cwyckoff-babel_icious 0.0.4.7 → 0.0.4.8

data/MIT-LICENSE

@@ -19,4 +19,4 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,6 +1,6 @@
 = Babel-icious
 
-A flexible and scalable mapping tool that currently only supports mapping hashes and xml.
+Are you tired of ugly data munging in Rails controllers or models, for instance.  Well, Babel_icious is a flexible mapping tool for mapping hashes and xml.  It allows you define mappings separate from your code, keeping your code clean and focused on its core responsibilities.  The mappings themselves are then easy to understand and modify if and when your code changes.
 
 
 == Author
@@ -15,7 +15,8 @@ Add a mapper for JSON.
 
 == Examples
 
-Mappings are set up by calling passing mapping 'coordinates' to a 'config' block on the Mapper class:
+
+Babel_icious mappings should ideally be written in their own file or files, separate from the code that actually requires mapping.  Just include the mapping files at runtime.  A mapping is configured by passing mapping 'coordinates' to a 'config' block on the Mapper class:
 
  Babelicious::Mapper.config(:foo) do |m|
   
@@ -28,7 +29,7 @@ Mappings are set up by calling passing mapping 'coordinates' to a 'config' block
   
  end
 
-The 'config' method takes a symbol as its first argument which serves as an identification tag for that mapping.  The second argument is a block where you indiate the details of your mapping.  This should include a direction indicator and individual mapping 'coordinates'.
+The 'config' method takes a symbol as its first argument which serves as an identification tag for that mapping.  The second argument is a block where you indiate the details of your mapping, which should include a direction indicator and individual mapping 'coordinates', as well as a series of 'to' and 'from' mappings.  The line
 
  m.direction :from => :xml, :to => :hash
 
@@ -47,6 +48,15 @@ the slash indicates that "bar" is a nested hash within "foo".  The target xml th
 with the value of "bar" from the hash above placed in the nested <foo> tags in the xml.
 
 
+=== Translation
+
+When you want to translate the mappings, simply call:
+
+ Babelicious::Mapper.translate(:foo, source)
+
+passing the tag for the mapping and the actual source you want to translate from.  The above line would translate the :foo mapping above.
+
+
 === Conditions
 
 You can also qualify your mappings with the methods "unless" and "when".  For example, if you do not want to translate mappings that lack a value, simply add an "unless" method:
@@ -62,11 +72,13 @@ if the value at "foo/bar" is empty or nil, "foo/bar" will not be translated.  Ad
 will only translate if the value at "foo/bar" begins with a capital "M".
 
 
-== Customized mappings
+=== Customized mappings
+
+Babel_icious provides a few powerful ways of handling customized mappings.
 
-=== .to
+==== .to
 
-If your target mapping is conditional, you may use the .to method which takes a block
+If your *target* mapping depends upon one or more conditions, you may use the .to method which takes a block.  The block yields the value of the source mapping for you to evaluate any conditions necessary.
 
    m.from("foo/bar").to do |value|
      if(value == "baz")
@@ -76,18 +88,17 @@ If your target mapping is conditional, you may use the .to method which takes a
      end
    end
 
-Note that the .to method must be used in conjunction with .from, which takes a simple string for the source mapping.
+The above mapping, for example, will use "value/is/baz" as its target mapping if the source value is "baz", otherwise, the mapping defaults to "value/is/something/else".  (Note that the .to method must be used in conjunction with .from, which takes a simple string for the source mapping.)
 
-
-=== .customize
+==== .customize
 
 If you have a complex mapping and need to customize it in some way, use the .customize method and pass it a block.  The block yields the source object for you to manipulate.  Let's say you're mapping xml to a hash where the xml source looks like:
 
-  <event><progress><statuses><status><code>Foo</code><message>Bar</message></status></statuses></progress></event>
+  <statuses><status><code>Foo</code><message>Bar</message></status></statuses>
 
 You need to map statuses so that the output looks like [{"name" => "Foo", "text" => "Bar"}].  Here's how you could customize your mapping:
 
-  m.map(:from => "event/progress/statuses", :to => "event/status_code").customize do |node|
+  m.map(:from => "statuses", :to => "status_code").customize do |node|
     res = []
     node.elements.map {|nd| res << {"name" => nd.child_content("code"), "text" => nd.child_content("message")}
     res
@@ -95,29 +106,20 @@ You need to map statuses so that the output looks like [{"name" => "Foo", "text"
 
 This mapping would produce:
 
-  {"event" => {"status_code" => [{"name" => "Foo", "text" => "Bar"}]}}
+  {"status_code" => [{"name" => "Foo", "text" => "Bar"}]}
 
 A more common use case is concatenation of nested xml nodes.  Given the following xml:
 
-  <event><institutions><institution>FOO</institution><institution>BAR</institution><institution>BAZ</institution></institutions></event>
+  <institutions><institution>FOO</institution><institution>BAR</institution><institution>BAZ</institution></institutions>
 
-You could easily concatentate institutions with the following mapping:
+You could easily concatentate the institutions nested within the <institutions> node with the following mapping:
 
-  m.map(:from => "event/institutions", :to => "event/concatenated_institutions").customize do |node|
+  m.map(:from => "institutions", :to => "concatenated_institutions").customize do |node|
     node.concatenate_children("|")
   end
 
-which would produce
+This mapping would produce
 
-  {"event" => {"concatenated_institutions" => "FOO|BAR|BAZ"}}
+  {"concatenated_institutions" => "FOO|BAR|BAZ"}
 
 (note: 'concatentate' is a convenience method I've added to the libxml XML::Node object)
-
-
-== Translation
-
-Finally, when you want to translate the mappings, simply call:
-
- Babelicious::Mapper.translate(:foo, source)
-
-passing the tag for the mapping and the actual source you want to translate from.

data/lib/babel_icious/core_ext/libxml_node.rb

@@ -3,7 +3,14 @@ require 'xml/libxml'
 module BabeliciousNodeHacks
 
   def concatenate_children(glue)
-    res = self.children.inject('') {|a,b| a << "#{b.content}#{glue}"}
+    self.children.reject { }
+    res = self.children.inject('') do |a,b| 
+      unless b.content.strip.empty?
+        a << "#{b.content.strip}#{glue.strip}"
+      else 
+        a
+      end 
+    end 
     res.chop
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cwyckoff-babel_icious
 version: !ruby/object:Gem::Version 
-  version: 0.0.4.7
+  version: 0.0.4.8
 platform: ruby
 authors: 
 - Chris Wyckoff