Treet

Comparisons and transformation between trees of files and JSON blobs

The "JSON blobs" that are supported are not unlimited in structure, but must define:

  • hashes, where are the values are either where the values are all scalars or of hashes where the values are all scalars
  • or arrays of hashes as described above.

Installation

Add this line to your application's Gemfile:

gem 'treet'

And then execute:

$ bundle

Or install it yourself as:

$ gem install treet

Usage - Command Line

treet expand [path] [jsonfile]
treet explode [jsonfile] [rootdir]
treet import [rootdir] [xrefkey]

Usage - API

require 'treet'

hash = Treet::Hash.new(jsonfile)
repo = Treet::Repo.new(directory)
farm = Treet::Farm.new(rootdir, :xref => 'label')

hash = repo.to_hash
repo = hash.to_repo(root)
hash = farm.export

Treet.init(jsonfile, root) # when jsonfile contains an array which is exploded to multiple files

Concepts

A repo is a directory that contains other files & directories. Any text files in this tree structure must contain JSON-formatted data.

A farm is a directory containing one or more repos. When a farm is exported to JSON, each record is augmented with an xref value that contains the root filename of that repo.

For example:

farm = Treet::Farm.new(rootdir, :xref => 'keycode')
puts farm.export

should produce something like:

{
  "subdir1": {
    "field": "value"
  },
  "subdir2": {
    "field": "value",
    "field2": "value2"
  },
  "xref": {
    "keycode": "repo-dir-name"
  }
}

Structures

All the nodes at the top level are mapped to subdirectories.

At the second level, arrays elements are converted to individual subdirectories. Subdirectories are named with unique digest values computed from the data contents. This means that duplicate entries are not allowed.

Contributing

  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

TODO

  • why is caching built into treet farm? The data on disk could change. Caching doesn't belong here.
  • Enforce limitation on structure depth (top-level elements can contain flat hashes or arrays, nothing else)
  • refac: move diff stuff from hash.rb to Treet::Diff class, to encapsulate the structure of a diff (array of arrays); create methods for hunting for special stuff in a diff
  • Check all exceptions for explicit classes