currency-in-words

= currency-in-words

Provides a view helper for Rails that displays a currency amount in words (eg. number_to_currency_in_words(100) => 'one hundred dollars').

This helper comes with two supported locales (English and French) but it is possible and easy to implement your own (see "Implementing a new locale").

== Installation

Add the gem to your Gemfile.

gem 'currency-in-words'

== Usage

==== General Options

• :locale - Sets the locale to be used for formatting (defaults to current locale).
• :currency - Sets the denomination of the currency (defaults to +:default+ currency for the locale or "dollar" if not set).
• :connector - Sets the connector between integer part and decimal part of the currency (defaults to ", ").
• :format - Sets the format for non-negative numbers (defaults to "%n"). Field is %n for the currency amount in words.
• :negative_format - Sets the format for negative numbers (defaults to prepending "minus" to the number in words 'minus %n'). Field is %n for the currency amount in words (same as format).

===== Examples [number_to_currency_in_words(123456.50)] => one hundred and twenty-three thousand four hundred and fifty-six dollars, fifty cents [number_to_currency_in_words(123456.50, connector: ' and ')] => one hundred and twenty-three thousand four hundred and fifty-six dollars and fifty cents [number_to_currency_in_words(123456.50, locale: :fr, connector: ' et ')] => cent vingt-trois mille quatre cent cinquante-six dollars et cinquante cents [number_to_currency_in_words(80300.80, locale: :fr, currency: :euro, connector: ' et ')] => quatre-vingt mille trois cents euros et quatre-vingts centimes

==== Specifics options for locale :en

• :delimiter - Sets the thousands delimiter (defaults to +false+)
• :skip_and - Skips the 'and' part in number - US (defaults to +false+)

===== Examples [number_to_currency_in_words(201201201.201, delimiter: true)] => two hundred and one million, two hundred and one thousand, two hundred and one dollars, twenty cents [number_to_currency_in_words(201201201.201, delimiter: true, skip_and: true)] => two hundred one million, two hundred one thousand, two hundred one dollars, twenty cents

== Options settings

Modify +config/locales/xx.yml+ to set default options and add currencies for locales.

=== Example for locale :en

en: number: currency_in_words: connector: ' and ' negative_format: '(%n)' skip_and: true delimiter: true currencies: euro: unit: one: 'euro' many: 'euros' decimal: one: 'cent' many: 'cents' pound: unit: one: 'pound' many: 'pounds' decimal: one: 'penny' many: 'pence'

=== Example for locale :fr

fr: number: currency_in_words: format: '%n' negative_format: 'moins %n' connector: ' et ' currencies: default: # euro will be the default currency for locale :fr unit: one: 'euro' many: 'euros' # can be omit more: "d'euros" # can be omit (specific to :fr, eg. 'un million d'euros') decimal: one: 'centime' many: 'centimes' # can be omit dollar: unit: one: 'dollar' many: 'dollars' decimal: one: 'cent' many: 'cents' livre: unit: feminine: true # specific to :fr, eg. 'un euro' but 'une livre' one: 'livre' many: 'livres' decimal: one: 'penny' many: 'pence'

== Implementing a new locale

+CurrencyInWords+ expects a texterizer by locale. A texterizer is a simple class that returns the amount in words for the currency and the given locale (eg. a class +EnTexterizer+ for English locale, a class +FrTexterizer+ for French locale). So, for example, if you want to support Italian, you have to implement an +ItTexterizer+ class for the module +CurrencyInWords+.

A texterizer :

• must provide a +texterize+ method
• must return a +string+

That's all.

Example :

class CurrencyInWords::ItTexterizer def texterize(context) ../.. end end

Parameter +context+ provides :

• an array that includes the integer part and the decimal part of the number (+context.number_parts+)
• a hash that includes the options passed to +number_to_currency_in_words+ (+context.options+).

See the source code of +EnTexterizer+ for an example (+FrTexterizer+ is perhaps too specific but +EnTexterizer+ can be a starting point to implement your own texterizer).

If you need more options for your language, simply create yours and use them (options +:delimiter+ and +:skip_and+ are for example specifics to +EnTexterizer+ while +:feminine+ is specific to +FrTexterizer+).

== ToDo

• clean up and push tests
• add comments in source code

== Contributing to currency-in-words

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Bruno Carrere. See LICENSE.txt for further details.