NOTE: LazyDoc is currently in alpha and is not quite ready for use.

An implementation of the Embedded Document pattern for POROs.

LazyDoc provides a declarative DSL for extracting deeply nested values from a JSON document. The embedded JSON is lazily parsed so that needed attributes from the document are only parsed when accessed. Finally, parsed values are cached so that subsequent access does not access the JSON again.

Currently, LazyDoc only supports JSON. XML support will be added later.

Add this line to your application's Gemfile:

gem 'lazy_doc'

1. Basic usage. access :name will look for a property called 'name' at the top level of the embedded document.
2. via: access :job, via: [:profile, :occupation] will look for a property called 'job' by parsing through 'profile' -> 'occupation'.
3. finally: access :initials, finally: lambda { |initials| initials.upcase } will call the supplied block, passing in 'initials,' and will return the result of that block.
4. as: access :profile, as: Profile will pass the sub-document found at 'profile' into a new 'Profile' object, and will return the newly constructed Profile object. This is great for constructing nested LazyDoc relationships.

class User
    include LazyDoc::DSL

    access :name                                        # Access the attribute "name"
    access :address, via: :street_address               # Access the attribute "street_address"
    access :job, via: [:profile, :occupation, :title]   # Access the attribute "title" found at "profile" -> "occupation"

    def initialize(json)
      lazily_embed(json)                                # Initialize the LazyDoc object
    end
end

user = User.new(json)
puts user.name
puts user.address
puts user.job

1. DONE - Full path parsing more than just top level. ex: access :name, by: [:profile, :basic_info, :name]
2. Error handling for incorrectly specified paths
3. Exception handling when a json does not contain a path, but that is ok.
4. DONE - Transforms. ex: access :name, finally: lambda { |name| name.gsub('-',' ') }
5. DONE - Objects from sub-trees. ex: access :profile, as: Profile (This would construct a LazyDoc Profile object and pass the json found at "profile" to it)
6. Collections.
   • Map. For example, extract array of customer names from array of customers. ex: access :customers, extract: :name
   • Objects from collection. Instead of extracting just the name, extract whole objects like in #5. ex: access :customers, as: Customer
7. Joins
   • Using previously defined attributes. ex: join :address, from: [:street, :city, :state:, :zip]
   • Defining attributes in place.
8. Throw exception immediately when trying to use incompatible options (ex: 'finally' and 'as')
9. Multiple simple paths in one line (ex: access :name, :street, :city, :state)
10. XML support

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request