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"] ==> [{"id"=>"0001", "type"=>"donut", "ingredients"=>[{"flour"=>200}, {"eggs"=>3}]}, {"id"=>"0002", "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.