Class Versionomy::Format::Delimiter
In: lib/versionomy/format/delimiter.rb
Parent: Base

The Delimiter format class provides a DSL for building formats that can handle most cases where the fields of a version number appear consecutively in order in the string formatting. We expect most version number schemes should fall into this category.

In general, the strategy is to provide, for each field, a set of regular expressions that recognize different formats for that field. Every field must be of the form "(pre)(value)(post)" where (pre) and (post) are delimiters preceding and following the value. Either or both delimiters may be the empty string.

To parse a string, the string is scanned from left to right and matched against the format for the fields in order. If the string matches, that part of the string is consumed and the field value is interpreted from it. If the string does not match, and the field is not marked as "required", then the field is set to its default value and the next field is tried.

During parsing, the actual delimiters, along with other information such as whether or not fields are required, are saved into a default set of parameters for unparsing. These are saved in the unparse_params of the version value, so that the version number can be unparsed in generally the same form. If the version number value is modified, this allows the unparsing of the new value to generally follow the format of the original string.

Formats that use the Delimiter mechanism also provide support for certain parsing and unparsing parameters. See the documentation for the parse and unparse methods for details.

For a usage example, see the definition of the standard format in Versionomy::Format::Standard#create.

Methods

Classes and Modules

Class Versionomy::Format::Delimiter::Builder
Class Versionomy::Format::Delimiter::IntegerFieldBuilder
Class Versionomy::Format::Delimiter::MappingSymbolBuilder
Class Versionomy::Format::Delimiter::StringFieldBuilder
Class Versionomy::Format::Delimiter::SymbolFieldBuilder

Public Class methods

Create a format using delimiter tools. You should provide the version number schema, a set of default options, and a block.

Within the block, you can call methods of Versionomy::Format::Delimiter::Builder to provide parsers for the fields of the schema. Any fields you do not explicitly configure will get parsed in a default manner.

Public Instance methods

Return a copy of the default parsing parameters used by this format. This hash cannot be edited in place. To modify the default parsing parameters, use modified_copy and call Versionomy::Format::Delimiter::Builder#default_parse_params in the block.

Return a copy of the default unparsing parameters used by this format. This hash cannot be edited in place. To modify the default unparsing parameters, use modified_copy and call Versionomy::Format::Delimiter::Builder#default_unparse_params in the block.

Create a copy of this format, with the modifications given in the provided block. You can call methods of Versionomy::Format::Delimiter::Builder in the block. Field handlers that you specify in that block will override and change the field handlers from the original. Any fields not specified in this block will use the handlers from the original.

Parse the given string and return a value. This method is required by the Format contract.

This method provides, out of the box, support for the following parse parameters:

:extra_characters:Determines what to do if the entire string cannot be consumed by the parsing process. If set to :ignore, any extra characters are ignored. If set to :suffix, the extra characters are set as the :suffix unparse parameter and are thus appended to the end of the string when unparsing takes place. If set to :error (the default), causes a Versionomy::Errors::ParseError to be raised if there are uninterpreted characters.

Returns the schema understood by this format. This method is required by the Format contract.

Unparse the given value and return a string. This method is required by the Format contract.

This method provides, out of the box, support for the following unparse parameters:

:suffix:A string to append to the unparsed string. Default is nothing.
:required_fields:An array of field names that must be present in the unparsed string. These are generally fields with default_value_optional set, but that we want present in the string anyway. For example, in the version number "2.0.0", often the third field will be default_value_optional, but we can include it in the required fields passed to unparse to force it to appear in the string.
:optional_fields:An array of field names that should have their presence in required_fields undone.
:fieldname_required:This is an alternate way of specifying whether a potentially optional field should be required. Accepted values are true and false.
:fieldname_style:Specify the style for unparsing the given field. See Versionomy::Format::Delimiter::Builder#field for more discussion of styles.
:fieldname_delim:Set the pre-delimiter for the given field, if supported. Note that the string specified must be legal— it must match the regexp for the field. If not, it will revert to the default.
:fieldname_postdelim:Set the post-delimiter for the given field, if supported. Note that the string specified must be legal— it must match the regexp for the field. If not, it will revert to the default.
:fieldname_case:This is used by letter-formatted integer fields only, and sets the case to use while unparsing. Recognized values are :lower (the default), and :upper.

[Validate]