transcriber 0.0.2 → 0.0.3

data/Guardfile

@@ -1,7 +1,7 @@
 guard 'rspec', cli: '--color' do
-  watch(%r{spec/spec_helper.rb})                       { "spec" }
-  watch(%r{^config\/(.*\/)*.*\.rb$})                   { "spec" }
+  watch(%r{spec/spec_helper.rb})     {"spec"}
+  watch(%r{^config\/(.*\/)*.*\.rb$}) {"spec"}
 
   watch(%r{^spec/.+_spec\.rb})
-  watch(%r{^lib/(.+)\.rb})                           { |m| "spec/#{m[1]}_spec.rb" }
-end
+  watch(%r{^lib/(.+)\.rb}) {|m| "spec/#{m[1]}_spec.rb"}
+end

data/README.md

@@ -1,13 +1,213 @@
 # Transcriber
 
+**Map from one or more input hashes** to instances of your model classes.
 
-## Installation
-
-  gem install transciber
+**Map to restful responses** from these model instances. (Some hypermedia magic happens here).
 
 ## Usage
 
-[See Examples](https://github.com/rodrigues/transcriber/tree/master/examples)
+### Input hash to model
+
+Given you have:
+
+    input = {
+      "result" => [
+        {
+          "id"       => 1938713897398,
+          "login"    => "jsmith180",
+          "username" => "John Smith",
+          "personal_info" => {
+            "birth_date"      => "1999-02-10",
+            "registered_date" => "2015-04-05"
+          }
+        },
+        {
+          "id"       => 92171987391873,
+          "login"    => "john_appleseed",
+          "username" => "John Appleseed",
+          "personal_info" => {
+            "birth_date"      => "1999-02-10",
+            "registered_date" => "2015-04-05"
+          }
+        }
+      ]
+    }
+
+And you want to transform this input in some instances of a `class User;   attr_accessor :id, :login, :name, :birth;   end`
+
+With transcriber you can parse the input to instances of `User`:
+
+    users = User.parse(input, :result)  # starts looking input hash from 'result' key
+
+Just define your `User` class like this:
+
+    class User < Transcriber::Resource
+      id
+      property :login
+      property :name,  field: :username                  # input hash key is different from resource key
+      property :birth, field: 'personal_info/birth_date' # digg hash path defined by '/', the last being the key
+    end
+
+### Model instances array to restful response hash
+
+    User.resources(users)
+=>
+
+    {
+      entries: [
+        {
+          id:    1938713897398,
+          login: "jsmith180",
+          name:  "John Smith",
+          birth: "1999-02-10",
+          href:  "http://app/api/users/1938713897398"
+        },
+        {
+          id:    92171987391873,
+          login: "john_appleseed",
+          name:  "John Appleseed",
+          birth: "1999-02-10",
+          href:  "http://app/api/users/92171987391873"
+        }
+      ]
+    }
+
+### Model instance to restful response hash
+
+    user.resource
+=>
+
+    {
+      id:    1938713897398,
+      login: "jsmith180",
+      name:  "John Smith",
+      birth: "1999-02-10",
+      href:  "http://app/api/users/1938713897398"
+    }
+
+### Input hash to restful response hash
+
+    User.transcribe(input, :result)
+
+## Embedding other resources
+
+### [`embeds_one`](https://github.com/rodrigues/transcriber/tree/master/examples/embeds_one)
+
+    class Customer < Transcriber::Resource
+      id field: 'cust_id'
+      embeds_one :address
+    end
+
+    class Address < Transcriber::Resource
+      property :street,
+      property :number, field: 'n'
+      properties :city, :state, :country
+    end
+
+    {
+      id:    1938713897398,
+      address: {
+        street:  'transcriber st.',
+        number:  '39',
+        city:    'hashland',
+        state:   'std',
+        country: 'ruby'
+      },
+      href:  "http://app/api/users/1938713897398"
+    }
+
+### [`embeds_many`](https://github.com/rodrigues/transcriber/tree/master/examples/embeds_many)
+
+    class OrderItems < Transcriber::Resource
+      property :item_id,    id: true      # default serialization: String
+      property :quantity,   type: Integer
+      property :unit_price, type: Float
+      property :amount,     type: Float
+    end
+
+    class Order < Transcriber::Resource
+      id
+      embeds_many :items, class: OrderItems
+    end
+
+    {
+      id: 739819813719387,
+      items: [
+        {
+          item_id:    1738917139871,
+          quantity:   18,
+          unit_price: 0.2,
+          amount:     3.6
+        },
+        {
+          item_id:    3987187398782,
+          quantity:   1,
+          unit_price: 39.9,
+          amount:     39.9
+        }
+      ]
+    }
+
+## Relations
+
+### `has_one`, `has_many` and `belongs_to`
+
+    class User < Transcriber::Resource
+      id
+      property   :login
+      has_one    :avatar
+      has_many   :achievements
+      belongs_to :guilda
+    end
+
+    {
+      id:    19837139879,
+      login: 'jsmith180',
+      links: [
+        {
+          rel:  'avatar',
+          href: 'http://app/api/users/19837139879/avatar'
+        },
+        {
+          rel:  'achievements',
+          href: 'http://app/api/users/19837139879/achievements'
+        },
+        {
+          rel:  'guilda',
+          href: 'http://app/api/users/19837139879/guilda
+        }
+      ]
+    }
+
+### embedding relations
+
+If you want your api to handle `http://app/api/users/19371897318937?include[]=avatar&include[]=guilda`
+
+    user = User.parse(input, include: [avatar_input, guilda_input]).first
+
+    {
+      id:    19837139879,
+      login: 'jsmith180',
+      avatar: {
+        name:   'K1ll3r',
+        specie: 'WTF'
+      },
+      guilda: {
+        name: 'K1ll3rs'
+      },
+      links: [
+        {
+          rel:  'achievements',
+          href: 'http://app/api/users/19837139879/achievements'
+        }
+      ]
+    }
+
+### [See more examples here](https://github.com/rodrigues/transcriber/tree/master/examples).
+
+## Installation
+
+    gem install transcriber
 
 ## Maintainers
 

data/examples/all.rb

@@ -11,4 +11,4 @@ Dir["examples/*/**.rb"].each do |file|
   puts
   puts
   load file
-end
+end

data/examples/embeds_many/invisible.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+$:.push 'lib'; require 'transcriber'
+
+class Root < Transcriber::Resource
+  property :key, id: true
+
+  property :locale, visible: false
+
+  embeds_many :names, class_name: 'Hash', visible: false
+  property :name,     values: proc {names[locale]}
+end
+
+
+@root = Root.parse({'locale' => 'pt-BR',
+                    'key' => 19190839,
+                    'names'   => {
+                      'en'    => 'Woot',
+                      'pt-BR' => 'Úia',
+                      'es'    => 'Me gusta'
+                   }}).first
+
+puts "root:     #{@root.inspect}"
+puts "resource: #{@root.resource}"

data/examples/embeds_many/simple.rb

@@ -8,7 +8,7 @@ class Root < Transcriber::Resource
   embeds_many :items
 end
 
-root = Root.parse({"items" => [{"id" => 2000}]}).first
+@root = Root.parse({"items" => [{"id" => 2000}]}).first
 
-puts "root:     #{root.inspect}"
-puts "resource: #{root.resource}"
+puts "root:     #{@root.inspect}"
+puts "resource: #{@root.resource}"

data/lib/transcriber/resource/key/property.rb

@@ -10,7 +10,8 @@ module Transcriber
       def initialize(name, options = {})
         super
         @serializer   = options.fetch(:type, Serialization::String)
-        @translations = options[:values].try(:invert)
+        @translations = options[:values]        if options[:values].kind_of?(Proc)
+        @translations = options[:values].invert if options[:values].kind_of?(Hash)
       end
     end
   end

data/lib/transcriber/resource/key/relation.rb

@@ -16,7 +16,7 @@ module Transcriber
         !has?
       end
 
-      def parse(value)
+      def parse(value, resource = nil)
         nil
       end
     end

data/lib/transcriber/resource/key.rb

@@ -15,6 +15,15 @@ module Transcriber
         resource.instance_eval &options[:if]
       end
 
+      def visible?(resource)
+        if present? resource
+          return true if options[:visible].nil?
+          return options[:visible] unless options[:visible].kind_of?(Proc)
+          return resource.instance_eval &options[:visible]
+        end
+        false
+      end
+
       def input_path
         return @input_path if @input_path
         path = InputPath.resolve(options, convert_input_keys)

data/lib/transcriber/resource/parser/embeddable.rb

@@ -2,10 +2,16 @@ module Transcriber
   class Resource
     module Parser
       module Embeddable
-        def parse(value)
-          parsed_value = resource_class.parse(value)
+        def parse(value, resource = nil)
+          parsed_value = parse? ? resource_class.parse(value) : value
           one? ? parsed_value.first : parsed_value
         end
+
+        private
+
+        def parse?
+          ![Hash, Array].include?(resource_class)
+        end
       end
     end
   end

data/lib/transcriber/resource/parser/property.rb

@@ -2,12 +2,19 @@ module Transcriber
   class Resource
     module Parser
       module Property
-        def parse(value)
-          translate serializer.serialize(value)
+        def parse(value, resource = nil)
+          translate(serializer.serialize(value), resource)
         end
 
-        def translate(value)
-          translations ? translations[value] : value
+        def translate(value, resource)
+          case translations
+          when nil
+            value
+          when Hash
+            translations[value]
+          when Proc
+            resource.instance_eval &translations
+          end
         end
       end
     end

data/lib/transcriber/resource/parser.rb

@@ -16,7 +16,7 @@ module Transcriber
         self.new.tap do |resource|
           keys.each do |key|
             value = digg(item, key.input_path)
-            resource.__send__("#{key.name}=", key.parse(value)) if key.present?(resource)
+            resource.__send__("#{key.name}=", key.parse(value, resource)) if key.present?(resource)
           end
         end
       end

data/lib/transcriber/resource/response/embeddable.rb

@@ -3,7 +3,7 @@ module Transcriber
     module Response
       module Embeddable
         def to_resource(parent)
-          return {} unless present?(parent)
+          return {} unless visible?(parent)
           embedded = parent.__send__(name)
           resource = one? ? embedded.resource : embedded.map(&:resource)
           {name => resource}

data/lib/transcriber/resource/response/property.rb

@@ -3,7 +3,7 @@ module Transcriber
     module Response
       module Property
         def to_resource(parent)
-          present?(parent) ? {name => parent.__send__(name)} : {}
+          visible?(parent) ? {name => parent.__send__(name)} : {}
         end
       end
     end

data/lib/transcriber/resource/response/relation.rb

@@ -4,7 +4,7 @@ module Transcriber
       module Relation
         def to_resource(parent)
           included = parent.__send__(name)
-          return {} unless present?(parent) and included
+          return {} unless visible?(parent) and included
           {name => resource_from_included(included)}
         end
 

data/lib/transcriber/resource/response.rb

@@ -6,6 +6,7 @@ module Transcriber
           {entries: model.map(&:resource)}
          : model.resource
       end
+      alias :resources :normalize
     end
   end
 end

data/lib/transcriber/resource.rb

@@ -40,6 +40,10 @@ module Transcriber
       self.class.relations.map {|key| key.to_relation(self)}
     end
 
+    def self.transcribe(input, options = {})
+      normalize(parse(input, options), options)
+    end
+
     def self.method_added(method_name)
       return unless not_allowed_names.include?(method_name.to_s)
       puts "warning: redefining '#{method_name}' may cause serious problems"

data/lib/transcriber/version.rb

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

data/spec/unit/key_spec.rb

@@ -16,7 +16,60 @@ describe Resource::Key do
     end
   end
 
-  describe "present?" do
+  describe "#visible?" do
+    context "when :visible option was defined" do
+      context "and :if option was defined with false" do
+        subject {Resource::Property.new(name, {if: proc {false}, visible: true})}
+        it "return false even when visible is true" do
+          subject.visible?(nil).should be_false
+        end
+      end
+
+      context "and it evaluates to false" do
+        subject {Resource::Property.new(name, {visible: false})}
+
+        it "returns false" do
+          subject.visible?(nil).should be_false
+        end
+      end
+
+      context "and it evaluates to true" do
+        subject {Resource::Property.new(name, {visible: true})}
+
+        it "returns true" do
+          subject.visible?(nil).should be_true
+        end
+      end
+
+      context "with a proc" do
+        context "and it evaluates true" do
+          subject {Resource::Property.new(name, {visible: proc {true}})}
+          it "returns true" do
+            subject.visible?("a").should be_true
+          end
+        end
+
+        context "and it evaluates false" do
+          subject {Resource::Property.new(name, {visible: proc {false}})}
+          it "returns false" do
+            subject.visible?("a").should be_false
+          end
+        end
+
+        context "and it depends on resource instance" do
+          subject {Resource::Property.new(name, {visible: proc {show}})}
+
+          it "uses it" do
+            resource = OpenStruct.new
+            resource.show = true
+            subject.visible?(resource).should be_true
+          end
+        end
+      end
+    end
+  end
+
+  describe "#present?" do
     context "when :if option was defined with a proc" do
       context "and it evaluates to false" do
         subject {Resource::Property.new(name, {if: proc {false}})}

data/spec/unit/resource/response/embeddable_spec.rb

@@ -17,9 +17,9 @@ describe Resource::Response::Embeddable do
       subject.to_resource(example).should == result
     end
 
-    context "when this key shouldn't be present on resource" do
+    context "when this key shouldn't be visible on resource" do
       it "returns an empty hash" do
-        subject.should_receive(:present?).and_return false
+        subject.should_receive(:visible?).and_return false
         subject.to_resource(example).should == {}
       end
     end

data/spec/unit/resource/response/property_spec.rb

@@ -12,9 +12,9 @@ describe Resource::Response::Property do
     subject.to_resource(customer).should == {login: "jackiechan2010"}
   end
 
-  context "when this key shouldn't be present on resource" do
+  context "when this key shouldn't be visible on resource" do
     it "returns an empty hash" do
-      subject.should_receive(:present?).and_return false
+      subject.should_receive(:visible?).and_return false
       customer = Customer.new.tap {|c| c.login = "jackiechan2010"}
       subject.to_resource(customer).should == {}
     end

data/spec/unit/resource/response/relation_spec.rb

@@ -9,9 +9,9 @@ describe Resource::Response do
     end
 
     context "#to_resource" do
-      context "when the key shouldn't be present on resource" do
+      context "when the key shouldn't be visible on resource" do
         it "returns an empty hash" do
-          subject.should_receive(:present?).and_return false
+          subject.should_receive(:visible?).and_return false
           subject.to_resource(example).should == {}
         end
       end

metadata

@@ -1,104 +1,100 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: transcriber
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.0.3
   prerelease: 
-  version: 0.0.2
 platform: ruby
-authors: 
+authors:
 - Victor Rodrigues
 - William Yokoi
-- "Guilherme Guimar\xC3\xA3es Filho"
+- Guilherme Guimarães Filho
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-11 00:00:00 -03:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-08-15 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activesupport
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70342384534920 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3.0"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: i18n
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70342384534920
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: &70342384534420 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.6"
+      - !ruby/object:Gem::Version
+        version: '0.6'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70342384534420
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70342384533960 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "2.6"
+      - !ruby/object:Gem::Version
+        version: '2.6'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: guard
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70342384533960
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: &70342384533500 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.5"
+      - !ruby/object:Gem::Version
+        version: '0.5'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: guard-rspec
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *70342384533500
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: &70342384533040 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.4"
+      - !ruby/object:Gem::Version
+        version: '0.4'
   type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: growl
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *70342384533040
+- !ruby/object:Gem::Dependency
+  name: growl
+  requirement: &70342384532580 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.0"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :development
-  version_requirements: *id006
-description: ""
-email: 
+  prerelease: false
+  version_requirements: *70342384532580
+description: ''
+email:
 - victorcrodrigues@gmail.com
 - thekina@gmail.com
 - guilherme.filho@locaweb.com.br
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - Guardfile
 - README.md
 - Rakefile
 - examples/all.rb
+- examples/embeds_many/invisible.rb
 - examples/embeds_many/simple.rb
 - examples/embeds_many/with_class_name.rb
 - examples/embeds_many/with_if.rb
@@ -173,35 +169,31 @@ files:
 - spec/unit/resource_spec.rb
 - spec/unit/response_spec.rb
 - transcriber.gemspec
-has_rdoc: true
 homepage: http://github.com/rodrigues/transcriber
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
-summary: ""
-test_files: 
+summary: ''
+test_files:
 - spec/integration/has_many_spec.rb
 - spec/integration/property_spec.rb
 - spec/spec_helper.rb