Tutorial Start using ObjectPath's interactive shell in no time

We'll work with the following JSON document:

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      { 
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      { 
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      { 
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ]
  }
}

Installing and running

Python

Install the newest version from GitHub:

$ git clone https://github.com/objectpath/ObjectPath.git
$ cd ObjectPath
$ python shell -h
usage: shell [-h] [-u URL] [-xml] [-d] [FILE]

Command line options

positional arguments:
  FILE               File name

optional arguments:
  -h, --help         show this help message and exit
  -u URL, --url URL  URL containing JSON document.
  -xml               [EXPERIMENTAL] Expect XML input.
  -d, --debug        Debbuging on/off.

To use localization features you need python-tz package installed on your machine.

You can also run ObjectPath in PyPy, the faster Python implementation:

pypy objectpath

Basics

Before getting your hands dirty read through the language basics, even if you're an experienced programmer - some sugar can be found here.

Basic arithmetics

ObjectPath supports common arithmetics:

2+2*2 -> 6
(2+2)*2 -> 8
8/5 -> 1.6 
17 % 3 -> 2 #remainder of division

Working with strings

ObjectPath provides a range of tools to manipulate strings. Strings are written as:

"text" or 'text'

Strings can be concatenated by + sign:

"Hello "+"World!" -> "Hello World!"

Numbers can be concatenated with strings if string is on the left-hand side of + sign

"Hello "+2+"!" -> "Hello World!"
2+" Hello!" -> error (in JS you'll see NaN, which is a bug)
""+2+" Hello!" -> "2 Hello!"

In the Python version of ObjectPath it's also possible to do some crazy things like:

3*"a" -> "aaa"
"Hello %s"%"World!" -> "Hello World!"

To access specific parts of the string, use the following:

# To get the first character of the string
"Hello World!"[0] -> "H" # We count letters starting from 0!
# To get the last character of a string:
"Hello World!"[-1] -> "!"
# To get the substring "Word"
slice("Hello World!",[6,11]) -> "World"
# or in the Javascript version:
"Hello World!"[6:11] -> "World"

ObjectPath also offers a vast range of functions that can do the following tricks on strings (currently available only in the Python version):

len("Hello") -> 5
upper("Hello") -> "HELLO"
lower("Hello") -> "hello"
title("Hello world") -> "Hello World"
capitalize("hello world") -> "Hello world"
split("hello world"," ") -> ["Hello","world"]
replace("hello world!","world","moon") -> "Hello moon!"
# replace can also take advantage of regular expressions
replace("hello world!","l[^l]","r") -> "Helr worr!"

Functions can be nested:

upper(replace("hello world!","world","moon")) -> "HELLO MOON!"

Simple queries

Putting the boring stuff aside we fast forward to queries. Simple queries starts with $ character. It indicates the root of the document. To show the whole document write:

$

ObjectPath is like paths to files in your operating system. . means we want to go one level deeper in JSON document (equivalent to / on Unix/Mac or \ on Windows in the paths to files).

$.store.book

This returns an array. You can select a specific element from it, filter etc:

$.store.book[1] # get the second book
$.store.book[-1] # get the last book
$.store.book[2:4] # get the 3rd and 4th book

We can also get specific elements based on their properties:

$.store.book[@.price is 0.99] # get books of price 0.99

@ points to the current element from books. In other words, [ iterates over the array of books and for each element checks if condition inside square parenthesis is met. @ tells ObjectPath that price is an property of each book, not a string.

To make it even more interesting we can filter it even further by getting only the specific fields from results:

$.store.book[@.price is 0.99].(price, isbn) # WARNING! works only in Python verion! filter attributes from the result

When we don't know where in the document are prices, we can search for all of them by:

$..price # searches for any attribute named price in the document
$..price[@ > 0.99] # returns all prices greater than 0.99

In the last example we used @ to indicate current element of an array of prices.