delocalize 0.4.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 00c6fb17341720d91984d417a166c15085fd39fa
+  data.tar.gz: b9c1d5688872a8692ab3fc2c82b8283ea434d4d7
+SHA512:
+  metadata.gz: 71bdd8bf81b15f4cb496dc7d266ea237a51ab5e18e657f0869bbdfed27363c69f13ddf96b2d88041a18ae0c4f095d6f6c9fbd1a3341115115eca4ee5eef4c962
+  data.tar.gz: e9032a044a45f7456a19d6f80a262d1448e058265c45cca990bf051eaa639a7ded115fe42f89c11f8b4f35c4f170158edef024f624595af3c39a47d80ecc01bf

data/README.markdown

@@ -4,17 +4,24 @@
 
 delocalize provides localized date/time and number parsing functionality for Rails.
 
-## 1.0 Beta
+## Demo Application
 
-Check out the [1-0-beta branch](https://github.com/clemens/delocalize/tree/1-0-beta) for an unfinished/unreleased improved version of delocalize. The goal is to get rid of all the nasty hacks and have a library that doesn't break with every new release of Rails.
+Find a demo application [here](https://github.com/clemens/delocalize_demo).
 
-Also check out the [ongoing discussion the wiki](https://github.com/clemens/delocalize/wiki/delocalize-1.0) and feel free to put in your opinion there.
+## Compability
+
+This gem requires the following versions:
+
+* Ruby >= 1.9.2
+* Rails >= 3.0 (Rails 2 and probably even Rails 1 *should* work but aren't officially supported)
+
+Check [the Travis configuration](https://github.com/clemens/delocalize/blob/1-0-beta/.travis.yml) in order to see which configurations we are testing.
 
 ## Installation
 
-You can use delocalize as a gem (preferred). Using delocalize as a Rails plugin has been discontinued and is no supported. If you want/need to use delocalize as a gem (I really don't see a reason why you'd want to), consider using the `0-2-stable` branch.
+You can use delocalize as a gem. Using delocalize as a Rails plugin has been discontinued and is no supported. If you want/need to use delocalize as a plugin (I really don't see a reason why you'd want to), consider using the `0-2-stable` branch.
 
-### Rails 3 and Rails 4
+### Rails 3
 
 To use delocalize, put the following gem requirement in your `Gemfile`:
 
@@ -24,7 +31,7 @@ gem "delocalize"
 
 ### Rails 2
 
-Note: Support for Rails 2 has been discontinued. This version is only considered stable for Rails >= 3. If you need Rails 2 support, please use the `0.2.x` versions or the `0-2-stable` branch respectively.
+Note: Official support for Rails 2 has been discontinued. However, due to the way this gem has been rewritten for its 1.0.0 release, it *should* work with Rails 2 just fine. If you run into any problems, consider filing an issue.
 
 To use delocalize, put the following gem requirement in your `environment.rb`:
 
@@ -46,7 +53,72 @@ def price=(price)
 end
 ```
 
-delocalize does this under the covers -- all you need is your regular translation data (as YAML or Ruby file) where you need Rails' standard translations:
+You also had to take care of proper formatting in forms on the frontend so people would see localized values in their forms.
+
+Delocalize does most of this under the covers. All you need is a simple setup in your controllers and your regular translation data (as YAML or Ruby file) where you need Rails' standard translations.
+
+### Controller setup
+
+The approach used in delocalize is based on Rails' own `strong_parameters`. In fact, if you are on Rails 3 with the `strong_parameters` gem installed or Rails 4 (which includes it by default), delocalize is mixed straight into the provided `ActionController::Parameters` class. Otherwise it uses its own similar class (`Delocalize::Parameters`).
+
+You can then use delocalize as you would use strong_parameters:
+
+``` ruby
+class ProductsController < ApplicationController
+  def create
+    Product.create(product_params)
+  end
+
+private
+
+  def product_params
+    delocalize_config = { :released_on => :date, :available_until => :time, :price => :number }
+    # with strong_parameters
+    params.require(:product).permit(*delocalize_config.keys).delocalize(delocalize_config)
+    # without strong_parameters
+    params.delocalize(:product => delocalize_config)[:product]
+    # or
+    params[:product].delocalize(delocalize_config)
+  end
+
+end
+```
+
+If you want to delocalize only certain parameters, configure those parameters and leave the others out – they will be kept as they are.
+
+### Views
+
+Delocalize doesn't automatically localize your data again (yet). There are various reasons for that but the main reasons are:
+
+- It's hard to do this properly with some amount of flexibility for you as the user of the gem without crazy hacks of Rails internals (a problem that delocalize previously suffered from).
+- Personally I feel that presentation logic (including forms) should be split out into separate objects (presenters, decorators, form objects and the like).
+
+I might change my mind but as it stands but for the time being the gist is: Wherever you want to see localized values, you have to localize them yourself.
+
+Examples:
+
+``` ruby
+text_field :product, :released_on, :value => product.released_on ? l(product.released_on) : nil
+text_field_tag 'product[price]', number_with_precision(product.price, :precision => 2)
+```
+
+You can of course use something like the [Draper gem](https://github.com/drapergem/draper) or the great [Reform gem](https://github.com/apotonick/reform) to wrap your actual object and override the relevant accessors.
+
+Check out how this can be done in the [demo app](https://github.com/clemens/delocalize_demo).
+
+There's also a wiki page on [how to write a custom input for SimpleForm](https://github.com/clemens/delocalize/wiki/Using-with-simple-form).
+
+### Locale setup
+
+In addition to your controller setup, you also need to configure your locale file(s). If you intend to use delocalize, you probably have a working locale file anyways. In this case, you only need to add two extra keys: `date.input.formats` and `time.input.formats`.
+
+Assuming you want to use all of delocalize's parsers (date, time, number), the required keys are:
+* number.format.delimiter
+* number.format.separator
+* date.input.formats
+* time.input.formats
+* date.formats.SOME_FORMAT for all formats specified in date.input.formats
+* time.formats.SOME_FORMAT for all formats specified in time.input.formats
 
 ```yml
 de:
@@ -85,164 +157,12 @@ de:
 
 For dates and times, you have to define input formats which are taken from the actual formats. The important thing here is to define input formats sorted by descending complexity; in other words: the format which contains the most (preferably non-numeric) information should be first in the list because it can produce the most reliable match. Exception: If you think there most complex format is not the one that most users will input, you can put the most-used in front so you save unnecessary iterations.
 
-Careful with formats containing only numbers: It's very hard to produce reliable matches if you provide multiple strictly numeric formats!
-
-delocalize then overrides `to_input_field_tag` in ActionView's `InstanceTag` so you can use localized text fields:
-
-```erb
-<% form_for @product do |f| %>
-  <%= f.text_field :name %>
-  <%= f.text_field :released_on %>
-  <%= f.text_field :price %>
-<% end %>
-```
-
-In this example, a user can enter the release date and the price just like he's used to in his language, for example:
-
->  Name: "Couch"
->  Released on: "12. Oktober 2009"
->  Price: "2.999,90"
-
-When saved, ActiveRecord automatically converts these to a regular Ruby date and number.
-
-Edit forms then also show localized dates/numbers. By default, dates and times are localized using the format named :default in your locale file. So with the above locale file, dates would use `%d.%m.%Y` and times would use `%A, %e. %B %Y, %H:%M Uhr`. Numbers are also formatted using your locale's thousands delimiter and decimal separator.
-
-You can also customize the output using some options:
-
-  The price should always show two decimal digits and we don't need the delimiter:
-
-```erb
-<%= f.text_field :price, :precision => 2, :delimiter => '' %>
-```
-
-  The `released_on` date should be shown in the `:full` format:
-
-```erb
-<%= f.text_field :released_on, :format => :full %>
-```
-
-  Since `I18n.localize` supports localizing `strftime` strings, we can also do this:
-
-```erb
-<%= f.text_field :released_on, :format => "%B %Y" %>
-```
-
-## Ruby 1.9 + Psych YAML Parser
-
-You will need to adjust the localization formatting when using the new YAML parser Psych.  Below is an example error message you may receive in your logs as well as an example of acceptable formatting and helpful links for reference:
-
-__Error message from logs:__
-
-    Psych::SyntaxError (couldn't parse YAML at line x column y):
-
-__References:__
-
-The solution can be found here: http://stackoverflow.com/questions/4980877/rails-error-couldnt-parse-yaml#answer-5323060
-
-http://pivotallabs.com/users/mkocher/blog/articles/1692-yaml-psych-and-ruby-1-9-2-p180-here-there-be-dragons
-
-__Psych Preferred Formatting:__
-
-```yml
-en:
-  number:
-    format:
-      separator: '.'
-      delimiter: ','
-      precision: 2
-  date:
-    input:
-      formats:
-        - :default
-        - :long
-        - :short
-    formats:
-      default: "%m/%d/%Y"
-      short: "%b %e"
-      long: "%B %e, %Y"
-      only_day: "%e"
-    day_names:
-      - Sunday
-      - Monday
-      - Tuesday
-      - Wednesday
-      - Thursday
-      - Friday
-      - Saturday
-    abbr_day_names:
-      - Sun
-      - Mon
-      - Tue
-      - Wed
-      - Thur
-      - Fri
-      - Sat
-    month_names:
-      - ~
-      - January
-      - February
-      - March
-      - April
-      - May
-      - June
-      - July
-      - August
-      - September
-      - October
-      - November
-      - December
-    abbr_month_names:
-      - ~
-      - Jan
-      - Feb
-      - Mar
-      - Apr
-      - May
-      - Jun
-      - Jul
-      - Aug
-      - Sep
-      - Oct
-      - Nov
-      - Dec
-    order:
-      - :month
-      - :day
-      - :year
-  time:
-    input:
-      formats:
-        - :default
-        - :long
-        - :short
-        - :time
-    formats:
-      default: "%m/%d/%Y %I:%M%p"
-      short: "%B %e %I:%M %p"
-      long: "%A, %B %e, %Y %I:%M%p"
-      time: "%l:%M%p"
-    am: "am"
-    pm: "pm"
-```
-
-## Compatibility
-
-* Tested with Rails 2.3.5 in Ruby 1.8.7, Ruby 1.9.1 and Ruby 1.9.2 (head)
-* Tested with Rails 3 in Ruby 1.9.3, Ruby 2.0 and Ruby 2.1 (head)
-* Tested with Rails 4 in Ruby 1.9.3, Ruby 2.0 and Ruby 2.1 (head)
-
-## Contributors
-
-Thanks to [all the people who contributed](https://github.com/clemens/delocalize/graphs/contributors) and submitted issues.
+**Be careful with formats containing only numbers: It's very hard to produce reliable matches if you provide multiple strictly numeric formats!**
 
-## TODO
+### Contributors and Copyright
 
-* Improve test coverage
-* Separate Ruby/Rails stuff to make it usable outside Rails
-* Decide on other ActionView hacks (e.g. `text_field_tag`)
-* Implement AM/PM support
-* Cleanup, cleanup, cleanup ...
+[Here](https://github.com/clemens/delocalize/graphs/contributors) is a list of all people who ever contributed to delocalize.
 
-Copyright (c) 2009-2014 Clemens Kofler <clemens@railway.at>
+Copyright (c) 2009-2015 Clemens Kofler <clemens@railway.at>
 <http://www.railway.at/>
 Released under the MIT license

data/lib/delocalize.rb

@@ -1,9 +1,17 @@
-require 'delocalize/ruby_ext'
-require 'delocalize/i18n_ext'
-require 'delocalize/localized_date_time_parser'
-
 if defined?(Rails::Railtie)
   require 'delocalize/railtie'
 elsif defined?(Rails::Initializer)
   raise "This version of delocalize is only compatible with Rails 3.0 or newer"
 end
+
+module Delocalize
+  class ParserNotFound < ArgumentError; end
+
+  autoload :Parsers,               'delocalize/parsers'
+
+  autoload :Parameters,            'delocalize/parameters'
+  autoload :ParameterDelocalizing, 'delocalize/parameter_delocalizing'
+
+  autoload :NumberParser,          'delocalize/number_parser'
+  autoload :DateTimeParser,        'delocalize/date_time_parser'
+end

data/lib/delocalize/delocalizable_parameters.rb

@@ -0,0 +1,15 @@
+# blatantly copied from strong_parameters's ActionController::Parameters :)
+
+module Delocalize
+  module DelocalizableParameters
+    extend ActiveSupport::Concern
+
+    def params
+      @_params ||= Parameters.new(request.parameters)
+    end
+
+    def params=(val)
+      @_params = val.is_a?(Hash) ? Parameters.new(val) : val
+    end
+  end
+end

data/lib/delocalize/parameter_delocalizing.rb

@@ -0,0 +1,70 @@
+module Delocalize
+  module ParameterDelocalizing
+    def delocalize(options)
+      delocalize_hash(self, options)
+    end
+
+  private
+
+    def delocalize_hash(hash, options, base_key_stack = [])
+      hash.each do |key, value|
+        key_stack = [*base_key_stack, key] # don't modify original key stack!
+
+        hash[key] = case value
+                    when Hash
+                      delocalize_hash(value, options, key_stack)
+                    when Array
+                      key_stack += [:[]] # pseudo-key to denote arrays
+                      value.map { |item| delocalize_parse(options, key_stack, item) }
+                    else
+                      delocalize_parse(options, key_stack, value)
+                    end
+      end
+    end
+
+    def delocalize_parse(options, key_stack, value)
+      parser = delocalize_parser_for(options, key_stack)
+      parser ? parser.parse(value) : value
+    end
+
+    def delocalize_parser_for(options, key_stack)
+      parser_type = key_stack.reduce(options) do |h, key|
+        case h
+        when Hash
+          h = h.stringify_keys
+          key = key.to_s
+          if key =~ /\A-?\d+\z/ && !h.key?(key)
+            h
+          else
+            h[key]
+          end
+        when Array
+          break unless key == :[]
+          h.first
+        else
+          break
+        end
+      end
+
+      return unless parser_type
+
+      parser_name = "delocalize_#{parser_type}_parser"
+      respond_to?(parser_name, true) ?
+        send(parser_name) :
+        raise(Delocalize::ParserNotFound.new("Unknown parser: #{parser_type}"))
+    end
+
+    def delocalize_number_parser
+      @delocalize_number_parser ||= Parsers::Number.new
+    end
+
+    def delocalize_time_parser
+      @delocalize_time_parser ||= Parsers::DateTime.new(Time)
+    end
+
+    def delocalize_date_parser
+      @delocalize_date_parser ||= Parsers::DateTime.new(Date)
+    end
+
+  end
+end

data/lib/delocalize/parameters.rb

@@ -0,0 +1,25 @@
+# blatantly copied from strong_parameters's ActionController::Parameters :)
+
+require 'active_support/core_ext/hash/indifferent_access'
+
+module Delocalize
+  class Parameters < ActiveSupport::HashWithIndifferentAccess
+    include ParameterDelocalizing
+
+    def [](key)
+      convert_hashes_to_parameters(key, super)
+    end
+
+  private
+
+    def convert_hashes_to_parameters(key, value)
+      if value.is_a?(self.class) || !value.is_a?(Hash)
+        value
+      else
+        # convert on first access
+        self[key] = self.class.new(value)
+      end
+    end
+
+  end
+end

data/lib/delocalize/parsers.rb

@@ -0,0 +1,6 @@
+module Delocalize
+  module Parsers
+    autoload :Number,   'delocalize/parsers/number'
+    autoload :DateTime, 'delocalize/parsers/date_time'
+  end
+end

data/lib/delocalize/{localized_date_time_parser.rb → parsers/date_time.rb}

@@ -1,26 +1,34 @@
+require 'date'
+
 # TODO:
 #   * AM/PM calculation
 #   * proper documentation (comments)
 module Delocalize
-  class LocalizedDateTimeParser
-    # extend/change this according to your needs by merging your custom regexps
-    REGEXPS = {
-      '%B' => "(#{Date::MONTHNAMES.compact.join('|')})",      # long month name
-      '%b' => "(#{Date::ABBR_MONTHNAMES.compact.join('|')})", # short month name
-      '%m' => "(\\d{2})",                                     # numeric month
-      '%A' => "(#{Date::DAYNAMES.join('|')})",                # full day name
-      '%a' => "(#{Date::ABBR_DAYNAMES.join('|')})",           # short day name
-      '%Y' => "(\\d{4})",                                     # long year
-      '%y' => "(\\d{2})",                                     # short year
-      '%e' => "(\\s\\d|\\d{2})",                              # short day
-      '%d' => "(\\d{2})",                                     # full day
-      '%H' => "(\\d{2})",                                     # hour (24)
-      '%M' => "(\\d{2})",                                     # minute
-      '%S' => "(\\d{2})"                                      # second
-    }
+  module Parsers
+    class DateTime
+      # extend/change this according to your needs by merging your custom regexps
+      REGEXPS = {
+        '%B' => "(#{Date::MONTHNAMES.compact.join('|')})",      # long month name
+        '%b' => "(#{Date::ABBR_MONTHNAMES.compact.join('|')})", # short month name
+        '%m' => "(\\d{2})",                                     # numeric month
+        '%A' => "(#{Date::DAYNAMES.join('|')})",                # full day name
+        '%a' => "(#{Date::ABBR_DAYNAMES.join('|')})",           # short day name
+        '%Y' => "(\\d{4})",                                     # long year
+        '%y' => "(\\d{2})",                                     # short year
+        '%e' => "(\\s\\d|\\d{2})",                              # short day
+        '%d' => "(\\d{2})",                                     # full day
+        '%H' => "(\\d{2})",                                     # hour (24)
+        '%M' => "(\\d{2})",                                     # minute
+        '%S' => "(\\d{2})"                                      # second
+      }
+
+      attr_reader :type
 
-    class << self
-      def parse(datetime, type)
+      def initialize(type)
+        @type = type
+      end
+
+      def parse(datetime)
         return unless datetime
         return datetime if datetime.respond_to?(:strftime) # already a Date/Time object -> no need to parse it
 
@@ -28,7 +36,7 @@ module Delocalize
         input_formats(type).each do |original_format|
           next unless datetime =~ /^#{apply_regex(original_format)}$/
 
-          datetime = DateTime.strptime(datetime, original_format)
+          datetime = ::DateTime.strptime(datetime, original_format)
           return Date == type ?
             datetime.to_date :
             Time.zone.local(datetime.year, datetime.mon, datetime.mday, datetime.hour, datetime.min, datetime.sec)
@@ -36,20 +44,20 @@ module Delocalize
         default_parse(datetime, type)
       end
 
-      private
+    private
+
       def default_parse(datetime, type)
         return if datetime.blank?
-        begin
-          today = Date.current
-          parsed = Date._parse(datetime)
-          return if parsed.empty? # the datetime value is invalid
-          # set default year, month and day if not found
-          parsed.reverse_merge!(:year => today.year, :mon => today.mon, :mday => today.mday)
-          datetime = Time.zone.local(*parsed.values_at(:year, :mon, :mday, :hour, :min, :sec))
-          Date == type ? datetime.to_date : datetime
-        rescue
-          datetime
-        end
+
+        today = Date.current
+        parsed = Date._parse(datetime)
+        return if parsed.empty? # the datetime value is invalid
+
+        # set default year, month and day if not found
+        parsed.reverse_merge!(:year => today.year, :mon => today.mon, :mday => today.mday)
+        datetime = Time.zone.local(*parsed.values_at(:year, :mon, :mday, :hour, :min, :sec))
+
+        Date == type ? datetime.to_date : datetime
       end
 
       def translate_month_and_day_names(datetime)