Jsonwalk

Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/jsonwalk. To experiment with that code, run bin/console for an interactive prompt.

TODO: Delete this and the text above, and describe your gem

Installation

Add this line to your application's Gemfile:

gem 'jsonwalk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonwalk

Usage

jsonwalk provides functions to walk in a JSON tree created with JSON.parse

- JsonWalk.walk
    selects the list values from a JSON tree using a given path of names
    parameters :
        root: the top of the JSON tree
              usually the value returned by JSON.parse
        path: the list of names which form the json path
                each element may be a name, a selection, an integer or 
            the .. operator which causes a backward move
    return : 
        the value or the list of values which match the path

- JsonWalk.forward
    move into a JSON tree one step deeper 
    parameters : 
            node: a node or a list of nodes belonging to a JSON tree, 
                          node may be an array. In this case all the values are returned
            branch: the  name of the object 
    output :
        a list which contains the values corresponding to branch
        nil if node is nil or branch has not been founded
- JsonWalk.select
    filter out a node list based on the given operator 
    parameters : 
        node: a list of nodes belonging to a JSON tree
        branch: the name of the object on which the selection will be done
        condition: the string which must be matched by the value
        operator: define how the name/value pair has to match 
                == value must be equal to condition
                =~ value must match (regex) the condition
                != value must NOT be equal to condition
                !~ value must NOT  match (regex) the condition
    output :
        a list of nodes which match the condition
        this is a subset of node
- JsonWalk.backward
    move into a JSON tree one step back to the root 
    parameters :
        parent: a single node of a JSON tree
        node: a node or a list of nodes belonging to a JSON tree
    output: 
        the list of the parent childern which include node as descendant

Examples

Consider this Json object provided as the pjson2.txt file :

{ "food": [ { "id": "0001", "type": "donut", "ingredients": [ { "flour": 200, "eggs": 3, } ] }, { "id": "0002", "type": "cookie", "ingredients": [ { "flour": 100, "chocolate": 50, } ] },
] }

You can use the file test/cli_jsonwalk.rb to parse it with the syntax: cli_jsonwalk.rb pjson2.txt path

1. get the value corresponding to the name food : $ ruby test_jsonwalk.rb pjson2.txt food ["food"] ==> ["type"=>"donut", "ingredients"=>[{"flour"=>200, "eggs"=>3]}, "type"=>"cookie", "ingredients"=>[{"flour"=>100, "chocolate"=>50]}]

2. get the values corresponding to the path food,type $ ruby test_jsonwalk.rb pjson2.txt food/type ["food", "type"] ==> ["donut", "cookie"]

3. get the ingredients for the elements of type donut $ ruby test_jsonwalk.rb pjson2.txt food/type==donut/ingredients ["food", "type==donut", "ingredients"] ==> [["flour"=>200, "eggs"=>3]]

4. get the type of elements which needs chocolate $ ruby test_jsonwalk.rb pjson2.txt food/ingredients/chocolate/../../type ["food", "ingredients", "chocolate", "..", "..", "type"] ==> ["cookie"]

5. get the second ingredient for the type donut $ ruby test_jsonwalk.rb pjson2.txt food/type==donut/ingredients/0/1 ["food", "type==donut", "ingredients", 0, 1] ==> "eggs"=>3

Note that the selection type==donut does not remove the food array but propagate it

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/PJO2/jsonwalk.

License

The gem is available as open source under the terms of the MIT License.