Refactor spec/version matching.

Instead of choosing the comparison on each `.match()` call, the
expression is converted to a combination of `Range()` expressions
(simple comparison to a semver-compliant `Version`).

`Range()` objects can be combined with `And` and `Or` through the
`AnyOf` and `AllOf` clauses (sticking to Python's naming scheme).

Some specific flags have been provided to those range, allowing users to
subtly alter the matching behaviour - thus accomodating different
versioning schemes:
- `<0.1.2` won't match `0.1.2-rc1`, unless the prerelease_policy flag is
  set to either `always` or `same-patch`
- `<0.1.2` will match `0.1.1-rc1`, unless the `prerelease_policy` flag
  is set to `same-patch`
- `==0.1.2` will always match `0.1.2+build44`, unless the `build_policy`
  is set to `strict`.

The `Spec` item has been updated, alongside `SpecItem`.
Those objects keep the original expression as attributes, but don't use
them for comparisons.

1 files changed, 23 insertions, 35 deletions

diff --git a/README.rst b/README.rst
index ac42f72..0d0d421 100644
--- a/README.rst
+++ b/README.rst
@@ -59,10 +59,13 @@ Import it in your code:
 
 .. currentmodule:: semantic_version
 
-This module provides two classes to handle semantic versions:
+This module provides classes to handle semantic versions:
 
 - :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``)
-- :class:`Spec` represents a requirement specification (``>=0.1.1,<0.3.0``)
+- :class:`BaseSpec`-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``):
+
+  - :class:`NativeSpec` describes a natural description syntax
+  - :class:`NpmSpec` is used for NPM-style range descriptions.
 
 Versions
 --------
@@ -168,12 +171,12 @@ In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be inte
 Requirement specification
 -------------------------
 
-The :class:`Spec` object describes a range of accepted versions:
+The :class:`NativeSpec` object describes a range of accepted versions:
 
 
 .. code-block:: pycon
 
-    >>> s = Spec('>=0.1.1')  # At least 0.1.1
+    >>> s = NativeSpec('>=0.1.1')  # At least 0.1.1
     >>> s.match(Version('0.1.1'))
     True
     >>> s.match(Version('0.1.1-alpha1'))  # pre-release satisfy version spec
@@ -185,42 +188,28 @@ Simpler test syntax is also available using the ``in`` keyword:
 
 .. code-block:: pycon
 
-    >>> s = Spec('==0.1.1')
+    >>> s = NativeSpec('==0.1.1')
     >>> Version('0.1.1-alpha1') in s
     True
     >>> Version('0.1.2') in s
     False
 
 
-Combining specifications can be expressed in two ways:
-
-- Components separated by commas in a single string:
-
-  .. code-block:: pycon
-
-      >>> Spec('>=0.1.1,<0.3.0')
-
-- Components given as different arguments:
+Combining specifications can be expressed as follows:
 
   .. code-block:: pycon
 
-      >>> Spec('>=0.1.1', '<0.3.0')
-
-- A mix of both versions:
-
-  .. code-block:: pycon
-
-      >>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0')
+      >>> NativeSpec('>=0.1.1,<0.3.0')
 
 
 Using a specification
 """""""""""""""""""""
 
-The :func:`Spec.filter` method filters an iterable of :class:`Version`:
+The :func:`NativeSpec.filter` method filters an iterable of :class:`Version`:
 
 .. code-block:: pycon
 
-    >>> s = Spec('>=0.1.0,<0.4.0')
+    >>> s = NativeSpec('>=0.1.0,<0.4.0')
     >>> versions = (Version('0.%d.0' % i) for i in range(6))
     >>> for v in s.filter(versions):
     ...     print v
@@ -233,7 +222,7 @@ It is also possible to select the 'best' version from such iterables:
 
 .. code-block:: pycon
 
-    >>> s = Spec('>=0.1.0,<0.4.0')
+    >>> s = NativeSpec('>=0.1.0,<0.4.0')
     >>> versions = (Version('0.%d.0' % i) for i in range(6))
     >>> s.select(versions)
     Version('0.3.0')
@@ -259,22 +248,21 @@ version-like string into a valid semver version:
 Including pre-release identifiers in specifications
 """""""""""""""""""""""""""""""""""""""""""""""""""
 
-When testing a :class:`Version` against a :class:`Spec`, comparisons are only
-performed for components defined in the :class:`Spec`; thus, a pre-release
-version (``1.0.0-alpha``), while not strictly equal to the non pre-release
-version (``1.0.0``), satisfies the ``==1.0.0`` :class:`Spec`.
+When testing a :class:`Version` against a :class:`NativeSpec`, comparisons are
+adjusted for common user expectations; thus, a pre-release version (``1.0.0-alpha``)
+will not satisfy the ``==1.0.0`` :class:`NativeSpec`.
 
-Pre-release identifiers will only be compared if included in the :class:`Spec`
+Pre-release identifiers will only be compared if included in the :class:`BaseSpec`
 definition or (for the empty pre-release number) if a single dash is appended
 (``1.0.0-``):
 
 
 .. code-block:: pycon
 
-    >>> Version('0.1.0-alpha') in Spec('>=0.1.0')  # No pre-release identifier
-    True
-    >>> Version('0.1.0-alpha') in Spec('>=0.1.0-')  # Include pre-release in checks
+    >>> Version('0.1.0-alpha') in NativeSpec('<0.1.0')  # No pre-release identifier
     False
+    >>> Version('0.1.0-alpha') in NativeSpec('<0.1.0-')  # Include pre-release in checks
+    True
 
 
 Including build metadata in specifications
@@ -286,9 +274,9 @@ build metadata is equality.
 
 .. code-block:: pycon
 
-    >>> Version('1.0.0+build2') in Spec('<=1.0.0')   # Build metadata ignored
+    >>> Version('1.0.0+build2') in NativeSpec('<=1.0.0')   # Build metadata ignored
     True
-    >>> Version('1.0.0+build2') in Spec('==1.0.0+build2')  # Include build in checks
+    >>> Version('1.0.0+build1') in NativeSpec('==1.0.0+build2')  # Include build in checks
     False
 
 
@@ -296,7 +284,7 @@ Using with Django
 =================
 
 The :mod:`semantic_version.django_fields` module provides django fields to
-store :class:`Version` or :class:`Spec` objects.
+store :class:`Version` or :class:`BaseSpec` objects.
 
 More documentation is available in the :doc:`django` section.