class CiteProc::Variable
A CiteProc
Variable
represents the content of a text, numeric, date, or name variable. In its basic form it is thin abstraction that behaves almost like a regular Ruby string; more complex Variables are handled by dedicated sub-classes that make the variable's type more explicit.
@abstract
Attributes
@!attribute [r] factories @return [{Symbol => Class}] mapping of field names to their respective
Variable classes
@!attribute [r] fields @return [{Symbol => Array
<Symbol>}] mapping of variable types to
their respective field names
@!attribute markup @return [Regexp] pattern used to strip markup off values
@!attribute [r] types @return [{Symbol => Symbol}] mapping of field names to variable types
@!attribute value @return [Object] the value wrapped by this variable
Public Class Methods
Creates a new {Variable} instance using the passed-in field name to distinguish which {Variable} class to use as factory. This method returns nil if the creation fails.
@see .create!
@example
Variable.create('foo') #-> #<CiteProc::Variable "foo"> Variable.create('foo', :title) #-> #<CiteProc::Text "foo"> Variable.create(['Matz', 'Flanagan'], :author) #-> #<CiteProc::Names "Matz & Flanagan"> Variable.create(2009, :issued) #-> #<CiteProc::Date "2009-01-01">
@param value [Object] the variable's value @param field [Symbol] the value's field name
@return [Variable] a new {Variable} (or sub-class) instance
# File lib/citeproc/variable.rb, line 104 def create(value, field = nil) create!(value, field) rescue nil end
Creates a new {Variable} instance using the passed-in field name to distinguish which {Variable} class to use as factory.
@see .create
@raise [TypeError] if no variable can be created for the given value
and type
@param value [Object] the variable's value @param field [Symbol] the variable's field name
@return [Variable] a new {Variable} (or sub-class) instance
# File lib/citeproc/variable.rb, line 123 def create!(value, field = nil) factory = factories[field] value.is_a?(factory) ? value : factory.new(value) end
Creates new Variable
for the passed-in value
# File lib/citeproc/variable.rb, line 143 def initialize(value = nil) replace(value) end
Public Instance Methods
Compares the variable with the passed-in value. If other responds to {#strip_markup} the stripped strings will be compared; otherwise both objects will be converted to and compared as strings.
@param other [Object] the object used for comparison @return [Fixnum,nil] -1, 0, or 1 depending on the result of the
comparison; or nil if the two objects cannot be ignored.
# File lib/citeproc/variable.rb, line 266 def <=>(other) case when other.respond_to?(:strip_markup) strip_markup <=> other.strip_markup when other && other.respond_to?(:to_s) to_s <=> other.to_s else nil end end
# File lib/citeproc/variable.rb, line 232 def date? false end
# File lib/citeproc/variable.rb, line 147 def initialize_copy(other) @value = other.value.dup end
@return [String] a human-readable representation of the variable
# File lib/citeproc/variable.rb, line 287 def inspect "#<#{self.class.name} #{to_s.inspect}>" end
Tests whether the variable contains numeric content. Content is considered numeric if it solely consists of numbers. Numbers may have prefixes and suffixes (“D2”, “2b”, “L2d”), and may be separated by a comma, hyphen, or ampersand, with or without spaces (“2, 3”, “2-4”, “2 & 4”). For example, “2nd” tests “true” whereas “second” and “2nd edition” test “false”.
@return [Boolean] whether or not the variable's value is numeric
# File lib/citeproc/variable.rb, line 228 def numeric? !!match(/^[\w\.:;]*\d+[\w\.:;]*(\s*[,&-]\s*[\w\.:;]*\d+[\w\.:;]*)*$/i) end
@return [Boolean] whether or not the variable holds a plural value
# File lib/citeproc/variable.rb, line 173 def plural? if numeric? Number.pluralize?(to_s) else false end end
The replace method is typically called by the Variable's constructor. It will try to set the Variable
to the passed in value and should accept a wide range of argument types; subclasses (especially Date
and Names
) override this method.
@raise [TypeError] if the variable cannot be set to the passed-in value
@param value [Object] the variable's new value @return [self]
# File lib/citeproc/variable.rb, line 161 def replace(value) raise TypeError, "failed to set value to #{value.inspect}" unless value.respond_to?(:to_s) @value = value.to_s self end
@return [String, nil] roman equivalent of the variable's numeric value
# File lib/citeproc/variable.rb, line 182 def romanize return unless numeric? Number.romanize(to_i) end
@return [String] the variable's value stripped of markup
# File lib/citeproc/variable.rb, line 249 def strip_markup gsub(Variable.markup, '') end
Strips markup off the variable's value. @return [self]
# File lib/citeproc/variable.rb, line 255 def strip_markup! gsub!(Variable.markup, '') end
@return [Float] the first (!) numeric or floating point data contained
in the variable's value; zero if no numeric data is present
# File lib/citeproc/variable.rb, line 244 def to_f to_s =~ /([+-]?\d[\d,\.]*)/ && $1.tr(',','.').to_f || 0.0 end
@return [Fixnum] the first (!) numeric data contained in the variable's
value; zero if no numeric data is present
# File lib/citeproc/variable.rb, line 238 def to_i to_s =~ /([+-]?\d+)/ && $1.to_i || 0 end
@return [String] a JSON string representation of the variable
# File lib/citeproc/variable.rb, line 282 def to_json ::JSON.dump(to_citeproc) end
Tokenizes the variable's value according to the rules of CSL number extraction. Note that this method returns an emtpy array unless the variable has numeric content.
@see numeric?
For numeric variables, this method normalizes delimiters and separators: numbers separated by a hyphen are stripped of intervening spaces (“2 - 4” becomes “2-4”). Numbers separated by a comma receive one space after the comma (“2,3” and “2 , 3” become “2, 3”), while numbers separated by an ampersand receive one space before and one after the ampsersand (“2&3” becomes “2 & 3”).
The array returned by this method contains all numbers and tokens as separate strings.
@example
Variable.new('2,3').tokenize #-> ['2', ', ', '3'] Variable.new('2 - 4').tokenize #-> ['2', '-', '4']
@return [Array<String>] tokenizes the variable's value
# File lib/citeproc/variable.rb, line 208 def tokenize return [] unless numeric? numbers = to_s.dup numbers.gsub!(/\s*,\s*/, ', ') numbers.gsub!(/\s*-\s*/, '-') numbers.gsub!(/\s*&\s*/, ' & ') numbers.split(/(\s*[,&-]\s*)/) end
@return [Symbol] the variable's type
# File lib/citeproc/variable.rb, line 168 def type @type ||= self.class.name.split(/::/)[-1].downcase.to_sym end