/ README.rst
README.rst
1 jq.py: a lightweight and flexible JSON processor 2 ================================================ 3 4 This project contains Python bindings for 5 `jq <https://jqlang.github.io/jq/>`_ 1.7.1. 6 7 Installation 8 ------------ 9 10 Wheels are built for various Python versions and architectures on Linux and Mac OS X. 11 On these platforms, you should be able to install jq with a normal pip install: 12 13 .. code-block:: sh 14 15 pip install jq 16 17 If a wheel is not available, 18 the source for jq 1.7.1 is built. 19 This requires: 20 21 * Autoreconf 22 23 * The normal C compiler toolchain, such as gcc and make. 24 25 * libtool 26 27 * Python headers. 28 29 Alternatively, set the environment variable ``JQPY_USE_SYSTEM_LIBS`` to ``1`` when installing the package 30 to use the libjq and libonig versions available on the system rather than building them. 31 32 Debian, Ubuntu or relatives 33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 34 35 If on Debian, Ubuntu or relatives, running the following command should be sufficient: 36 37 .. code-block:: sh 38 39 apt-get install autoconf automake build-essential libtool python-dev 40 41 Red Hat, Fedora, CentOS or relatives 42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 43 44 If on Red Hat, Fedora, CentOS, or relatives, running the following command should be sufficient: 45 46 .. code-block:: sh 47 48 yum groupinstall "Development Tools" 49 yum install autoconf automake libtool python python-devel 50 51 Mac OS X 52 ~~~~~~~~ 53 54 If on Mac OS X, you probably want to install 55 `Xcode <https://developer.apple.com/xcode/>`_ and `Homebrew <http://brew.sh/>`_. 56 Once Homebrew is installed, you can install the remaining dependencies with: 57 58 .. code-block:: sh 59 60 brew install autoconf automake libtool 61 62 Usage 63 ----- 64 65 Using jq requires three steps: 66 67 #. Call ``jq.compile()`` to compile a jq program. 68 #. Call an input method on the compiled program to supply the input. 69 #. Call an output method on the result to retrieve the output. 70 71 For instance: 72 73 .. code-block:: python 74 75 import jq 76 77 assert jq.compile(".+5").input_value(42).first() == 47 78 79 Input methods 80 ~~~~~~~~~~~~~ 81 82 Call ``.input_value()`` to supply a valid JSON value, such as the values returned from ``json.load``: 83 84 .. code-block:: python 85 86 import jq 87 88 assert jq.compile(".").input_value(None).first() == None 89 assert jq.compile(".").input_value(42).first() == 42 90 assert jq.compile(".").input_value(0.42).first() == 0.42 91 assert jq.compile(".").input_value(True).first() == True 92 assert jq.compile(".").input_value("hello").first() == "hello" 93 94 Call ``.input_values()`` to supply multiple valid JSON values, such as the values returned from ``json.load``: 95 96 .. code-block:: python 97 98 import jq 99 100 assert jq.compile(".+5").input_values([1, 2, 3]).all() == [6, 7, 8] 101 102 Call ``.input_text()`` to supply unparsed JSON text: 103 104 .. code-block:: python 105 106 import jq 107 108 assert jq.compile(".").input_text("null").first() == None 109 assert jq.compile(".").input_text("42").first() == 42 110 assert jq.compile(".").input_text("0.42").first() == 0.42 111 assert jq.compile(".").input_text("true").first() == True 112 assert jq.compile(".").input_text('"hello"').first() == "hello" 113 assert jq.compile(".").input_text("1\n2\n3").all() == [1, 2, 3] 114 115 Pass ``slurp=True`` to ``.input_text()`` to read the entire input into an array: 116 117 .. code-block:: python 118 119 import jq 120 121 assert jq.compile(".").input_text("1\n2\n3", slurp=True).first() == [1, 2, 3] 122 123 You can also call the older ``input()`` method by passing: 124 125 * a valid JSON value, such as the values returned from ``json.load``, as a positional argument 126 * unparsed JSON text as the keyword argument ``text`` 127 128 For instance: 129 130 .. code-block:: python 131 132 import jq 133 134 assert jq.compile(".").input("hello").first() == "hello" 135 assert jq.compile(".").input(text='"hello"').first() == "hello" 136 137 Output methods 138 ~~~~~~~~~~~~~~ 139 140 Calling ``first()`` on the result will run the program with the given input, 141 and return the first output element. 142 143 .. code-block:: python 144 145 import jq 146 147 assert jq.compile(".").input_value("hello").first() == "hello" 148 assert jq.compile("[.[]+1]").input_value([1, 2, 3]).first() == [2, 3, 4] 149 assert jq.compile(".[]+1").input_value([1, 2, 3]).first() == 2 150 151 Call ``text()`` instead of ``first()`` to serialise the output into JSON text: 152 153 .. code-block:: python 154 155 assert jq.compile(".").input_value("42").text() == '"42"' 156 157 When calling ``text()``, if there are multiple output elements, each element is represented by a separate line: 158 159 .. code-block:: python 160 161 assert jq.compile(".[]").input_value([1, 2, 3]).text() == "1\n2\n3" 162 163 Call ``all()`` to get all of the output elements in a list: 164 165 .. code-block:: python 166 167 assert jq.compile(".[]+1").input_value([1, 2, 3]).all() == [2, 3, 4] 168 169 Call ``iter()`` to get all of the output elements as an iterator: 170 171 .. code-block:: python 172 173 iterator = iter(jq.compile(".[]+1").input_value([1, 2, 3])) 174 assert next(iterator, None) == 2 175 assert next(iterator, None) == 3 176 assert next(iterator, None) == 4 177 assert next(iterator, None) == None 178 179 Arguments 180 ~~~~~~~~~ 181 182 Calling ``compile()`` with the ``args`` argument allows predefined variables to be used within the program: 183 184 .. code-block:: python 185 186 program = jq.compile("$a + $b + .", args={"a": 100, "b": 20}) 187 assert program.input_value(3).first() == 123 188 189 Convenience functions 190 ~~~~~~~~~~~~~~~~~~~~~ 191 192 Convenience functions are available to get the output for a program and input in one call: 193 194 .. code-block:: python 195 196 assert jq.first(".[] + 1", [1, 2, 3]) == 2 197 assert jq.first(".[] + 1", text="[1, 2, 3]") == 2 198 assert jq.text(".[] + 1", [1, 2, 3]) == "2\n3\n4" 199 assert jq.all(".[] + 1", [1, 2, 3]) == [2, 3, 4] 200 assert list(jq.iter(".[] + 1", [1, 2, 3])) == [2, 3, 4] 201 202 Original program string 203 ~~~~~~~~~~~~~~~~~~~~~~~ 204 205 The original program string is available on a compiled program as the ``program_string`` attribute: 206 207 .. code-block:: python 208 209 program = jq.compile(".") 210 assert program.program_string == "."