class Versionomy::Format::Delimiter
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.
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.
# File lib/versionomy/format/delimiter.rb, line 87 def initialize(schema_, default_opts_={}, &block_) # Special case used by modified_copy if schema_.kind_of?(Delimiter) orig_ = schema_ @schema = orig_.schema @default_parse_params = orig_.default_parse_params @default_unparse_params = orig_.default_unparse_params @field_handlers = orig_.instance_variable_get(:@field_handlers).dup builder_ = Delimiter::Builder.new(@schema, @field_handlers, @default_parse_params, @default_unparse_params) ::Blockenspiel.invoke(block_, builder_) return end @schema = schema_ @field_handlers = {} @default_parse_params = {} @default_unparse_params = {} builder_ = Delimiter::Builder.new(@schema, @field_handlers, @default_parse_params, @default_unparse_params) ::Blockenspiel.invoke(block_, builder_) _interpret_field_lists(@default_unparse_params) @schema.names.each do |name_| @field_handlers[name_] ||= Delimiter::FieldHandler.new(@schema.field_named(name_), default_opts_) end end
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.
# File lib/versionomy/format/delimiter.rb, line 290 def default_parse_params @default_parse_params.dup end
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.
# File lib/versionomy/format/delimiter.rb, line 300 def default_unparse_params @default_unparse_params.dup end
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.
# File lib/versionomy/format/delimiter.rb, line 311 def modified_copy(&block_) Delimiter.new(self, &block_) end
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.
# File lib/versionomy/format/delimiter.rb, line 139 def parse(string_, params_=nil) parse_params_ = default_parse_params parse_params_.merge!(params_) if params_ parse_state_ = { :backtrack => nil, :string => string_, :values => {}, :unparse_params => {}, :field => @schema.root_field, :recognizer_index => 0, :previous_field_missing => false } while (field_ = parse_state_[:field]) handler_ = @field_handlers[field_.name] recognizer_ = handler_.get_recognizer(parse_state_[:recognizer_index]) parse_data_ = nil if recognizer_ parse_state_[:recognizer_index] += 1 parse_data_ = recognizer_.parse(parse_state_, parse_params_) if parse_data_ parse_state_[:previous_field_missing] = false if recognizer_.requires_next_field parse_state_ = { :backtrack => parse_state_, :string => parse_state_[:string], :values => parse_state_[:values].dup, :unparse_params => parse_state_[:unparse_params].dup, :field => parse_state_[:field], :recognizer_index => 0, :previous_field_missing => false, :next_field_required => true, } else parse_state_[:next_field_required] = false end end elsif parse_state_[:next_field_required] parse_state_ = parse_state_[:backtrack] else parse_data_ = [handler_.default_value, nil, nil, nil] parse_state_[:previous_field_missing] = true parse_state_[:next_field_required] = false end if parse_data_ parse_state_[:values][field_.name] = parse_data_[0] parse_state_[:string] = parse_data_[2] if parse_data_[2] parse_state_[:unparse_params].merge!(parse_data_[3]) if parse_data_[3] parse_state_[:field] = field_.child(parse_data_[0]) parse_state_[:recognizer_index] = 0 handler_.set_style_unparse_param(parse_data_[1], parse_state_[:unparse_params]) end end unparse_params_ = parse_state_[:unparse_params] if parse_state_[:string].length > 0 case parse_params_[:extra_characters] when :ignore # do nothing when :suffix unparse_params_[:suffix] = parse_state_[:string] else raise Errors::ParseError, "Extra characters: #{parse_state_[:string].inspect}" end end Value.new(parse_state_[:values], self, unparse_params_) end
Returns the schema understood by this format. This method is required by the Format contract.
# File lib/versionomy/format/delimiter.rb, line 118 def schema @schema end
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
.
# File lib/versionomy/format/delimiter.rb, line 245 def unparse(value_, params_=nil) unparse_params_ = value_.unparse_params || default_unparse_params _interpret_field_lists(unparse_params_) if params_ unparse_params_.merge!(params_) _interpret_field_lists(unparse_params_) end skipped_handler_list_ = nil requires_next_field_ = false string_ = '' value_.each_field_object do |field_, val_| handler_ = @field_handlers[field_.name] unparse_data_ = handler_.unparse(val_, unparse_params_, requires_next_field_) if unparse_data_ if skipped_handler_list_ && handler_.requires_previous_field skipped_handler_list_.each do |pair_| frag_ = pair_[0].unparse(pair_[1], unparse_params_, true) unless frag_ raise Errors::UnparseError, "Field #{field_.name} empty although a prerequisite for a later field" end string_ << frag_[0] end end skipped_handler_list_ = nil string_ << unparse_data_[0] requires_next_field_ = unparse_data_[1] else if handler_.requires_previous_field (skipped_handler_list_ ||= []) << [handler_, val_] else skipped_handler_list_ = [[handler_, val_]] end requires_next_field_ = false end end string_ << (unparse_params_[:suffix] || '') string_ end