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

factories[R]

@!attribute [r] factories @return [{Symbol => Class}] mapping of field names to their respective

Variable classes
fields[R]

@!attribute [r] fields @return [{Symbol => Array<Symbol>}] mapping of variable types to

their respective field names
markup[RW]

@!attribute markup @return [Regexp] pattern used to strip markup off values

types[R]

@!attribute [r] types @return [{Symbol => Symbol}] mapping of field names to variable types

value[RW]

@!attribute value @return [Object] the value wrapped by this variable

Public Class Methods

create(value, field = nil) click to toggle source

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
create!(value, field = nil) click to toggle source

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
new(value = nil) click to toggle source

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

<=>(other) click to toggle source

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
date?() click to toggle source
# File lib/citeproc/variable.rb, line 232
def date?
  false
end
extract_numbers()
Alias for: tokenize
initialize_copy(other) click to toggle source
# File lib/citeproc/variable.rb, line 147
def initialize_copy(other)
  @value = other.value.dup
end
inspect() click to toggle source

@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
numeric?() click to toggle source

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
plural?() click to toggle source

@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
replace(value) click to toggle source

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
romanize() click to toggle source

@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
strip_markup() click to toggle source

@return [String] the variable’s value stripped of markup

# File lib/citeproc/variable.rb, line 249
def strip_markup
  gsub(Variable.markup, '')
end
strip_markup!() click to toggle source

Strips markup off the variable’s value. @return [self]

# File lib/citeproc/variable.rb, line 255
def strip_markup!
  gsub!(Variable.markup, '')
end
to_f() click to toggle source

@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
to_i() click to toggle source

@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
to_json() click to toggle source

@return [String] a JSON string representation of the variable

# File lib/citeproc/variable.rb, line 282
def to_json
  ::JSON.dump(to_citeproc)
end
tokenize() click to toggle source

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
Also aliased as: extract_numbers
type() click to toggle source

@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