view 1.0.0.alpha.1 → 1.0.0.alpha.2

data/README.rdoc

@@ -1,5 +1,7 @@
 = View
 
+{Source}[http://github.com/iain/view] | {Documentation}[http://rubydoc.info/github/iain/view/master/frames]
+
 Automatic viewer. Very configurable. Very flexible. Very alpha (for now).
 
 It is made for displaying stuff in views. This can be very handy for DSLs that create views.
@@ -11,7 +13,7 @@ But first, the view!
 
 Use it from your views:
 
-  = view @post
+  <%= view @post %>
 
 View will try to figure out what the most logical way is to present the object you passed in.
 If the @post object has a title for instance, it will use that.
@@ -20,7 +22,7 @@ See the auto formatter for more information.
 
 You can use view anywhere you like:
 
-  puts View.to_s(@post)
+  puts View.format(@post)
 
 But beware that for many formatters, a reference to the template is required.
 It is a helper for the view part of your application after all.
@@ -29,55 +31,56 @@ It is a helper for the view part of your application after all.
 
 View will automatically try to choose the proper formatter. You can specify a formatter yourself:
 
-  = view @post.created_at, :as => :date
+  <%= view @post.created_at, :as => :date %>
 
 You can add a block to specify your own behavior. The parsed value is passed in as a block-variable.
 
-  = view @post.author do |author|
-    = link_to author, @post.author
+  <%= view @post.author do |author| %>
+    <%= link_to author, @post.author %>
+  <% end %>
 
 Most formatters pass their options down to the method they use, such as the image formatter:
 
-  = view @user.avatar, :as => :image, :size => "40x40", :class => "avatar"
+  <%= view @user.avatar, :as => :image, :size => "40x40", :class => "avatar" %>
 
 == Examples
 
 There are many formatters included (18 and counting), but here are some interesting use cases of some of them.
 
   # Options are passed to the helper methods:
-  = view @post, :as => :link, :method => :delete, :confirm => "are you sure?"
+  view @post, :as => :link, :method => :delete, :confirm => "are you sure?"
 
   # Renders a link to the edit_page of the post:
-  = view @post, :as => :link, :path => [ :edit ]
+  view @post, :as => :link, :path => [ :edit ]
 
   # Renders a sentence of links:
-  = view Post.all, :each => { :as => :link }
+  view Post.all, :each => { :as => :link }
 
   # When using paperclip, renders the image:
-  = view @project.logo, :as => :image
+  view @project.logo, :as => :image
 
   # Renders "yes" or "no" (with I18n support!)
-  = view @user.admin?
+  view @user.admin?
 
 See the formatters in lib/views/formatters to see their full documentation.
 
 == Adding formatters
 
-You can add a formatter by inheriting from View::Formatter.
-The only method you need to implement is the to_s method.
+You can add a formatter by inheriting from +View::Formatter+.
+The only method you need to implement is the +format+ method.
 
 In the class you have access to the following methods:
 
-* value: the object passed in
-* options: a filtered hash of options
-* all_options: the unfiltered hash
-* template: call methods like link_to on this
+* +value+: the object passed in
+* +options+: a filtered hash of options
+* +all_options+: the unfiltered hash
+* +template+: call methods like link_to on this
 
 If you wanted a uppercase formatter for example, you could do this:
 
   class Uppercase < View::Formatter
 
-    def to_s
+    def format
       value.to_s.upcase
     end
 
@@ -85,7 +88,7 @@ If you wanted a uppercase formatter for example, you could do this:
 
 The name of the formatter is automatically infered from the name of the class.
 
-You can use the .as method to specify a different name.
+You can use the +.as+ method to specify a different name.
 
   class Foo < View::Formatter
     as :bar
@@ -99,20 +102,20 @@ You can control which options are allowed, by adding reserved options:
   end
 
 Now, the options method will return the options passed by the user, minus foo and bar.
-To use them, in your code, use the all_options method.
+To use them, in your code, use the +all_options+ method.
 This is done to easily pass the options to another method, without cluttering:
 
   class Paragraph < View::Formatter
-    def to_s
+    def format
       template.content_tag(:p, value.to_s, options)
     end
   end
 
-To more tightly control which options are allowed, specify the allowed_options.
+To more tightly control which options are allowed, specify the allowed options:
 
   class Size < View::Formatter
     self.allowed_options = [ :separator, :delimiter, :precision ]
-    def to_s
+    def format
       template.number_to_human_size(value, options)
     end
   end
@@ -121,33 +124,15 @@ You can use the existing formatters as examples.
 
 == Configuration:
 
-See lib/view.rb for information on configuration.
+See +lib/view.rb+ for information on configuration.
 
 == Installation
 
-=== Rails 3
-
-In Rails 3, just add it to your Gemfile:
+Just add it to your Gemfile:
 
   gem 'view'
 
-Run <tt>bundle install</tt> and you're ready to go!
-
-=== Rails 2
-
-In Rails 2, add it to app/environment.rb:
-
-  config.gem 'view'
-
-And run <tt>rake gems:install</tt> to get it.
-
-Afterwards, include the helper mehtod manually, by editing app/helpers/application_helper.rb:
-
-  module ApplicationHelper
-    include View::Helper
-  end
-
-Caution: some helpers may use new helper methods from Rails 3 and might not work in Rails 2.
+Run +bundle install+ and you're ready to go!
 
 == Contributing
 

data/lib/view/formatter.rb

@@ -1,5 +1,6 @@
 module View
 
+  # @abstract Subclass and override {#format} to implement your own formatter.
   class Formatter
 
     attr_reader :value, :template, :block
@@ -13,58 +14,150 @@ module View
     class_inheritable_array :allowed_options
     self.allowed_options = []
 
-    def initialize(value, options = {}, template = nil, &block)
-      @value    = value
-      @options  = options
-      @template = template
-      @block    = block
-    end
-
+    # When you inherit from View::Formatter, the formatters goes on the list,
+    # but in reverse order, so that newer formatters kan override older ones.
     def self.inherited(formatter)
       super
       formatters.unshift(formatter)
     end
 
-    def self.formatters
-      View.formatters ||= []
-    end
-
+    # Specify your own name for the formatter. By default the name of the class
+    # will be used (without any namespacing), but you can override it yourself
+    # by calling this method.
+    #
+    # @example
+    #   class SomeStrangeName < View::Formatter
+    #     as :real_name
+    #   end
+    #
+    #   View.format @foo, :as => :real_name
+    #
+    # @param [Symbol] type The new name of the formatter
     def self.as(type)
       @type = type
     end
 
+    # @return [String] the type of the formatter, either set via +.as+ or
+    #   automatically deducted from the class name.
+    #
+    # @see .as
     def self.type
       @type || name.split('::').last.underscore
     end
 
-    def self.to_s(*args, &block)
-      new(*args, &block).format
-    end
-
+    # By default, blank values (nil, empty strings, etc), will override any
+    # formatter you specified. This way empty values are handled globally.
+    # 
+    # If you don't want this, you can either turn it off per formatter.
+    # Call this method to turn it off.
+    #
+    # @example
+    #   class IHandleMyOwnBlank < View::Formatter
+    #     skip_blank_formatter
+    #     # etc...
+    #   end
+    #
+    # @see View::Blank
+    def self.skip_blank_formatter
+      @skip_blank_formatter = true
+    end
+
+    # If you didn't specify a format instance method inside specific
+    # formatters, this will raise an error.
+    #
+    # @abstract Subclass and override {#format} to implement your own formatter.
+    # @return [String] the formatted value
     def format
-      if block
-        captured_value
-      else
-        formatted_value
-      end
-    end
-
-    def to_s
       msg <<-MSG.squeeze(' ')
-        The only thing a formatter needs to do is implement the #to_s method.
+        The only thing a formatter needs to do is implement the #format method.
         If you see this error, you forgot to do that for the #{self.class.type} formatter.
       MSG
       raise NotImplementedError.new(msg)
     end
 
+    # The "safe" options that you can toss around to helper methods.
+    #
+    # You can specify which methods are "safe" by white listing or black
+    # listing. White listing takes precedence over black listing.
+    #
+    # To access options that are filtered out, use +all_options+.
+    # It's generally a good idea to black list options that you use inside your
+    # formatter.
+    #
+    # The options +:as+ and +:block_arguments+ are black listed by default.
+    #
+    # @example White listing:
+    #
+    #   class Sentence < View::Formatter
+    #     self.allowed_options = [ :words_connector, :last_word_connector ]
+    #
+    #     def format
+    #       value.to_sentence(options)
+    #     end
+    #   end
+    #
+    # @example Black listing:
+    #
+    #   class Link < View::Formatter
+    #     self.reserved_options = [ :to ]
+    #
+    #     def format
+    #       template.link_to(value.to_s, all_options[:to], options)
+    #     end
+    #   end
+    #
+    # @return [Hash] filtered options
+    # @see #all_options
     def options
       default_options.merge(all_options).delete_if do |key, value|
         option_not_allowed?(key)
       end
     end
 
+    # This calls the format action. You can override it to do something with
+    # the formatted value. This doesn't (and shouldn't) do any formatting
+    # itself.
+    #
+    # @see #format
+    def to_s
+      format
+    end
+
+    # @return All options, unfiltered.
+    # @see #options
+    def all_options
+      @options
+    end
+
     private
 
+    def self.skip_blank_formatter?
+      @skip_blank_formatter
+    end
+
+    def self.format(*args, &block)
+      new(*args, &block).send(:format!)
+    end
+
+    def format!
+      if block
+        captured_value
+      else
+        formatted_value
+      end
+    end
+
+    def self.formatters
+      View.formatters ||= []
+    end
+
+    def initialize(value, options = {}, template = nil, &block)
+      @value    = value
+      @options  = options
+      @template = template
+      @block    = block
+    end
+
     def template_can_capture?
       template && template.respond_to?(:capture)
     end
@@ -78,31 +171,29 @@ module View
     end
 
     def captured_value_by_template
-      template.capture(formatted_value, *block_arguments, &block)
+      template.capture(*block_arguments, &block)
     end
 
     def captured_return_value
-      block.call(formatted_value, *block_arguments)
+      block.call(*block_arguments)
     end
 
     def formatted_value
+      formatter_not_found unless formatter
       formatter.new(value, all_options, template, &block).to_s
     end
 
     def formatter
-      find_formatter || formatter_not_found
+      blank_formatter || find_formatter
     end
 
     def formatter_not_found
+      formatter_names = self.class.formatters.map { |formatter| formatter.type.to_s }
       raise "Couldn't find the #{as} formatter. Got: #{formatter_names.join(', ')}"
     end
 
-    def formatter_names
-      self.class.formatters.map { |formatter| formatter.type.to_s }
-    end
-
     def find_formatter
-      self.class.formatters.find { |formatter| formatter.type.to_s == as.to_s }
+      @formatter ||= self.class.formatters.find { |formatter| formatter.type.to_s == as.to_s }
     end
 
     def option_not_allowed?(key)
@@ -114,15 +205,15 @@ module View
     end
 
     def block_arguments
-      all_options[:block_arguments] || []
+      all_options[:block_arguments] || [ formatted_value ]
     end
 
     def as
       all_options[:as] || View.default_formatter
     end
 
-    def all_options
-      @options
+    def blank_formatter
+      Blank if !find_formatter.skip_blank_formatter? && value.blank?
     end
 
   end

data/lib/view/formatters/array.rb

@@ -0,0 +1,32 @@
+module View
+
+  # @abstract Subclass this for html safe lists with formatted each support.
+  class Array < Formatter
+
+    def to_s
+      if all_safe?
+        super.html_safe
+      else
+        super
+      end
+    end
+
+    def all_safe?
+      formatted_values.all? do |element|
+        element.respond_to?(:html_safe?) && element.html_safe?
+      end
+    end
+
+    def formatted_values
+      @formatted_values ||= value.map do |element|
+        View.format(element, each, template, &block)
+      end
+    end
+
+    def each
+      all_options[:each] || { :as => View.default_formatter }
+    end
+
+  end
+
+end

data/lib/view/formatters/auto.rb

@@ -1,47 +1,70 @@
 module View
 
+  # The auto formatter tries to figure out what other formatter should be the
+  # most appropriate to use and delegates the formatting to that formatter.
+  #
+  # This is fully configurable too. See Auto.add
   class Auto < Formatter
 
-    def to_s
-      if as
-        format
-      else
-        guess
-      end
+    skip_blank_formatter
+
+    # Adds behavior to check which view should automatically be used.
+    #
+    # @example
+    #
+    #   View::Auto.add :boolean do
+    #     value == true || value == false
+    #   end
+    #
+    # @param [Symbol] formatter_name The name of the formatter
+    #
+    # @yield The block is eval'd inside the formatter, so you can use the
+    #   instance methods that are available for every formatters, like +value+
+    #   and +options+.
+    #
+    # @yieldreturn [true, false] The first block to evaluate to true will
+    #   determine the formatter. New blocks are checked first.
+    def self.add(formatter_name, &block)
+      auto_formatters.unshift(:formatter => formatter_name, :block => block)
     end
 
-    def datetime_format?
-      value.respond_to?(:strftime)
+    private
+
+    def format
+      format!
     end
 
-    def file_link_format?
-      View.file_methods.any? { |method| value.respond_to?(method) }
+    def self.auto_formatters
+      @auto_formatters ||= []
     end
 
-    def boolean_format?
-      value == true || value == false
+    def as
+      as = self.class.auto_formatters.find { |auto| instance_eval(&auto[:block]) }
+      as ? as[:formatter] : :guess
     end
 
-    def nil_format?
-      value.nil?
+    add :datetime do
+      value.respond_to?(:strftime)
     end
 
-    def sentence_format?
-      value.respond_to?(:to_sentence)
+    add :file_link do
+      View.file_methods.any? { |method| value.respond_to?(method) }
     end
 
-    def link_format?
-      all_options[:to]
+    add View.default_list_formatter do
+      value.respond_to?(:each)
     end
 
-    def as
-      %w|nil boolean file_link datetime sentence link|.find { |type| send("#{type}_format?") }
+    add :link do
+      all_options.has_key?(:to)
     end
 
-    def guess
-      View.guessing_methods.each do |method|
-        return value.send(method) if value.respond_to?(method)
-      end
+    add :blank do
+      value.blank?
+    end
+
+    add :boolean do
+      value == true || value == false
     end
 
   end

data/lib/view/formatters/blank.rb

@@ -0,0 +1,20 @@
+module View
+
+  # The default formatter for blank objects, like nil, empty strings and empty
+  # arrays. It will display an empty string or something else, which you can
+  # configure with I18n.
+  #
+  # @example config/locales/en.yml
+  #   en:
+  #     view:
+  #       blank: "nothing"
+  #
+  class Blank < Formatter
+
+    def format
+      ::I18n.t(:blank, :scope => :view, :default => "").html_safe
+    end
+
+  end
+
+end

data/lib/view/formatters/boolean.rb

@@ -1,8 +1,24 @@
 module View
 
+  # The default formatter for booleans.
+  #
+  # It will display "Yes" or "No".
+  #
+  # You can configure it with I18n. When writing 'true' and 'false' as keys in
+  # yaml, please don't forget the quotes.
+  #
+  # @example config/locales/en.yml
+  #   en:
+  #     view:
+  #       booleans:
+  #         'true': Yup
+  #         'false': Nope
+  #
   class Boolean < Formatter
 
-    def to_s
+    skip_blank_formatter
+
+    def format
       ::I18n.t(boolean_value.to_s, :scope => [:view, :booleans], :default => default)
     end
 

data/lib/view/formatters/currency.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :precision, :unit, :separator, :delimiter, :format ]
 
-    def to_s
+    def format
       template.number_to_currency(value, options)
     end
 

data/lib/view/formatters/date.rb

@@ -1,9 +1,10 @@
 module View
 
+  # Uses I18n to localize a date.
   class Date < Formatter
 
-    def to_s
-      ::I18n.l(value.to_date, options) if value.present?
+    def format
+      ::I18n.l(value.to_date, options)
     end
 
   end

data/lib/view/formatters/datetime.rb

@@ -1,9 +1,10 @@
 module View
 
+  # Uses I18n to format a datetime object.
   class Datetime < Formatter
 
-    def to_s
-      ::I18n.l(value, options) if value.present?
+    def format
+      ::I18n.l(value, options)
     end
 
   end

data/lib/view/formatters/delimited.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :separator, :delimiter ]
 
-    def to_s
+    def format
       template.number_with_delimiter(value, options)
     end
 

data/lib/view/formatters/file_link.rb

@@ -5,7 +5,7 @@ module View
     self.reserved_options = [ :text, :text_method ]
     self.default_options = { :target => "_blank" }
 
-    def to_s
+    def format
       template.link_to(text, path, options)
     end
 

data/lib/view/formatters/guess.rb

@@ -0,0 +1,18 @@
+module View
+
+  # This formatter is the fallback formatter for auto. It figures out which
+  # method will be called to get a proper version to render.
+  #
+  # @see View.guessing_methods
+  class Guess < Formatter
+
+    def format
+      View.guessing_methods.each do |method|
+        return value.send(method) if value.respond_to?(method)
+      end
+      value
+    end
+
+  end
+
+end

data/lib/view/formatters/html_safe.rb

@@ -1,8 +1,9 @@
 module View
 
+  # This formatter marks the value as html safe
   class HtmlSafe < Formatter
 
-    def to_s
+    def format
       value.to_s.html_safe
     end
 

data/lib/view/formatters/human.rb

@@ -7,7 +7,7 @@ module View
     self.allowed_options = [ :locale, :precision, :significant, :separator, :delimiter,
       :strip_insignificant_zeros, :units, :format ]
 
-    def to_s
+    def format
       template.number_to_human(value, options)
     end
 

data/lib/view/formatters/image.rb

@@ -4,7 +4,7 @@ module View
 
     self.reserved_options = [ :with ]
 
-    def to_s
+    def format
       template.image_tag(path, options) if file?
     end
 

data/lib/view/formatters/link.rb

@@ -4,7 +4,7 @@ module View
 
     self.reserved_options = [ :to, :path, :text ]
 
-    def to_s
+    def format
       template.link_to(format, to, options)
     end
 

data/lib/view/formatters/percentage.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :precision, :separator, :delimiter ]
 
-    def to_s
+    def format
       template.number_to_percentage(value, options)
     end
 

data/lib/view/formatters/phone.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :area_code, :delimiter, :extension, :country_code ]
 
-    def to_s
+    def format
       template.number_to_phone(value, options)
     end
 

data/lib/view/formatters/precision.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :precision, :separator, :delimiter ]
 
-    def to_s
+    def format
       template.number_with_precision(value, options)
     end
 

data/lib/view/formatters/self.rb

@@ -1,8 +1,11 @@
 module View
 
+  # This formatter just returns itself. It doesn't do anything.
   class Self < Formatter
 
-    def to_s
+    skip_blank_formatter
+
+    def format
       value
     end
 

data/lib/view/formatters/sentence.rb

@@ -1,31 +1,26 @@
 module View
 
-  class Sentence < Formatter
+  # This formatter is for arrays and stuff into a sentence.
+  #
+  # You can pass the options for sentence and, like any other array formatter,
+  # you can pass an each option, that contains the options for every element in
+  # the array.
+  #
+  # If you don't pass any options in each, it will autoformat every element.
+  #
+  # @example
+  #
+  #   View.format @dates, :as => :sentence,
+  #     :each => { :as => :date, :format => :short }
+  #
+  # @see View::Array
+  # @see http://rubydoc.info/docs/rails/3.0.0/Array:to_sentence
+  class Sentence < Array
 
     self.allowed_options = [ :words_connector, :two_words_connector, :last_word_connector ]
 
-    def to_s
-      if all_safe?
-        sentence.html_safe
-      else
-        sentence
-      end
-    end
-
-    def all_safe?
-      formatted_values.all? { |element| element.html_safe? }
-    end
-
-    def formatted_values
-      value.map { |element| View.to_s(element, each, template, &block) }
-    end
-
-    def sentence
-      formatted_values.to_sentence if value.present?
-    end
-
-    def each
-      all_options[:each] || { :as => View.default_formatter }
+    def format
+      formatted_values.to_sentence(options)
     end
 
   end

data/lib/view/formatters/size.rb

@@ -4,7 +4,7 @@ module View
 
     self.allowed_options = [ :precision, :separator, :delimiter ]
 
-    def to_s
+    def format
       template.number_to_human_size(value, options)
     end
 

data/lib/view/helper.rb

@@ -3,7 +3,7 @@ module View
   module Helper
 
     def view(value, options = {}, &block)
-      ::View.to_s(value, options, self, &block)
+      ::View.format(value, options, self, &block)
     end
 
   end

data/lib/view/version.rb

@@ -1,3 +1,3 @@
 module View
-  VERSION = '1.0.0.alpha.1'
+  VERSION = '1.0.0.alpha.2'
 end

data/lib/view.rb

@@ -4,26 +4,94 @@ module View
   autoload :Helper,    'view/helper'
   autoload :VERSION,   'view/version'
 
-  mattr_accessor :guessing_methods
-  self.guessing_methods = %w|to_label display_name full_name name title username login value to_s|
+  class << self
+    # Used by the guess filter, these are the methods used to format an object.
+    # It will use the first method that the object responds to.
+    attr_accessor :guessing_methods
 
-  mattr_accessor :file_methods
-  self.file_methods = %w|mounted_as file? public_filename|
+    # To determine if something is an uploaded image, it checks
+    # to see whether it responds to one of these methods.
+    attr_accessor :file_methods
 
-  mattr_accessor :path_methods
-  self.path_methods = %w|mounted_as url public_filename|
+    # To show an image, it will use one of these methods to get the src
+    # attribute.
+    attr_accessor :path_methods
 
-  mattr_accessor :path_arguments
-  self.path_arguments = []
+    # You can set a default argument for rendering images, like the style or size
+    # of the image. It will be passed to one of the path_methods.
+    attr_accessor :path_arguments
 
-  mattr_accessor :default_formatter
-  self.default_formatter = :auto
+    # Which formatter will be used by default. The default is auto, which does
+    # all sorts of interesting stuff to see what to do.
+    attr_accessor :default_formatter
 
-  mattr_accessor :formatters
+    # The auto formatter will choose this formatter by default when your value is
+    # an array (or really, something that responds to +each+).
+    attr_accessor :default_list_formatter
 
+    # Holds a list of formatters. It will be filled automatically by inheriting
+    # from View::Formatter.
+    attr_accessor :formatters
 
-  def self.to_s(value, options = {}, template = nil, &block)
-    Formatter.to_s(value, options, template, &block)
+    # Shorthand for configuring this gem.
+    #
+    # @example In +config/initializers/view.rb+
+    #
+    #   View.configure do |config|
+    #     config.default_formatter = :self
+    #   end
+    #
+    # @yield [config] The View module
+    def configure
+      yield self
+    end
+
+  end
+
+  self.guessing_methods       = %w|to_label display_name full_name name title
+                                   username login value to_s|
+  self.file_methods           = %w|mounted_as file? public_filename|
+  self.path_methods           = %w|mounted_as url public_filename|
+  self.path_arguments         = []
+  self.default_formatter      = :auto
+  self.default_list_formatter = :sentence
+
+
+  # This is the main method to use this gem. Any formatting from outside this
+  # gem should be done through this method (notwithstanding custom formatters).
+  #
+  # In every day usage you will access it through the +view+ helper method,
+  # because most formatters require a view to render links or images. Any
+  # helper method should also point to this method.
+  #
+  # @see View::Helper#view
+  #
+  # @example Rendering a link
+  #   module PostsHelper
+  #     def link_to_post
+  #       View.format @post, :as => :link, self
+  #     end
+  #   end
+  #
+  # @param [Object] value the object to be shown
+  # @param [Hash] options Any extra options
+  #
+  # @option options [Symbol] :as (:auto) The name of the formatter
+  # @option options [Array] :block_arguments (nil) Overrides the arguments passed to
+  #   the block of this method.
+  #
+  # @param [ActionView::Template] Template the view instance on which to call
+  #   helper methods like +link_to+ and +image_tag+.
+  #   You need this for many formatters.
+  #
+  # @yield [formatted_string] The block will be captured (using the template if
+  #   possible) to alter the formatted string that would otherwise be returned.
+  #   Consider it as a final modifier after the view formatter has done its
+  #   work.
+  #
+  # @return [String] the object formatted to a string
+  def self.format(value, options = {}, template = nil, &block)
+    Formatter.format(value, options, template, &block)
   end
 
 end

data/spec/view/formatter_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe "View::Formatter" do
+
+  it "doesn't touch strings" do
+    View.format("bar").should == "bar"
+  end
+
+  it "parses the block" do
+    View.format("bar") { |val| val.upcase }.should == "BAR"
+  end
+
+end

data/spec/view/formatters/auto_spec.rb

@@ -2,24 +2,21 @@ require 'spec_helper'
 
 describe "Auto formatter" do
 
-  it "guesses the to_label" do
-    object = Struct.new(:to_label).new("some label")
-    View.to_s(object).should == "some label"
+  it "formats like a boolean automatically" do
+    View.format(true).should == "Yes"
   end
 
-  it "guesses to_s" do
-    object = Struct.new(:to_s).new("string")
-    View.to_s(object).should == "string"
-  end
-
-  it "guesses a name" do
-    object = Struct.new(:name).new("my name")
-    View.to_s(object).should == "my name"
-  end
-
-  it "guesses a login" do
-    object = Struct.new(:login).new("loginname")
-    View.to_s(object).should == "loginname"
+  it "is configurable" do
+    foo = Class.new(View::Formatter) do
+      as :foo
+      def format
+        "!!!#{value}!!!"
+      end
+    end
+    View::Auto.add :foo do
+      value == "foobar"
+    end
+    View.format("foobar").should == "!!!foobar!!!"
   end
 
 end

data/spec/view/formatters/blank_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe "Blank formatter" do
+
+  it "formats nil" do
+    View.format(nil).should == ""
+  end
+
+  it "formats empty strings" do
+    View.format("  ").should == ""
+  end
+
+  it "formats empty arrays" do
+    View.format([]).should == ""
+  end
+
+  it "uses i18n for nil" do
+    with_translation :view => { :blank => "nothing" } do
+      View.format(nil).should == "nothing"
+    end
+  end
+
+end

data/spec/view/formatters/boolean_spec.rb

@@ -3,24 +3,24 @@ require 'spec_helper'
 describe "Boolean formatter" do
 
   it "formats true" do
-    View.to_s(true).should == "Yes"
+    View.format(true).should == "Yes"
   end
 
   it "formats false" do
-    View.to_s(false).should == "No"
+    View.format(false).should == "No"
   end
 
   it "formats boolean values" do
-    View.to_s("h", :as => :boolean).should == "Yes"
-    View.to_s(nil, :as => :boolean).should == "No"
+    View.format("h", :as => :boolean).should == "Yes"
+    View.format(nil, :as => :boolean).should == "No"
   end
 
   it "localizes booleans" do
     with_translation :view => { :booleans => { :true => "yup" } } do
-      View.to_s(true).should == "yup"
+      View.format(true).should == "yup"
     end
     with_translation :view => { :booleans => { :false => "nope" } } do
-      View.to_s(false).should == "nope"
+      View.format(false).should == "nope"
     end
   end
 

data/spec/view/formatters/date_spec.rb

@@ -5,18 +5,18 @@ describe "Date formatter" do
   it "localizes dates" do
     date = Date.new(2010, 10, 11)
     with_translation :date => { :formats => { :foo => "%A" }, :day_names => [ "zondag", "maandag" ] } do
-      View.to_s(date, :format => :foo).should == "maandag"
+      View.format(date, :format => :foo).should == "maandag"
     end
   end
 
   it "formats dates" do
     date = Date.new(2010, 10, 10)
-    View.to_s(date).should == "2010-10-10"
+    View.format(date).should == "2010-10-10"
   end
 
   it "forces datetimes to date" do
     time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
-    View.to_s(time, :as => :date).should == "2010-10-10"
+    View.format(time, :as => :date).should == "2010-10-10"
   end
 
 end

data/spec/view/formatters/datetime_spec.rb

@@ -4,13 +4,13 @@ describe "Datetime formatter" do
 
   it "formats" do
     time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
-    View.to_s(time).should == "Sun, 10 Oct 2010 08:45:30 +0100"
+    View.format(time).should == "Sun, 10 Oct 2010 08:45:30 +0100"
   end
 
   it "localizes" do
     time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
     with_translation :time => { :formats => { :short => "%d-%m-%Y %H:%M" } } do
-      View.to_s(time, :format => :short).should == "10-10-2010 08:45"
+      View.format(time, :format => :short).should == "10-10-2010 08:45"
     end
   end
 

data/spec/view/formatters/guess_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe "Guess formatter" do
+
+  it "guesses the to_label" do
+    object = Struct.new(:to_label).new("some label")
+    View.format(object).should == "some label"
+  end
+
+  it "guesses to_s" do
+    object = Struct.new(:to_s).new("string")
+    View.format(object).should == "string"
+  end
+
+  it "guesses a name" do
+    object = Struct.new(:name).new("my name")
+    View.format(object).should == "my name"
+  end
+
+  it "guesses a login" do
+    object = Struct.new(:login).new("loginname")
+    View.format(object).should == "loginname"
+  end
+
+end

data/spec/view/formatters/self_spec.rb

@@ -4,7 +4,7 @@ describe "Self formatter" do
 
   it "doesn't format with formatter self" do
     time = Time.now
-    View.to_s(time, :as => :self).should == time
+    View.format(time, :as => :self).should == time
   end
 
 end

data/spec/view/formatters/sentence_spec.rb

@@ -4,7 +4,23 @@ describe "Sentence formatter" do
 
   it "constructs a sentence" do
     object = [ 1, 2, 3 ]
-    View.to_s(object).should == "1, 2, and 3"
+    View.format(object).should == "1, 2, and 3"
+  end
+
+  it "has options for each element" do
+    object = [ Date.today ]
+    subject = View.format(object, :each => { :format => :short })
+    subject.should == I18n.l(Date.today, :format => :short)
+  end
+
+  it "makes the sentence html safe if all elements are" do
+    object = [ "safe".html_safe ]
+    View.format(object).should be_html_safe
+  end
+
+  it "doesn't make the sentence html safe if not all elements are safe" do
+    object = [ "safe".html_safe, "unsafe" ]
+    View.format(object).should_not be_html_safe
   end
 
 end

metadata

@@ -7,8 +7,8 @@ version: !ruby/object:Gem::Version
   - 0
   - 0
   - alpha
-  - 1
-  version: 1.0.0.alpha.1
+  - 2
+  version: 1.0.0.alpha.2
 platform: ruby
 authors: 
 - Iain Hecker
@@ -16,10 +16,24 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-03 00:00:00 +02:00
+date: 2010-10-10 00:00:00 +02:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
 description: A very extensible way of viewing objects, easily integrated with other gems
 email: 
 - iain@iain.nl
@@ -31,18 +45,20 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - lib/view/formatter.rb
+- lib/view/formatters/array.rb
 - lib/view/formatters/auto.rb
+- lib/view/formatters/blank.rb
 - lib/view/formatters/boolean.rb
 - lib/view/formatters/currency.rb
 - lib/view/formatters/date.rb
 - lib/view/formatters/datetime.rb
 - lib/view/formatters/delimited.rb
 - lib/view/formatters/file_link.rb
+- lib/view/formatters/guess.rb
 - lib/view/formatters/html_safe.rb
 - lib/view/formatters/human.rb
 - lib/view/formatters/image.rb
 - lib/view/formatters/link.rb
-- lib/view/formatters/nil.rb
 - lib/view/formatters/percentage.rb
 - lib/view/formatters/phone.rb
 - lib/view/formatters/precision.rb
@@ -56,15 +72,16 @@ files:
 - init.rb
 - README.rdoc
 - spec/spec_helper.rb
+- spec/view/formatter_spec.rb
 - spec/view/formatters/auto_spec.rb
+- spec/view/formatters/blank_spec.rb
 - spec/view/formatters/boolean_spec.rb
 - spec/view/formatters/date_spec.rb
 - spec/view/formatters/datetime_spec.rb
-- spec/view/formatters/nil_spec.rb
+- spec/view/formatters/guess_spec.rb
 - spec/view/formatters/self_spec.rb
 - spec/view/formatters/sentence_spec.rb
 - spec/view/helper_spec.rb
-- spec/view/view_spec.rb
 has_rdoc: true
 homepage: http://github.com/iain/view
 licenses: []
@@ -101,12 +118,13 @@ specification_version: 3
 summary: Displaying objects automatically
 test_files: 
 - spec/spec_helper.rb
+- spec/view/formatter_spec.rb
 - spec/view/formatters/auto_spec.rb
+- spec/view/formatters/blank_spec.rb
 - spec/view/formatters/boolean_spec.rb
 - spec/view/formatters/date_spec.rb
 - spec/view/formatters/datetime_spec.rb
-- spec/view/formatters/nil_spec.rb
+- spec/view/formatters/guess_spec.rb
 - spec/view/formatters/self_spec.rb
 - spec/view/formatters/sentence_spec.rb
 - spec/view/helper_spec.rb
-- spec/view/view_spec.rb

data/lib/view/formatters/nil.rb

@@ -1,11 +0,0 @@
-module View
-
-  class Nil < Formatter
-
-    def to_s
-      ::I18n.t(:nil, :scope => :view, :default => "")
-    end
-
-  end
-
-end

data/spec/view/formatters/nil_spec.rb

@@ -1,15 +0,0 @@
-require 'spec_helper'
-
-describe "Nil formatter" do
-
-  it "formats nil" do
-    View.to_s(nil).should == ""
-  end
-
-  it "uses i18n for nil" do
-    with_translation :view => { :nil => "nothing" } do
-      View.to_s(nil).should == "nothing"
-    end
-  end
-
-end

data/spec/view/view_spec.rb

@@ -1,13 +0,0 @@
-require 'spec_helper'
-
-describe "View" do
-
-  it "doesn't touch strings" do
-    View.to_s("bar").should == "bar"
-  end
-
-  it "parses the block" do
-    View.to_s("bar") { |val| val.upcase }.should == "BAR"
-  end
-
-end