king_placeholder 0.0.2 → 0.0.3

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+gemfile:
+  - Gemfile

data/README.rdoc

@@ -1,15 +1,24 @@
 = KingPlaceholder
+{<img src="https://secure.travis-ci.org/salesking/king_placeholder.png?branch=master" alt="Build Status" />}[http://travis-ci.org/salesking/king_placeholder]
+This gem was extracted from SalesKing, where it does placeholders substitution
+for user supplied strings in Email-, Text- and Export-Templates.
 
-This gem was extraced from SalesKing where it handles placeholders substitution
-for user supplied email-, text- and export- templates.
+Placeholders are declared in each class and afterwards any strings containing
+[placeholders] can be parsed in the scope of the model.
 
-Define the available methods in your class
+Parsing is done by a simple statemachine using regex for placeholder detection.
+
+== Usage
+
+Define the available methods in your class with 'has_placeholders'
 
   class User
     include KingPlaceholder
     has_many :comments
-    has_placeholders :firstname
+    has_one :company
+    has_placeholders :firstname, :email
   end
+
   class Comment
     include KingPlaceholder
     has_placeholders :text
@@ -17,11 +26,11 @@ Define the available methods in your class
 
 Use placeholder names in square brackets:
 
-  @user.expand_placeholders("Hello [user.first_name]")
-  => Hello Schorsch
-
+  @user = User.new( name: "Schorsch", email: 'a@b.com')
+  @user.expand_placeholders("Hey [name] your address is [email]")
+  => "Hey Schorsch your address is a@b.com"
 
-It can also handle relations and collections
+Handle collections
 
   @user.expand_placeholders("[comments][text][/comments]")
   => All comment texts
@@ -29,12 +38,18 @@ It can also handle relations and collections
   @user.expand_placeholders("[comments.1.text]")
   => First comment text
 
+Handle relations
+
+  @user.expand_placeholders("[company.name]")
+  => MyCompany
+
+Also see specs
 
 == TODO
 
-This gems still relies on king_views with king_format, for money, date
+This gems still relies on gem king_views with king_format, for money, date
 formatting. We will outsource king_format into its own gem and remove more
-SalesKing internal dependencies.
+Rails and SalesKing internal dependencies.
 
 == Installation
 
@@ -42,18 +57,10 @@ Add this line to your application's Gemfile:
 
     gem 'king_placeholder'
 
-And then execute:
-
-    $ bundle
-
 Or install it yourself as:
 
     $ gem install king_placeholder
 
-== Usage
-
-See specs
-
 == Contributing
 
 1. Fork it

data/lib/king_placeholder/{parse_context.rb → parser.rb}

@@ -2,6 +2,7 @@ require 'statemachine'
 require 'action_view'       # king_views related suxs
 require 'action_controller' # king_views
 require 'king_views'
+
 module KingPlaceholder
   # Statemachine for placeholder substitution
   # The statemachine is created and its state updated from within the Context
@@ -20,7 +21,6 @@ module KingPlaceholder
         context machine_context
       end
     end
-
   end
 
   # Statemachine context for placeholder substitution
@@ -30,7 +30,7 @@ module KingPlaceholder
   #   # send match event
   #   machine.sm.match
   #   machine.result
-  class ParseContext
+  class Parser
     include ::KingFormat::FormattingHelper
     # reference to statemachine
     attr_accessor :sm
@@ -40,14 +40,12 @@ module KingPlaceholder
     attr_accessor :result
     # the current object
     attr_accessor :obj
-    # hash parse options
+    # parse-options hash
     attr_accessor :opts
 
-    # === Parameter
-    # obj<Object>:: any object responding to has_placeholder
-    # content<String>:: String containing placeholders
-    # opts<Hash{Symbol=>Mixed}>:: parse options
-    # :only<Array> => parse only the given placeholders
+    # @param [Object] obj object responding to has_placeholder
+    # @param [String] content containing placeholders
+    # @param [Hash{Symbol=>Mixed}] opts parser options (none so far)
     def initialize(obj, content, opts={})
       @sm = ParseMachine.create_with(self) # init statemachine
       @obj = obj
@@ -71,20 +69,20 @@ module KingPlaceholder
     # When finished matching, triggers finished_matching event on statemachine
     def parse
       while match = @result.match(/\[((\w|\.)+)\]/)
-        @c_placeholder = match[0] #  with brackets - current placeholder
-        @c_field = match[1]       # without brackets - current field
+        @placeholder = match[0] #  with brackets - current placeholder
+        @field = match[1]       # without brackets - current field
 
         check_current_prefix
 
-        if @c_field['.']
+        if @field['.']
           sub_object
-        elsif obj.respond_to?(@c_field) && ( @cur_collection = obj.send(@c_field) ).is_a?(Array)
+        elsif obj.respond_to?(@field) && ( @cur_collection = obj.send(@field) ).is_a?(Array)
           sub_collection
         else
           sub_string
         end
         # If placeholder still exists here, it can't be recognized, sub with error
-        @result.gsub!(@c_placeholder, "UNKNOWN for #{obj.class.to_s}: #{@c_field}")
+        @result.gsub!(@placeholder, "UNKNOWN for #{obj.class.to_s}: #{@field}")
       end
       @sm.finished_matching
     end
@@ -100,35 +98,34 @@ module KingPlaceholder
     # Final destination of each placeholder in it's simple notation without
     # namespace e.g. [price_to_pay]
     def sub_string
-      return unless obj.is_placeholder?(@c_field)
-      # only parse some placeholders
-#      return if opts[:only] && !opts[:only].include?(@c_field)
-      value = strfval(obj, @c_field)
-      @result.gsub!(@c_placeholder, value.to_s) if value
+      return unless obj.is_placeholder?(@field)
+      value = strfval(obj, @field)
+      @result.gsub!(@placeholder, value.to_s) if value
     end
 
-    # Namespaced notation, for related objects. We are in invoice which belongs
-    # to a company:
+    # Namespaced notation, for related objects. E.g an invoice belonging to a
+    # company:
     #   [company.default_address.zip]
     # instead of
     #   [invoice.company.default_address.zip]
     def sub_object
-      splitted = @c_field.split('.')
-      object_name = splitted.first # just the first
-      field_names = splitted[1..-1] # all but the first
-      return unless object_name && obj.respond_to?(object_name) # the field exists
+      splits= @field.split('.')
+      object_name = splits.first
+      field_names = splits[1..-1] # all but the first
+      return unless object_name && obj.respond_to?(object_name)
       object = obj.send(object_name)
-      #check if its a collection => invoice.items and access is done by ary index items.0.name
-      if object.is_a?(Array) && ary_index = field_names.first[/\A\d*\z/] # [items.5.name] match digit only string
+      # Its a collection => invoice.items and access is done by ary index:
+      # first item => [items.1.name]
+      if object.is_a?(Array) && ary_index = field_names.first[/\A\d*\z/]
         field_names.delete_at(0) # remove entry from field_names ary
         # replace with empty string if the index does not exist or obj is empty
-        @result.gsub!(@c_placeholder, '') unless object = object[ary_index.to_i-1]
+        @result.gsub!(@placeholder, '') unless object = object[ary_index.to_i-1]
       end
 
-      # Recurse and Let the referenced object do the expanding
+      # Recurse and let the referenced object do the expanding
       if object.respond_to?(:expand_placeholders)
         value = object.expand_placeholders("[#{field_names.join('.')}]")
-        @result.gsub!(@c_placeholder, value)
+        @result.gsub!(@placeholder, value)
       end
     end
 
@@ -136,30 +133,31 @@ module KingPlaceholder
     # [/field_name]
     # e.g. [items] Item price: [price] \n [/items]
     def sub_collection
-      if match = @result.match(/\[#{@c_field}\](.*)\[\/#{@c_field}\]/m) # the /m makes the dot match newlines, too!
+      if match = @result.match(/\[#{@field}\](.*)\[\/#{@field}\]/m) # the /m makes the dot match newlines, too!
         whole_group = match[0]
         inner_placeholders = match[1]
         inner_result = ''
-         # Let the referenced object do the expanding by recursion if the collection knowns placeholders
+         # Let the referenced object do the expanding by recursion if the collection knows placeholders
         @cur_collection.each do |item|
           inner_result << item.expand_placeholders(inner_placeholders)
         end if @cur_collection.first.respond_to?(:expand_placeholders)
         @result.gsub!(whole_group, inner_result)
       else
-        @result.gsub!(@c_placeholder, "END MISSING FOR #{@c_field}")
+        @result.gsub!(@placeholder, "END MISSING FOR #{@field}")
       end
     end
 
-    # Checks if the current field name contains the current object's class name.
-    # If the current class is an invoice, kick the prefix:
-    #   invoice.number => number
+    # Checks if the field name contains the current object's class name.
+    # Kick the prefix if the current class matches it, e.g:
+    #   Inside a client object
+    #   client.number => number
     def check_current_prefix
-      if @c_field['.']
-        splitted = @c_field.split('.')
-        object_name = splitted.first
+      if @field['.']
+        splits = @field.split('.')
+        object_name = splits.first
         if object_name && obj.class.name == object_name.classify
-          splitted.delete_at(0) # kick the object portion => invoice
-          @c_field = splitted.join('.') # glue the rest back together [number]
+          splits.delete_at(0) # kick the object portion => invoice
+          @field = splits.join('.') # glue the rest back together [number]
         end
       end
     end

data/lib/king_placeholder/version.rb

@@ -1,3 +1,3 @@
 module KingPlaceholder
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/king_placeholder.rb

@@ -1,4 +1,4 @@
-require 'king_placeholder/parse_context'
+require 'king_placeholder/parser'
 require 'active_support'
 require 'active_support/version'
 
@@ -9,7 +9,7 @@ require 'active_support/version'
 
 module KingPlaceholder
 
-  # sets :placeholders and init Class.placeholders as emtpy array on inclusion
+  # sets :placeholders and init Class.placeholders array on inclusion
   def self.included(base)
     if ActiveSupport::VERSION::MAJOR == 3 && ActiveSupport::VERSION::MINOR > 0
       base.class_attribute :placeholders
@@ -21,26 +21,18 @@ module KingPlaceholder
   end
 
   module ClassMethods
-
-    #  Defines the fields returned by self.placeholders.
-    #  Sets self.publish if empty.
-    # ==== Parameter
-    #  fieldnames<Array[Symbol]>:: the names of the fields which are available
-    #  throught the placeholder methods
+    # Define fields(methods) available to placeholder substitution
+    # @param [Array[<Symbol>] fieldnames
     def has_placeholders(*fieldnames)
       self.placeholders = fieldnames
       include InstanceMethods
     end
-  end #ClassMethods
+  end
 
   module InstanceMethods
-
     # Check if a given field is declared as placeholder
-    # TODO check usage and/or move to class methods
-    # ==== Parameter
-    # fieldname<String|Symbol>:: the field to search in the placeholders array
-    # ==== Returns
-    # <Boolean>:: true if in
+    # @param [Object] fieldname to search in placeholders array
+    # @return [Boolean]true if available
     def is_placeholder?(fieldname)
       self.class.placeholders.include?(fieldname.to_sym)
     end
@@ -50,11 +42,11 @@ module KingPlaceholder
     # and returns data with the same data type e.g. if you put a hash, you will
     # get a hash.
     #
-    # ==== Examples
+    # @examples
     #
     # Placeholders in text strings can be written in different notations.
     #
-    # ===== Simple Notation:
+    # === Simple Notation:
     #
     #  => [first_name]
     # The fieldname is directly looked up on the current class:
@@ -63,7 +55,7 @@ module KingPlaceholder
     # invoice.expand_placeholders(["You owe me [price_to_pay]", "Invoice Nr. [number]"])
     #   => ["You owe me 495,00 EUR", "Invoice Nr. 123"]
     #
-    # ===== Namespaced Notation
+    # === Namespaced Notation
     #
     # => [company.organisation]
     # If the prefix equals the type of the current object the field is looked up on it.
@@ -78,7 +70,7 @@ module KingPlaceholder
     #   invoice.expand_placeholders("[client.company.default_address.zip]")
     #   => "50999"
     #
-    # ===== Namespaced Notation with multiple related objects
+    # === Namespaced Notation with multiple related objects
     #
     # In a has_many relationship, related objects reside in an array, which can
     # be reached using two different strategies.
@@ -91,11 +83,9 @@ module KingPlaceholder
     #   invoice.expand_placeholders("You bought an [items.0.name] for [items.0.price]")
     #   => "You bought an Apple for 12 EUR"
     #
-    # === Parameter
-    # content<Hash,Array, String>:: Collection, Hash or single string containing
-    # placeholders
-    # === Returns
-    # <Hash,Array, String>:: whatever type you threw in is also returned
+    # @param [Hash|Array|String] content with placeholders
+    # @param [Object] opts - unused for now
+    # @return [Hash|Array|String] whatever type you throw in is also returned
     def expand_placeholders(content, opts={})
       if content.is_a?(Array) # Expand all array elements and go recursive
         result = []
@@ -108,7 +98,7 @@ module KingPlaceholder
       else # Only proceed with strings
         return content unless content.is_a?(String)
       end
-      parser = KingPlaceholder::ParseContext.new(self, content, opts)
+      parser = KingPlaceholder::Parser.new(self, content, opts)
       parser.sm.match
       parser.result if parser.sm.state == :finished
     end

data/spec/king_placeholder_spec.rb

@@ -1,25 +1,23 @@
 require 'spec_helper'
 
-class BaseModel
-#  include KingFormat::FormattingHelper
+# Construct dummy classes
+class Master
   include KingPlaceholder
-end
-
-# Construct dummy models
-class Master < BaseModel
   attr_accessor :string_field
   attr_accessor :details
   attr_accessor :side
   has_placeholders :string_field
 end
 
-class Side < BaseModel
+class Side
+  include KingPlaceholder
   attr_accessor :field
   attr_accessor :master
   has_placeholders :field
 end
 
-class Detail < BaseModel
+class Detail
+  include KingPlaceholder
   include KingFormat::MoneyFields
   attr_accessor :int_field, :money_field, :secret_field, :currency
   attr_accessor :master

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: king_placeholder
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-27 00:00:00.000000000 Z
+date: 2012-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: statemachine
@@ -163,14 +163,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.rdoc
 - Rakefile
 - king_placeholder.gemspec
 - lib/king_placeholder.rb
-- lib/king_placeholder/parse_context.rb
+- lib/king_placeholder/parser.rb
 - lib/king_placeholder/version.rb
+- placeholder_state.dia
 - spec/king_placeholder_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/salesking/king_placeholder.git
@@ -187,7 +189,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2667406904980012047
+      hash: 2706534140845333133
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -196,7 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2667406904980012047
+      hash: 2706534140845333133
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24