class Versionomy::Format::Delimiter::Builder

Set or modify the default parameters used when parsing a value.

# File lib/versionomy/format/delimiter.rb, line 483
def default_parse_params(params_)
  @default_parse_params.merge!(params_)
end

Set or modify the default parameters used when unparsing a value.

# File lib/versionomy/format/delimiter.rb, line 490
def default_unparse_params(params_)
  @default_unparse_params.merge!(params_)
end

Specify how to handle a given field. You must pass the name of the field, a hash of options, and a block defining the handling of the field.

Within the block, you set up “recognizers” for various regular expression patterns. These recognizers are tested in order when parsing a version number.

The methods that can be called from the block are determined by the type of field. If the field is an integer field, the methods of Versionomy::Format::Delimiter::IntegerFieldBuilder can be called from the block. If the field is a string field, the methods of Versionomy::Format::Delimiter::StringFieldBuilder can be called. If the field is a symbolic field, the methods of Versionomy::Format::Delimiter::SymbolFieldBuilder can be called.

Options¶ ↑

The opts hash includes a number of options that control how the field is parsed.

Some of these are regular expressions that indicate what patterns are recognized by the parser. Regular expressions should be passed in as the string representation of the regular expression, not a Regexp object itself. For example, use the string '-' rather than the Regexp /-/ to recognize a hyphen delimiter.

The following options are recognized:

:default_value_optional

If set to true, this the field may be omitted in the unparsed (formatted) version number, if the value is the default value for this field. However, if the following field is present and set as :requires_previous_field, then this field is still unparsed even if it is its default value. For example, for a version number like “2.0.0”, often the third field is optional, but the first and second are required, so it will often be unparsed as “2.0”. Default is false.

:default_value

The actual value set for this field if it is omitted from the version string. Defaults to the field's schema default value, but that can be overridden here.

:case_sensitive

If set to true, the regexps are case-sensitive. Default is false.

:delimiter_regexp

The regular expression string for the pre-delimiter. This pattern must appear before the current value in the string, and is consumed when the field is parsed, but is not part of the value itself. Default is '.' to recognize a period.

:post_delimiter_regexp

The regular expression string for the post-delimiter. This pattern must appear before the current value in the string, and is consumed when the field is parsed, but is not part of the value itself. Default is '' to indicate no post-delimiter.

:expected_follower_regexp

The regular expression string for what characters are expected to follow this field in the string. These characters are not part of the field itself, and are not consumed when the field is parsed; however, they must be present immediately after this field in order for the field to be recognized. Default is '' to indicate that we aren't testing for any particular characters.

:default_delimiter

The default delimiter string. This is the string that is used to unparse a field value if the field was not present when the value was originally parsed. For example, if you parse the string “2.0”, bump the tiny version so that the value is “2.0.1”, and unparse, the unparsing won't receive the second period from parsing the original string, so its delimiter will use the default. Default value is '.'

:default_post_delimiter

The default post-delimiter string. Default value is '' indicating no post-delimiter.

:requires_previous_field

If set to true, this field's presence in a formatted version string requires the presence of the previous field. For example, in a typical version number “major.minor.tiny”, tiny should appear in the string only if minor also appears, so tiny should have this parameter set to true. The default is true, so you must specify :requires_previous_field => false explicitly if you want a field not to require the previous field.

:requires_next_field

If set to true, this field's presence in a formatted version string requires the presence of the next field. For example, in the version “1.0a5”, the release_type field requires the presence of the alpha_version field, because if the “5” was missing, the string “1.0a” looks like a patchlevel indicator. Often it is easier to set default_value_optional in the next field, but this option is also available if the behavior is dependent on the value of this previous field.

:default_style

The default style for this field. This is the style used for unparsing if the value was not constructed by a parser or is otherwise missing the style for this field.

Styles¶ ↑

A field may have different representation “styles”. For example, you could represent a patchlevel of 1 as “1.0-1” or “1.0a”. When a version number string is parsed, the parser and unparser work together to remember which style was parsed, and that style is used when the version number is unparsed.

Specify styles as options to the calls made within the block that is passed to this method. In the above case, you could define the patchlevel field with a block that has two calls, one that uses Versionomy::Format::Delimiter::IntegerFieldBuilder#recognize_number and passes the option :style => :number, and another that uses Versionomy::Format::Delimiter::IntegerFieldBuilder#recognize_letter and passes the option :style => :letter.

The standard format uses styles to preserve the different syntaxes for the release_type field. See the source code in Versionomy::Format::Standard#create for this example.

# File lib/versionomy/format/delimiter.rb, line 471
def field(name_, opts_={}, &block_)
  name_ = name_.to_sym
  field_ = @schema.field_named(name_)
  if !field_
    raise Errors::FormatCreationError, "Unknown field name #{name_.inspect}"
  end
  @field_handlers[name_] = Delimiter::FieldHandler.new(field_, opts_, &block_)
end