Class: CSL::Locale

Inherits:
Node show all
Extended by:
Loader
Includes:
Comparable
Defined in:
lib/csl/locale.rb,
lib/csl/locale/date.rb,
lib/csl/locale/term.rb,
lib/csl/locale/style_options.rb

Overview

CSL::Locales contain locale specific date formatting options, term translations, and a number ordinalizer.

Defined Under Namespace

Classes: Date, DatePart, StyleOptions, Term, Terms

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from Loader

#extension, #prefix, #root

Attributes inherited from Node

#attributes

Attributes included from Treelike

#children, #nodename, #parent

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Loader

extend_name, extend_path, list, load

Methods inherited from Node

#attribute?, #attributes?, #attributes_for, constantize, create, create_attributes, #custom_attributes, #deep_copy, #default_attribute?, #default_attributes, default_attributes, #each, #exact_match?, #formatting_options, #has_attributes?, #has_default_attributes?, #has_language?, hide_default_attributes!, hide_default_attributes?, match?, #match?, matches?, parse, parse!, #save_to, show_default_attributes!, #tags, #textnode?, types

Methods included from PrettyPrinter

#pretty_print, #tags, #to_xml

Methods included from Treelike

#<<, #add_child, #add_children, #ancestors, #delete_child, #delete_children, #depth, #descendants, #each_ancestor, #each_child, #each_descendant, #each_sibling, #empty?, #find_child, #find_children, #has_children?, #root, #root?, #siblings, #unlink

Constructor Details

#initialize(*arguments) {|_self| ... } ⇒ Locale

Returns a new locale. In the first form, the language/regions is set to the default language and region. In the second form the language/region is set by the passed-in IETF tag. The third form additionally accepts a hash of localize style-options. The fourth form is the standard node attribute initialize signature.

Examples:

Locale.new                                         #-> default
Locale.new('en')                                   #-> American English
Locale.new('en', :'punctuation-in-quote' => false) #-> with style-options
Locale.new(:lang => 'en-GB', :version => '1.0')    #-> British English

Yields:

  • (_self)

Yield Parameters:

  • _self (CSL::Locale) —

    the object that the method was called on



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/csl/locale.rb', line 105

def initialize(*arguments)
  case arguments.length
  when 0
    locale, attributes, options = Locale.default, {}, nil
  when 1
    if arguments[0].is_a?(Hash)
      arguments[0] = arguments[0].symbolize_keys

      locale = arguments[0].delete(:lang) ||
        arguments[0].delete(:'xml:lang') || Locale.default

      attributes, options = arguments
    else
      attributes, locale, options = {}, *arguments
    end
  when 2
    attributes, locale, options = {}, *arguments
  else
    raise ArgumentError, "wrong number of arguments (#{arguments.length} for 0..2)"
  end

  super(attributes, &nil)

  set(locale) unless locale.nil?

  unless options.nil?
    children[:'style-options'] = StyleOptions.new(options)
  end

  yield self if block_given?
end

Class Attribute Details

.default ⇒ Object

Returns the value of attribute default.



37
38
39
 
# File 'lib/csl/locale.rb', line 37

def default
  @default
end

.languages ⇒ Object (readonly)

Returns the value of attribute languages.



38
39
40
 
# File 'lib/csl/locale.rb', line 38

def languages
  @languages
end

.regions ⇒ Object (readonly)

Returns the value of attribute regions.



38
39
40
 
# File 'lib/csl/locale.rb', line 38

def regions
  @regions
end

Instance Attribute Details

#region ⇒ Object

Returns the value of attribute region.



85
86
87
 
# File 'lib/csl/locale.rb', line 85

def region
  @region
end

Class Method Details

.load(input = Locale.default) ⇒ Object 



40
41
42
43
 
# File 'lib/csl/locale.rb', line 40

def load(input = Locale.default)
  input = normalize input if input.to_s =~ tag_pattern
  super
end

.normalize(tag) ⇒ String

Normalizes an IETF tag; adds a language’s default region or a region’s default language.

Examples:

Locale.normalize("en")  #-> "en-US"
Locale.normalize("-BR") #-> "pt-BR"

Parameters:

  • tag (String) —

    an IETF tag to be normalized

Returns:

  • (String) —

    the normalized IETF tag

Raises:

  • (ArgumentError) —

    if the passed-in string is no IETF tag



56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/csl/locale.rb', line 56

def normalize(tag)
  tag = tag.to_s.strip

  raise ArgumentError, "not a valid IETF tag: #{tag.inspect}" unless
    tag =~ tag_pattern

  language, region = tag.split(/-/)

  return [language, regions[language.to_sym]].compact.join('-') if region.nil?
  return [languages[region.to_sym], region].join('-') if language.empty?

  tag
end

Instance Method Details

#<=>(other) ⇒ 1, ...

Locales are sorted first by language, then by region; sort order is alphabetical with the following exceptions: the default locale is prioritised; in case of a language match the default region of that language will be prioritised (e.g., de-DE will come before de-AT even though the alphabetical order would be different).

Parameters:

  • other (Locale) —

    the locale used for comparison

Returns:

  • (1, 0, -1, nil) —

    the result of the comparison



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'lib/csl/locale.rb', line 331

def <=>(other)
  case
  when !other.is_a?(Locale)
    nil
  when [language, region] == [other.language, other.region]
    0
  when default?
    -1
  when other.default?
    1
  when language == other.language
    case
    when default_region?
      -1
    when other.default_region?
      1
    else
      region <=> other.region
    end
  else
    language <=> other.language
  end
end

#added_to(node) ⇒ Object

Raises:



143
144
145
146
 
# File 'lib/csl/locale.rb', line 143

def added_to(node)
  raise ValidationError, "not allowed to add locale to #{node.nodename}" unless
    node.nodename == 'style'
end

#clear ⇒ self

Sets the locale’s language and region to nil.

Returns:

  • (self) 


196
197
198
199
 
# File 'lib/csl/locale.rb', line 196

def clear
  @language, @region = nil
  self
end

#default? ⇒ Boolean

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/csl/locale.rb', line 283

def default?
  to_s == Locale.default
end

#default_language? ⇒ Boolean

Returns whether or not the Locale’s language is the default language for its region.

Returns:

  • (Boolean) —

    whether or not the Locale’s language is the default language for its region



295
296
297
 
# File 'lib/csl/locale.rb', line 295

def default_language?
  language && language == Locale.languages[region]
end

#default_region? ⇒ Boolean

Returns whehter or not the Locale’s region is the default region for its language.

Returns:

  • (Boolean) —

    whehter or not the Locale’s region is the default region for its language



289
290
291
 
# File 'lib/csl/locale.rb', line 289

def default_region?
  region && region == Locale.regions[language]
end

#each_date ⇒ Object

Calls block once for each date format defined by the locale. If no block is given, an enumerator is returned instead.

Examples:

locale.each_date { |date_format| block } #-> locale
locale.each_date                         #-> enumerator


274
275
276
277
278
279
280
 
# File 'lib/csl/locale.rb', line 274

def each_date
  if block_given?
    date.each(&Proc.new)
  else
    enum_for :each_date
  end
end

#each_term ⇒ Object

Calls block once for each term defined by the locale. If no block is given, an enumerator is returned instead.

Examples:

locale.each_term { |term| block } #-> locale
locale.each_term                  #-> enumerator


259
260
261
262
263
264
265
266
 
# File 'lib/csl/locale.rb', line 259

def each_term
  if block_given?
    terms.each(&Proc.new)
    self
  else
    enum_for :each_term
  end
end

#initialize_copy(other) ⇒ Object 



137
138
139
140
 
# File 'lib/csl/locale.rb', line 137

def initialize_copy(other)
  super
  @language, @region = other.language, other.region
end

#inspect ⇒ String

Returns a string representation of the Locale.

Returns:

  • (String) —

    a string representation of the Locale



361
362
363
 
# File 'lib/csl/locale.rb', line 361

def inspect
  "#<#{self.class.name} #{to_s}>"
end

#legacy? ⇒ Boolean

Returns whether or not the Locale’s version is less than CSL-Ruby’s default version.

Returns:

  • (Boolean) —

    whether or not the Locale’s version is less than CSL-Ruby’s default version



170
171
172
 
# File 'lib/csl/locale.rb', line 170

def legacy?
  version < Schema.major_version
end

#merge(*others) ⇒ Locale

Returns:



308
309
310
 
# File 'lib/csl/locale.rb', line 308

def merge(*others)
  deep_copy.merge!(*others)
end

#merge!(*others) ⇒ self

Returns:

  • (self) 


313
314
315
316
317
318
319
320
 
# File 'lib/csl/locale.rb', line 313

def merge!(*others)
  others.each do |other|
    merge_options other
    merge_dates other
  end

  self
end

#ordinalize(number, options = {}) ⇒ String

Note:

For CSL 1.0 (and older) locales that do not define an “ordinal-00” term the algorithm specified by CSL 1.0 is used; otherwise uses the CSL 1.0.1 algorithm with improved support for languages other than English.

Ordinalizes the passed-in number using either the ordinal or long-ordinal forms defined by the locale. If a long-ordinal form is requested but not available, the regular ordinal will be returned instead.

Examples:

Locale.load('en').ordinalize(13)
#-> "13th"

de = Locale.load('de')
de.ordinalize(13)
#-> "13."

de.ordinalize(3, :form => :long, :gender => :feminine)
#-> "dritte"

Parameters:

  • number (#to_i) —

    the number to ordinalize

  • options (Hash) (defaults to: {}) —

    formatting options

Options Hash (options):

  • :form (:short, :long) — default: :short —

    which ordinals form to use

  • :gender (:feminine, :masculine, :neutral) — default: :neutral —

    which ordinals gender-form to use

Returns:

  • (String) —

    the ordinal for the passed-in number

Raises:

  • (ArgumentError) —

    if number cannot be converted to an integer



240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/csl/locale.rb', line 240

def ordinalize(number, options = {})
  raise ArgumentError, "unable to ordinalize #{number}; integer expected" unless
    number.respond_to?(:to_i)

  number = number.to_i
  ordinal = terms.ordinalize number, options

  return number.to_s if ordinal.nil?
  return ordinal.to_s(options) if ordinal.long_ordinal?

  [number, ordinal.to_s(options)].join
end

#set(locale) ⇒ self

Sets language and region according to the passed-in locale string. If the region part is not defined by the string, this method will set the region to the default region for the given language.

Examples:

locale.set('en')    #-> sets language to :en, region to :US
locale.set('de-AT') #-> sets language to :de, region to :AT
locale.set('-DE')   #-> sets langauge to :de, region to :DE

Returns:

  • (self)

Raises:

  • (ArgumentError) —

    if the argument is no valid locale string. A valid locale string is based on the syntax of IETF language tags; it consists of either a language or region tag (or both), separated by a hyphen.



189
190
191
192
 
# File 'lib/csl/locale.rb', line 189

def set(locale)
  @language, @region = Locale.normalize(locale).split(/-/).map(&:to_sym)
  self
end

#to_s ⇒ String

Returns the Locale’s IETF tag.

Returns:

  • (String) —

    the Locale’s IETF tag



356
357
358
 
# File 'lib/csl/locale.rb', line 356

def to_s
  [language, region].compact.join('-')
end

#translate(name, options = {}) ⇒ String? Also known as: t

Returns the term’s translation.

Returns:

  • (String, nil) —

    the term’s translation



202
203
204
205
 
# File 'lib/csl/locale.rb', line 202

def translate(name, options = {})
  term = terms.lookup name, options
  term && term.to_s(options)
end

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


303
304
305
 
# File 'lib/csl/locale.rb', line 303

def valid?
  validate.empty?
end

#validate ⇒ Object 



299
300
301
 
# File 'lib/csl/locale.rb', line 299

def validate
  Schema.validate self
end

#version ⇒ Object 



149
150
151
 
# File 'lib/csl/locale.rb', line 149

def version
  attributes[:version]
end

#version=(version) ⇒ Object

Raises:

  • (ArgumentError) 


153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/csl/locale.rb', line 153

def version=(version)
  raise ArgumentError, "failed to set version to #{version}" unless
    version.respond_to?(:to_s)

  version = version.to_s.strip

  raise ArgumentError, "failed to set version to #{version}: not a version string" unless
    version =~ /^\d[\d\.]+$/

  if version > Schema.version
    warn "setting version to #{version}; latest supported version is #{Schema.version}"
  end

  attributes[:version] = version
end