Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation updates; updated YAML tag

  • Loading branch information...
commit d5d11a524c2b2d9ea3a5c8a6c1e544940338bb71 1 parent 57c5ebe
@dazuma authored
View
3  History.rdoc
@@ -1,10 +1,11 @@
-=== 0.3.0 / 2009-12-??
+=== 0.3.0 / 2009-11-30
* Alpha release, opened for public feedback
* Autoloading of format definitions using a load path.
* Format and conversion registry/lookup is now thread-safe.
* Implemented resetting a particular field in the value.
* Implemented aliases for field names.
+* Changed the canonical YAML tag to its permanent value. The old one will continue to be recognized, but only the permanent one will be written from now on.
* Documentation updates
=== 0.2.5 / 2009-11-24
View
32 README.rdoc
@@ -4,35 +4,9 @@ Versionomy is a generalized version number library.
It provides tools to represent, manipulate, parse, and compare version
numbers in the wide variety of versioning schemes in use.
-=== Version numbers done right?
-
-Let's be honest. Version numbers are not easy to deal with, and very
-seldom seem to be done right.
-
-Imagine the common case of testing the Ruby version. Most of us, if we
-need to worry about Ruby VM compatibility, will do something like:
-
- do_something if RUBY_VERSION >= "1.8.7"
-
-Treating the version number as a string works well enough, until it
-doesn't. The above code will do the right thing for Ruby 1.8.6, 1.8.7,
-1.8.8, and 1.9.1. But it will fail if the version is "1.8.10" or "1.10".
-And properly interpreting "prerelease" version syntax such as
-"1.9.2-preview1"? Forget it.
-
-There are a few version number classes out there that do better than
-treating version numbers as plain strings. One example is Gem::Version,
-part of the RubyGems package. This class separates the version into fields
-and lets you manipulate and compare version numbers more robustly. It even
-provides limited support for "prerelease" versions through using string-
-valued fields-- although it's a hack, and a bit of a clumsy one at that. A
-prerelease version has to be represented like this: "1.9.2.b.1" or
-"1.9.2.preview.2". Wouldn't it be nice to be able to parse more typical
-version number formats such as "1.9.2b1" and "1.9.2-preview2"? Wouldn't
-it be nice for a version like "1.9.2b1" to _understand_ that it's a "beta"
-version and behave accordingly?
-
-With Versionomy, you can do all this and more.
+This document summarizes the features of Versionomy with a quick synopsis
+and feature list. For more detailed usage information and examples, see
+{Versionomy.rdoc}[link:Versionomy\_rdoc.html].
=== Some examples
View
2  Rakefile
@@ -45,7 +45,7 @@ require File.expand_path("#{File.dirname(__FILE__)}/lib/versionomy.rb")
# Configuration
-extra_rdoc_files_ = ['README.rdoc', 'History.rdoc']
+extra_rdoc_files_ = ['README.rdoc', 'Versionomy.rdoc', 'History.rdoc']
# Default task
View
346 Versionomy.rdoc
@@ -0,0 +1,346 @@
+== Versionomy
+
+Versionomy is a generalized version number library.
+It provides tools to represent, manipulate, parse, and compare version
+numbers in the wide variety of versioning schemes in use.
+
+This document provides a step-by-step introduction to most of the features
+of Versionomy.
+
+=== Version numbers done right?
+
+Let's be honest. Version numbers are not easy to deal with, and very
+seldom seem to be done right.
+
+Imagine the common case of testing the Ruby version. Most of us, if we
+need to worry about Ruby VM compatibility, will do something like:
+
+ do_something if RUBY_VERSION >= "1.8.7"
+
+Treating the version number as a string works well enough, until it
+doesn't. The above code will do the right thing for Ruby 1.8.6, 1.8.7,
+1.8.8, and 1.9.1. But it will fail if the version is "1.8.10" or "1.10".
+And properly interpreting "prerelease" version syntax such as
+"1.9.2-preview1"? Forget it.
+
+There are a few version number classes out there that do better than
+treating version numbers as plain strings. One example is Gem::Version,
+part of the RubyGems package. This class separates the version into fields
+and lets you manipulate and compare version numbers more robustly. It even
+provides limited support for "prerelease" versions through using string-
+valued fields-- although it's a hack, and a bit of a clumsy one at that. A
+prerelease version has to be represented like this: "1.9.2.b.1" or
+"1.9.2.preview.2". Wouldn't it be nice to be able to parse more typical
+version number formats such as "1.9.2b1" and "1.9.2-preview2"? Wouldn't
+it be nice for a version like "1.9.2b1" to _understand_ that it's a "beta"
+version and behave accordingly?
+
+With Versionomy, you can do all this and more. Here's how...
+
+=== Creating version numbers
+
+Creating a version number object in Versionomy is as simple as passing a
+string to a factory. Versionomy understands a wide range of version number
+formats out of the box.
+
+ v1 = Versionomy.parse('1.2') # Simple version numbers
+ v2 = Versionomy.parse('2.1.5.0') # Up to four fields supported
+ v3 = Versionomy.parse('1.9b3') # Alpha and beta versions
+ v4 = Versionomy.parse('1.9rc2') # Release candidates too
+ v5 = Versionomy.parse('1.9.2-preview2') # Preview releases
+ v6 = Versionomy.parse('1.9.2-p6') # Patchlevels
+ v7 = Versionomy.parse('v2.0 beta 6.1') # Many alternative syntaxes
+
+You can also construct version numbers manually by passing a hash of field
+values. See the next section for a discussion of fields.
+
+ v1 = Versionomy.create(:major => 1, :minor => 2) # creates version "1.2"
+ v2 = Versionomy.create(:major => 1, :minor => 9,
+ :release_type => :beta, :beta_version => 3) # creates version "1.9b3"
+
+The current ruby virtual machine version can be obtained using:
+
+ v1 = Versionomy.ruby_version
+
+Many other libraries include their version as a string constant in their
+main namespace module. Versionomy provides a quick facility to attempt to
+extract the version of a library:
+
+ require 'nokogiri'
+ v1 = Versionomy.version_of(Nokogiri)
+
+=== Version number fields
+
+A version number is a collection of fields in a particular order. Standard
+version numbers have the following fields:
+
+* :major
+* :minor
+* :tiny
+* :tiny2
+* :release_type
+
+The first four fields correspond to the four numeric fields of the version
+number. E.g. version numbers have the form "major.minor.tiny.tiny2".
+Trailing fields that have a zero value may be omitted from a string
+representation, but are still present in the Versionomy::Value object.
+
+The fifth field is special. Its value is one of the following symbols:
+
+* :development
+* :alpha
+* :beta
+* :release_candidate
+* :preview
+* :final
+
+The value of the :release_type field determines which other fields are
+available in the version number. If the :release_type is :development, then
+the two fields :development_version and :development_minor are available.
+Similarly, if :release_type is :alpha, then the two fields :alpha_version
+and :alpha_minor are available, and so on. If :release_type is :final, that
+exposes the two fields :patchlevel and :patchlevel_minor.
+
+You can query a field value simply by calling a method on the value:
+
+ v1 = Versionomy.parse('1.2b3')
+ v1.major # => 1
+ v1.minor # => 2
+ v1.tiny # => 0
+ v1.tiny2 # => 0
+ v1.release_type # => :beta
+ v1.beta_version # => 3
+ v1.beta_minor # => 0
+ v1.release_candidate_version # raises NoMethodError
+
+The above fields are merely the standard fields that Versionomy provides
+out of the box. Versionomy also provides advanced users the ability to
+define new version "schemas" with any number of different fields and
+different semantics. See the RDocs for Versionomy::Schema for more
+information.
+
+=== Version number calculations
+
+Version numbers can be compared (and thus sorted). Versionomy knows how to
+handle prerelease versions and patchlevels correctly. It also compares the
+semantic value so even if versions use an alternate syntax, they will be
+compared correctly. Each of these expressions evaluates to true:
+
+ Versionomy.parse('1.2') < Versionomy.parse('1.10')
+ Versionomy.parse('1.2') > Versionomy.parse('1.2b3')
+ Versionomy.parse('1.2b3') > Versionomy.parse('1.2a4')
+ Versionomy.parse('1.2') < Versionomy.parse('1.2-p1')
+ Versionomy.parse('1.2') == Versionomy.parse('1.2-p0')
+ Versionomy.parse('1.2b3') == Versionomy.parse('1.2.0-beta3')
+
+Versionomy automatically converts (parses) strings when comparing with a
+version number, so you could even evaluate these:
+
+ Versionomy.parse('1.2') < '1.10'
+ Versionomy::VERSION > '0.2'
+
+The Versionomy API provides various methods for manipulating fields such as
+bumping, resetting to default, and changing to an arbitrary value. Version
+numbers are always immutable, so changing a version number always produces
+a copy. Below are a few examples. See the RDocs for the class
+Versionomy::Value for more details.
+
+ v_orig = Versionomy.parse('1.2b3')
+ v1 = v_orig.change(:beta_version => 4) # creates version "1.2b4"
+ v2 = v_orig.change(:tiny => 4) # creates version "1.2.4b3"
+ v3 = v_orig.bump(:minor) # creates version "1.3"
+ v4 = v_orig.bump(:release_type) # creates version "1.2rc1"
+ v5 = v_orig.reset(:minor) # creates version "1.0"
+
+A few more common calculations are also provided:
+
+ v_orig = Versionomy.parse('1.2b3')
+ v_orig.prerelease? # => true
+ v6 = v_orig.release # creates version "1.2"
+
+=== Parsing and unparsing
+
+Versionomy's parsing and unparsing services appear simple from the outside,
+but a closer look reveals some sophisticated features. Parsing is as simple
+as passing a string to Versionomy#parse, and unparsing is as simple as
+calling Versionomy::Value#unparse or Versionomy::Value#to_s.
+
+ v = Versionomy.parse('1.2b3') # Create a Versionomy::Value
+ v.unparse # => "1.2b3"
+
+Versionomy does its best to preserve the original syntax when parsing a
+version string, so that syntax can be used when unparsing.
+
+ v1 = Versionomy.parse('1.2b3')
+ v2 = Versionomy.parse('1.2.0-beta3')
+ v1 == b2 # => true
+ v1.unparse # => "1.2b3"
+ v2.unparse # => "1.2.0-beta3"
+
+Versionomy even preserves the original syntax when changing a value:
+
+ v1 = Versionomy.parse('1.2b3')
+ v2 = Versionomy.parse('1.2.0.0b3')
+ v1 == v2 # => true
+ v1r = v1.release
+ v2r = v2.release
+ v1r == v2r # => true
+ v1r.unparse # => "1.2"
+ v2r.unparse # => "1.2.0.0"
+
+You can change the settings manually when unparsing a value.
+
+ v1 = Versionomy.parse('1.2b3')
+ v1.unparse # => "1.2b3"
+ v1.unparse(:required_fields => :tiny) # => "1.2.0b3"
+ v1.unparse(:release_type_delim => '-',
+ :release_type_style => :long) # => "1.2-beta3"
+
+Versionomy also supports serialization using Marshal and YAML.
+
+ require 'yaml'
+ v1 = Versionomy.parse('1.2b3')
+ v1.unparse # => "1.2b3"
+ str = v1.to_yaml
+ v2 = YAML.load(str)
+ v2.unparse # => "1.2b3"
+
+=== Customized formats
+
+Although the standard parser used by Versionomy is likely sufficient for
+most common syntaxes, Versionomy also lets you customize the parser for an
+unusual syntax. Here is an example of a customized formatter for version
+numbers used by a certain large software company:
+
+ year_sp_format = Versionomy.default_format.modified_copy do
+ field(:minor) do
+ recognize_number(:default_value_optional => true,
+ :delimiter_regexp => '\s?sp',
+ :default_delimiter => ' SP')
+ end
+ end
+ v1 = year_sp_format.parse('2008 SP2')
+ v1.major # => 2008
+ v1.minor # => 2
+ v1.unparse # => "2008 SP2"
+ v1 == "2008.2" # => true
+ v2 = v1.bump(:minor)
+ v2.unparse # => "2008 SP3"
+
+The above example uses a powerful DSL provided by Versionomy to create a
+specialized parser. In most cases, this DSL will be powerful enough to
+handle your parsing needs; in fact Versionomy's entire standard parser is
+written using the DSL. However, in case you need to parse very unusual
+syntax, you can also write an arbitrary parser. See the RDocs for the
+Versionomy::Format::Delimiter class for more information on the DSL. See
+the RDocs for the Versionomy::Format::Base class for information on the
+interface you need to implement to write an arbitrary parser.
+
+If you create a format, you can register it with Versionomy and provide a
+name for it. This will allow you to reference it easily, as well as allow
+Versionomy to serialize versions created with your custom format. See the
+RDocs for the Versionomy::Format module for more information.
+
+ Versionomy::Format.register("bigcompany.versionformat", year_sp_format)
+ v1 = Versionomy.parse("2009 SP1", "bigcompany.versionformat")
+
+Note that versions in the year_sp_format example can be compared with
+versions using the standard parser. This is because the versions actually
+share the same schema-- that is, they have the same fields. We have merely
+changed the parser.
+
+Recall that it is also possible to change the schema (the fields). This is
+also done via a DSL (see the Versionomy::Schema module and its contents).
+Version numbers with different schemas cannot normally be compared, because
+they have different fields and different semantics. You can, however,
+define ways to convert version numbers from one schema to another. See the
+Versionomy::Conversion module and its contents for details.
+
+Versionomy provides an example of a custom schema with its own custom
+format, designed to mimic the Rubygems version class. This can be accessed
+using the format registered under the name "rubygems". Conversion functions
+are also provided between the rubygems and standard schemas.
+
+ v1 = Versionomy.parse("1.2b3") # Standard schema/format
+ v2 = Versionomy.parse("1.2.b.4", :rubygems) # Rubygems schema/format
+ v2.field0 # => 1
+ # (Rubygems fields have different names)
+ v1a = v1.convert(:rubygems) # creates rubygems version "1.2.b.3"
+ v2a = v2.convert(:standard) # creates standard version "1.2b4"
+ v1 < v2 # => true
+ # (Schemas are different but Versionomy
+ # autoconverts if possible)
+ v2 < v1 # => false
+ v3 = Versionomy.parse("1.2.foo", :rubygems) # rubygems schema/format
+ v3a = v3.convert(:standard) # raises Versionomy::Errors::ConversionError
+ # (Value not convertable to standard)
+ v1 < v3 # raises Versionomy::Errors::SchemaMismatchError
+ # (Autoconversion failed)
+ v3 > v1 # => true
+ # (Autoconversion is attempted only on the
+ # the second value, and this one succeeds.)
+
+The APIs for defining schemas, formats, and conversions are rather complex.
+I recommend looking through the examples in the modules
+Versionomy::Format::Standard, Versionomy::Format::Rubygems, and
+Versionomy::Conversion::Rubygems for further information.
+
+=== Requirements
+
+* Ruby 1.8.6 or later (1.8.7 recommended), Ruby 1.9.1 or later, or JRuby
+ 1.4 or later.
+* blockenspiel 0.3.1 or later.
+
+=== Installation
+
+ gem install versionomy
+
+=== Known issues and limitations
+
+* Test coverage is still a little skimpy. It is focused on the "standard"
+ version number format and schema, but doesn't fully exercise all the
+ capabilities of custom formats.
+
+=== Development and support
+
+Documentation is available at http://virtuoso.rubyforge.org/versionomy/README_rdoc.html
+
+Source code is hosted on Github at http://github.com/dazuma/versionomy
+
+Report bugs on Github issues at http://github.org/dazuma/versionomy/issues
+
+Contact the author at dazuma at gmail dot com.
+
+=== Author / Credits
+
+Versionomy is written by Daniel Azuma (http://www.daniel-azuma.com/).
+
+== LICENSE:
+
+Copyright 2008-2009 Daniel Azuma.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+* Neither the name of the copyright holder, nor the names of any other
+ contributors to this software, may be used to endorse or promote products
+ derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
View
2  lib/versionomy/value.rb
@@ -150,7 +150,9 @@ def marshal_load(data_) # :nodoc:
end
+ # YAML tags. The last one is the canonical one.
yaml_as "tag:danielazuma.com,2009:version"
+ yaml_as "tag:verse15.com,2009:version"
# Deserialize a version number from YAML
Please sign in to comment.
Something went wrong with that request. Please try again.