snippr 0.1.7 → 0.2.0

data/CHANGELOG

@@ -1,2 +1,16 @@
+== 0.2.0 (2010-05-13)
+  * Added support for I18n snippr files. Simply enable I18n:
+    
+      Snippr.i18n = true
+    
+    And Snippr will automatically retrieve the current locale from I18n and append
+    it to every snippr file you're trying to load:
+    
+      I18n.locale = :de
+      Snippr.load(:topup, :success) # Will load: "topup/success_de.snip"
+
+  * From the example above, you should also notice that the method for loading a
+    snippr file has changed from +new+ to +load+.
+
 == 0.1.0 (2010-04-30)
   * Initial version.

data/README.rdoc

@@ -1,62 +1,67 @@
 = Snippr
 ==== File based content management
 
-A snippr is a piece of HTML to be included in a website. They are plain text
-files stored on the file system.
+A snippr file is a piece of HTML or raw text to be included in a website. They are plain text
+files stored on the file system. Snippr files end with ".snip" and are read from the Snippr path.
 
 == Snippr path
 
-You need to specify the path to the snippr directory:
+You need to specify the path to the directory where your Snippr files are stored:
 
-  Snippr.path = File.join(File.dirname(__FILE__), "..", "snippr")
+  Snippr.path = File.join File.dirname(__FILE__), "..", "snippr"
 
-When running on JRuby, you can also set the path via JVM properties. The property
-you need to specify is defined in +SnipprPath::JVMProperty+. This allows system
-administrators to change the path without having to touch your application.
+When running on JRuby, you can also set the path via JVM properties. The property you need to
+specify is defined in Snippr::Path::JVMProperty. This allows system administrators to change the
+path without having to touch your application.
 
-== Instantiation
+== Loading a snippr
 
-Instantiating a new snippr is done by passing in the path to the snippr file as
+To load a snippr file, you can use the +load+ method, passing in the path to the snippr file as
 a String (including path separators):
 
-  Snippr.new "tariff/einheit"
+  Snippr.load "tariff/einheit"
 
 or by using multiple Strings or Symbols:
 
-  Snippr.new :tariff, :einheit
+  Snippr.load :tariff, :einheit
 
 === Dynamic values
 
-A snippr may contain placeholders to be replaced with dynamic values. Placeholders
-are wrapped in curly braces.
+A snippr file may contain placeholders to be replaced with dynamic values. Placeholders are
+wrapped in curly braces.
 
   <p>You're topup of {topup_amount} at {date_today} was successful.</p>
 
-To replace both {topup_amount} and {date_today} with a dynamic value, you just pass
-in a Hash of placeholders and dynamic values when instantiating a new snippr.
+To replace both {topup_amount} and {date_today} with a dynamic value, you just pass in a Hash of
+placeholders and dynamic values when loading a snippr file.
 
-  Snippr.new :topup, :success, :topup_amount => number_to_currency(15), :date_today => Date.today
+  Snippr.load :topup, :success, :topup_amount => number_to_currency(15), :date_today => Date.today
 
 The result will obviously be something like:
 
   <p>You're topup of 15,00 &euro; at 2010-04-03 was successful.</p>
 
-== Links
+== I18n
 
-...
+Snippr comes with support for I18n, but up until further notice, you have to manually enable this
+behavior in your application.
 
-== Snippr content
+  Snippr.i18n = true
 
-Returning the snippr content is done by calling the +to_s+ method. This will replace
-all specified placeholders and links.
+Afterwards Snippr uses the locale specified via I18n and automatically prepends the current locale
+prefixed with a "_" to your snippr files.
 
-  Snippr.new(:tariff, :einheit).to_s
+  I18n.locale = :de
+  Snippr.load :shop # tries to load "shop_de.snip" relative to your Snippr path
+
+  I18n.locale = :en
+  Snippr.load :shop # tries to load "shop_en.snip" relative to your Snippr path
 
 == Rails Helper
 
-When using the Snippr component with Rails, it automatically adds the +SnipprHelper+
-module to your views. You can then use the +snippr+ helper method to load snippr files.
+When using the Snippr module with Rails, it automatically adds the +Snippr::Helper+ module to
+your views. You can then use the +snippr+ helper method to load snippr files.
 
   %h1 Topup successful
   .topup.info
-    = snippr :topup, :success
+    = snippr :topup, :success

data/Rakefile

@@ -1,20 +1,9 @@
 require "rake"
 require "spec/rake/spectask"
-require "spec/rake/verify_rcov"
 
 task :default => :spec
 
-Spec::Rake::SpecTask.new do |t|
-#  t.rcov = true
-#  t.rcov_opts = %w(--exclude-only ^\/User,spec\/)
-end
-
-namespace :spec do
-  RCov::VerifyTask.new(:rcov => :spec) do |t|
-    t.threshold = 90
-    t.index_html = "coverage/index.html"
-  end
-end
+Spec::Rake::SpecTask.new
 
 begin
   require "hanna/rdoctask"
@@ -27,5 +16,5 @@ begin
     t.options << "--webcvs=http://github.com/blaulabs/snippr/tree/master/"
   end
 rescue LoadError
-  puts "'gem install hanna' for documentation"
-end
+  puts "'gem install hanna' to generate documentation"
+end

data/lib/snippr/core_ext.rb

@@ -9,4 +9,4 @@ class String
     str
   end
 
-end
+end

data/lib/snippr/helper.rb

@@ -0,0 +1,23 @@
+# = Snippr::Helper
+#
+# This module is automatically included into +ActionView::Base+ when using the Snippr
+# component with Rails. It provides a +snippr+ helper method for loading snippr files.
+#
+#   %h1 Topup successful
+#   .topup.info
+#     = snippr :topup, :success
+module Snippr
+  module Helper
+
+    # Returns a snippr specified via +args+.
+    def snippr(*args)
+      snippr = Snippr.load *args
+      snippr.respond_to?(:html_safe) ? snippr.html_safe : snippr
+    end
+
+  end
+end
+
+if defined? ActionView::Base
+  ActionView::Base.send :include, Snippr::Helper
+end

data/lib/snippr/i18n.rb

@@ -0,0 +1,27 @@
+require "i18n"
+
+# = Snippr::I18n
+#
+# Extends the Snippr module adding support for I18n snippr files.
+module Snippr
+  module I18n
+
+    # Sets whether to use I18n snippr files.
+    def i18n=(enabled)
+      @enabled = enabled
+    end
+
+    # Returns whether to use I18n snippr files.
+    def i18n?
+      !!@enabled
+    end
+
+    # Returns the current locale prefixed with a "_" from I18n if I18n is enabled.
+    # Otherwise defaults to an empty String.
+    def locale
+      return "" unless i18n?
+      ["_", ::I18n.locale].join
+    end
+
+  end
+end

data/lib/snippr/path.rb

@@ -0,0 +1,29 @@
+# = Snippr::Path
+#
+# Extends the Snippr module with methods dealing the path to the snippr files.
+module Snippr
+  module Path
+
+    # The JVM property to set the path to the snippr files.
+    JVMProperty = "cms.snippet.path"
+
+    # Returns the path to the snippr files (from JVM properties if available).
+    def path
+      @path ||= JavaLang::System.get_property(JVMProperty) rescue ""
+    end
+
+    # Sets the path to the snippr files.
+    def path=(path)
+      @path = path.to_s
+    end
+
+  private
+
+    if RUBY_PLATFORM =~ /java/
+      module JavaLang
+        include_package "java.lang"
+      end
+    end
+
+  end
+end

data/lib/snippr/snippr.rb

@@ -1,114 +1,61 @@
+require "snippr/core_ext"
+require "snippr/path"
+require "snippr/i18n"
+
 # = Snippr
 # ==== File based content management
 #
-# A snippr is a piece of HTML to be included in a website. They are plain text
-# files stored on the file system.
-#
-# == Snippr path
-#
-# You need to specify the path to the snippr directory:
-#
-#   Snippr.path = File.join(File.dirname(__FILE__), "..", "snipprs")
-#
-# When running on JRuby, you can also set the path via JVM properties. The property
-# you need to specify is defined in +SnipprPath::JVMProperty+. This allows system
-# administrators to change the path without having to touch your application.
-#
-# == Instantiation
-#
-# Instantiating a new snippr is done by passing in the path to the snippr file as
-# a String (including path separators):
-#
-#   Snippr.new "tariff/einheit"
-#
-# or by using multiple Strings or Symbols:
-#
-#   Snippr.new :tariff, :einheit
-#
-# === Dynamic values
-#
-# A snippr may contain placeholders to be replaced with dynamic values. Placeholders
-# are wrapped in curly braces.
-#
-#   <p>You're topup of {topup_amount} at {date_today} was successful.</p>
-#
-# To replace both {topup_amount} and {date_today} with a dynamic value, you just pass
-# in a Hash of placeholders and dynamic values when instantiating a new snippr.
-#
-#   Snippr.new :topup, :success, :topup_amount => number_to_currency(15), :date_today => Date.today
-#
-# The result will obviously be something like:
-#
-#   <p>You're topup of 15,00 &euro; at 2010-04-03 was successful.</p>
-#
-# == Links
-#
-# ...
-#
-# == Snippr content
-#
-# Returning the snippr content is done by calling the +to_s+ method. This will replace
-# all specified placeholders and links.
-#
-#   Snippr.new(:tariff, :einheit).to_s
-#
-# == Rails Helper
-#
-# When using the Snippr component with Rails, it automatically adds the +SnipprHelper+
-# module to your views. You can then use the +snippr+ helper method to load snippr files.
-#
-#   %h1 Topup successful
-#   .topup.info
-#     = snippr :topup, :success
-class Snippr
-  extend SnipprPath
-
-  # The snippr file extension.
-  SnipprFileExtension = ".snip"
-
-  # The comments wrapping a snippr.
-  SnipprWrapper = "<!-- starting with snippr: %s -->\n%s\n<!-- ending with snippr: %s -->"
-
-  # The fallback for a missing snippr.
-  MissingSnippr = '<samp class="missing snippr" />'
-
-  # Expects the paths to a snippr. Also accepts a Hash of placeholders
-  # to be replaced with dynamic values.
-  def initialize(*args)
-    @dynamic_values = args.last.kind_of?(Hash) ? args.pop : {}
-    @snippr_name = args.map { |arg| arg.kind_of?(Symbol) ? arg.to_s.lower_camelcase : arg }.join("/")
-  end
+# A snippr file is a piece of HTML or raw text to be included in a website. They are plain text
+# files stored on the file system. Snippr files end with ".snip" and are read from the Snippr path.
+module Snippr
+  extend Snippr::Path
+  extend Snippr::I18n
+
+  class << self
+
+    # The snippr file extension.
+    FileExtension = ".snip"
+
+    # The comments wrapping a snippr.
+    SnipprComments = "<!-- starting snippr: %s -->\n%s\n<!-- closing snippr: %s -->"
+
+    # The fallback tag for a missing snippr.
+    MissingSnipprTag = '<samp class="missing snippr" />'
+
+    # Expects the name of a snippr file. Also accepts a Hash of placeholders
+    # to be replaced with dynamic values.
+    def load(*args)
+      @dynamics = args.last.kind_of?(Hash) ? args.pop : {}
+      @name = name_from args
+      SnipprComments % [@name, content, @name]
+    end
+
+  private
+
+    # Returns the name of a snippr from a given Array of +args+.
+    def name_from(args)
+      args.map { |arg| arg.kind_of?(Symbol) ? arg.to_s.lower_camelcase : arg }.join("/") + locale
+    end
+
+    # Returns the raw snippr content or a +MissingSnipprTag+ in case the snippr
+    # file does not seem to exist.
+    def content
+      return MissingSnipprTag unless File.exist? file
+      
+      content = File.read(file).strip
+      insert_dynamics content
+      content
+    end
+
+    # Returns the complete path to a snippr file.
+    def file
+      File.join path, [@name, FileExtension].join
+    end
+
+    # Replaces placeholders found in a given snippr +content+ with dynamic values.
+    def insert_dynamics(content)
+      @dynamics.each { |placeholder, value| content.gsub! "{#{placeholder}}", value.to_s }
+    end
 
-  # Returns the snippr content.
-  def to_s
-    wrap_in_comments { snippr }
   end
-
-private
-
-  # Returns the raw snippr content or a +MissingSnippr+ tag in case
-  # the snippr file does not exist.
-  def snippr
-    return MissingSnippr unless File.exist? snippr_file
-    
-    snippr = File.read(snippr_file).strip
-    insert_dynamic_values snippr
-    snippr
-  end
-
-  # Replaces placeholders with dynamic values.
-  def insert_dynamic_values(snippr)
-    @dynamic_values.each { |placeholder, value| snippr.gsub! "{#{placeholder}}", value.to_s }
-  end
-
-  # Returns the complete path to a snippr file.
-  def snippr_file
-    File.join self.class.path, "#{@snippr_name}#{SnipprFileExtension}"
-  end
-
-  # Wraps the content from a given +block+ in descriptive comments.
-  def wrap_in_comments
-    SnipprWrapper % [@snippr_name, yield, @snippr_name]
-  end
-
-end
+end

data/lib/snippr.rb

@@ -1,4 +1,2 @@
-require "snippr/core_ext"
-require "snippr/snippr_path"
-require "snippr/snippr_helper"
-require "snippr/snippr"
+require "snippr/snippr"
+require "snippr/helper"

data/rails/init.rb

@@ -1 +1 @@
-require "snippr"
+require "snippr"

data/spec/fixtures/i18n/shop_de.snip

@@ -0,0 +1 @@
+<p>Willkommen in unserem Shop.</p>

data/spec/fixtures/i18n/shop_en.snip

@@ -0,0 +1 @@
+<p>Welcome to our shop.</p>

data/spec/snippr/snippr_spec.rb

@@ -5,49 +5,68 @@ describe Snippr do
     snippr_path = File.join File.dirname(__FILE__), "..", "fixtures"
     
     if RUBY_PLATFORM =~ /java/
-      SnipprPath::JavaLang::System.set_property SnipprPath::JVMProperty, snippr_path
+      Snippr::Path::JavaLang::System.set_property Snippr::Path::JVMProperty, snippr_path
     else
       Snippr.path = snippr_path
     end
+    Snippr.i18n = false
   end
 
   it "should return the content of a snippr" do
-    Snippr.new(:home).to_s.should include("<p>Home</p>")
+    Snippr.load(:home).should include("<p>Home</p>")
   end
 
   it "should return the content a snippr from a subfolder" do
-    Snippr.new("tariff/einheit").to_s.should include("<p>tariff: einheit</p>")
+    Snippr.load("tariff/einheit").should include("<p>tariff: einheit</p>")
   end
 
   it "should return the content a snippr from a subfolder specified via multiple arguments" do
-    Snippr.new(:tariff, :einheit).to_s.should include("<p>tariff: einheit</p>")
+    Snippr.load(:tariff, :einheit).should include("<p>tariff: einheit</p>")
   end
 
   it "should convert snake_case Symbols to lowerCamelCase Strings" do
-    Snippr.new(:topup, :some_error).to_s.should include("<p>Some error occurred.</p>")
+    Snippr.load(:topup, :some_error).should include("<p>Some error occurred.</p>")
   end
 
   it "should wrap the snippr in descriptive comments" do
-    Snippr.new(:home).to_s.should ==
-      "<!-- starting with snippr: home -->\n" <<
+    Snippr.load(:home).should ==
+      "<!-- starting snippr: home -->\n" <<
       "<p>Home</p>\n" <<
-      "<!-- ending with snippr: home -->"
+      "<!-- closing snippr: home -->"
   end
 
   it "should replace placeholders with dynamic values" do
-    snippr = Snippr.new :topup, :success, :topup_amount => "15,00 &euro;", :date_today => Date.today
-    snippr.to_s.should include("<p>You're topup of 15,00 &euro; at #{Date.today} was successful.</p>")
+    snippr = Snippr.load :topup, :success, :topup_amount => "15,00 &euro;", :date_today => Date.today
+    snippr.should include("<p>You're topup of 15,00 &euro; at #{Date.today} was successful.</p>")
   end
 
   it "should return a fallback wrapped in descriptive comments for missing snipprs" do
-    Snippr.new(:doesnotexist).to_s.should ==
-      "<!-- starting with snippr: doesnotexist -->\n" <<
+    Snippr.load(:doesnotexist).should ==
+      "<!-- starting snippr: doesnotexist -->\n" <<
       "<samp class=\"missing snippr\" />\n" <<
-      "<!-- ending with snippr: doesnotexist -->"
+      "<!-- closing snippr: doesnotexist -->"
   end
 
-  it "should raise an ArgumentError if the +path+ does not exist" do
-    lambda { Snippr.path = "does_not_exist" }.should raise_exception(ArgumentError)
+  describe "I18n" do
+    before { Snippr.i18n = true }
+
+    it "should prepend the current locale prefixed with a '_' to a snippr file" do
+      I18n.locale = :de
+      
+      Snippr.load(:i18n, :shop).should ==
+        "<!-- starting snippr: i18n/shop_de -->\n" <<
+        "<p>Willkommen in unserem Shop.</p>\n" <<
+        "<!-- closing snippr: i18n/shop_de -->"
+    end
+
+    it "should also work for other locales" do
+      I18n.locale = :en
+      
+      Snippr.load(:i18n, :shop).should ==
+        "<!-- starting snippr: i18n/shop_en -->\n" <<
+        "<p>Welcome to our shop.</p>\n" <<
+        "<!-- closing snippr: i18n/shop_en -->"
+    end
   end
 
-end
+end

data/spec/spec_helper.rb

@@ -1,4 +1,4 @@
 require "spec"
 require "date"
 
-require "snippr"
+require "snippr"

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 7
-  version: 0.1.7
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Daniel Harrington
@@ -14,13 +14,25 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-07 00:00:00 +02:00
+date: 2010-05-13 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: i18n
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -30,7 +42,7 @@ dependencies:
         - 8
         version: 1.2.8
   type: :development
-  version_requirements: *id001
+  version_requirements: *id002
 description: 
 email: me@rubiii.com
 executables: []
@@ -44,15 +56,18 @@ files:
 - Rakefile
 - README.rdoc
 - lib/snippr/core_ext.rb
+- lib/snippr/helper.rb
+- lib/snippr/i18n.rb
+- lib/snippr/path.rb
 - lib/snippr/snippr.rb
-- lib/snippr/snippr_helper.rb
-- lib/snippr/snippr_path.rb
 - lib/snippr.rb
 - rails/init.rb
 - spec/snippr/core_ext_spec.rb
 - spec/snippr/snippr_spec.rb
 - spec/spec_helper.rb
 - spec/fixtures/home.snip
+- spec/fixtures/i18n/shop_de.snip
+- spec/fixtures/i18n/shop_en.snip
 - spec/fixtures/tariff/einheit.snip
 - spec/fixtures/topup/someError.snip
 - spec/fixtures/topup/success.snip

data/lib/snippr/snippr_helper.rb

@@ -1,20 +0,0 @@
-# = SnipprHelper
-#
-# This module is automatically included into +ActionView::Base+ when using the Snippr
-# component with Rails. It provides a +snippr+ helper method for loading snipprs.
-#
-#   %h1 Topup successful
-#   .topup.info
-#     = snippr :topup, :success
-module SnipprHelper
-
-  # Returns a snippr specified via +args+.
-  def snippr(*args)
-    Snippr.new(*args).to_s
-  end
-
-end
-
-if defined? ActionView::Base
-  ActionView::Base.send :include, SnipprHelper
-end

data/lib/snippr/snippr_path.rb

@@ -1,36 +0,0 @@
-# = SnipprPath
-#
-# This module is included into the Snippr component for retrieving and setting
-# the path to the snippr files.
-module SnipprPath
-
-  # The snippr path JVM property.
-  JVMProperty = "cms.snippet.path"
-
-  # Returns the snippr path (from JVM properties if available).
-  def path
-    @path ||= JavaLang::System.get_property(JVMProperty) || "" if jruby?
-    @path ||= ""
-  end
-
-  # Sets the snippr path as a JVM property.
-  def path=(path)
-    @path = path.to_s
-  end
-
-private
-
-  # Returns whether the current Ruby platform is JRuby.
-  def jruby?
-    RUBY_PLATFORM =~ /java/
-  end
-
-  module_function :jruby?
-
-  if jruby?
-    module JavaLang
-      include_package "java.lang"
-    end
-  end
-
-end