=============================================================================
                                    Amock
=============================================================================
-----------------------------------------------------------------------------
                       Mock objects library for PHP 5
-----------------------------------------------------------------------------

:Author: Roman Neuhauser
:Contact: neuhauser@sigpipe.cz
:Copyright: This document has been placed in the public domain.
:Id: $Id: README.rest 267 2006-12-12 21:19:58Z roman $
:HeadURL: $HeadURL: https://svn.sigpipe.cz/r/trunk/amock/README.rest $

.. contents::

Introduction
============

Amock is an `open-source`_ mocking library written in `PHP 5`_ for
programs written in PHP 5. Mock objects for classes or interfaces
are generated on the fly using a source code generator.

Amock is published under the `MIT license`_ which means you are free and
welcome to use it in any way.  

.. _open-source: http://opensource.org/docs/definition.php
.. _MIT license: http://opensource.org/licenses/mit-license.php
.. _PHP 5:       http://www.php.net/

Amock is an essential ingredient in BEER_.

.. _BEER: http://beer.sigpipe.cz/


Prerequisities
==============

* PHP >= 5.1.3


Downloads
=========

Repository
++++++++++

The latest source get be checked out from the Subversion_ repository_,
which is also available for anonymous browsing using the viewvc_ interface_. 

.. _Subversion: http://subversion.tigris.org/
.. _repository: https://svn.sigpipe.cz/r/
.. _viewvc:     http://www.viewvc.org/
.. _interface:  http://svn.sigpipe.cz/

Official tarballs
+++++++++++++++++

Amock source releases are distributed as bzip2ed tarballs created with
either Tim Kientzle's bsdtar_ or GNU tar, Julian Seward's bzip2_ in all cases.
Your operating system should include compatible extraction tools.

All Amock releases can be found in the `download directory`_.

.. _bsdtar: http://people.freebsd.org/~kientzle/libarchive/
.. _bzip2: http://www.bzip.org/
.. _download directory: http://www.amock.org/dist/


Build and Installation
======================

From a package
++++++++++++++

The most comfortable way to install Amock is using your operating
system's packaging system. Ask your OS vendor for a package of the latest
Amock release.

The source distribution includes a FreeBSD port skeleton.

From the source
+++++++++++++++

Wash and Go instructions
------------------------

::

    % url=http://www.amock.org/dist/amock-x.y.x.tar.gz
    % fetch -o - $url | tar -xzf -
    % cd amock-x.y.z
    % make check install

Detailed description
--------------------

The build and installation process can be configured using a number of
variables. Use the help target to display builtin help. ::

    % make help
    these targets display help for individual topics:

    help-targets:  help for targets
    help-var:      help for variables
    %

Functionality not described in the builtin help should be considered
implementation details. If the documented features don't support all your
configuration needs, please do send a feature request.

Amock is tested on FreeBSD 6 with the system make (should work on any
BSD) and GNU make.

Running the test suite
~~~~~~~~~~~~~~~~~~~~~~

Amock's Testilence_-based test suite can be exercised with or without
installed Amock by running ``make check`` or ``make maint-check``
in the source directory.  The former target excludes tests that use
filesystem or other external resources, because a bug in Amock might
prevent proper cleanup or (although unlikely) *delete your files*.

The test suite is described in more detail further below.

.. _Testilence: http://www.testilence.org/

Reference
=========

Overview
++++++++

Library
+++++++


Examples
========

Releases
========

Release types
+++++++++++++

Amock releases fall into one of the following four categories:

* snapshots
* bugfix releases
* new functionality
* backward-incompatible change

Release versioning
++++++++++++++++++

Each release is tagged with a version number string with the following
structure (ABNF_): ::

    version-string    = compat-cnt "." newfun-cnt "." bugfix-cnt [rel-candidate]
    compat-cnt    = counter
    newfun-cnt    = counter
    bugfix-cnt    = counter
    rel-candidate = "." snapshot counter
    ; "snap"
    snapshot          = %x73.6e.61.70
    ; counter is a positive integer (includes 0)
    counter            = 1 * DIGIT

For each release of any type the appropriate counter is incremented by at
least one and counters to the right of it are reset to 0 (the
release-candidate part is removed altogether), while counters to the left of
it are left at their current values.

Version string of the first nonsnapshot Amock release is ``0.0.0``, while
"0.0.0.snap135" is the version string of a pre-0.0.0 snapshot.  Note that
there may be gaps between.

This handling is consistent with the way FreeBSD's `pkg_version -t`_
interprets version strings.

.. _ABNF: http://tools.ietf.org/html/rfc4234
.. _pkg_version -t: http://www.freebsd.org/cgi/man.cgi?query=pkg_version


Test suite
==========

The suite is organized around Amock's classes, meaning there is one or
more cases per class under test. These are in turn organized into suites,
possibly multiple levels of them. Any part of the resulting tree can be run.

.. target-notes::

.. section-numbering::