Update docs

1 files changed, 73 insertions, 14 deletions

diff --git a/README.rst b/README.rst
index ed1c287..aa8cf49 100644
--- a/README.rst
+++ b/README.rst
@@ -59,15 +59,53 @@ Once Homebrew is installed, you can install the remaining dependencies with:
 Usage
 -----
 
-Call ``jq.compile`` to compile a jq program.
-Call ``.input()`` on the compiled program to supply an input value.
-The input must either be:
+Using jq requires three steps:
 
-* a valid JSON value, such as the values returned from ``json.load``
-* unparsed JSON text passed as the keyword argument ``text``.
+#. Call ``jq.compile()`` to compile a jq program.
+#. Call an input method on the compiled program to supply the input.
+#. Call an output method on the result to retrieve the output.
 
-Calling ``first()`` on the result will run the program with the given input,
-and return the first output element.
+For instance:
+
+.. code-block:: python
+
+    import jq
+
+    assert jq.compile(".+5").input_value(42).first() == 47
+
+Input methods
+~~~~~~~~~~~~~
+
+Call ``.input_value()`` to supply a valid JSON value, such as the values returned from ``json.load``:
+
+.. code-block:: python
+
+    import jq
+
+    assert jq.compile(".").input_value(None).first() == None
+    assert jq.compile(".").input_value(42).first() == 42
+    assert jq.compile(".").input_value(0.42).first() == 0.42
+    assert jq.compile(".").input_value(True).first() == True
+    assert jq.compile(".").input_value("hello").first() == "hello"
+
+Call ``.input_text()`` to supply unparsed JSON text:
+
+.. code-block:: python
+
+    import jq
+
+    assert jq.compile(".").input_text("null").first() == None
+    assert jq.compile(".").input_text("42").first() == 42
+    assert jq.compile(".").input_text("0.42").first() == 0.42
+    assert jq.compile(".").input_text("true").first() == True
+    assert jq.compile(".").input_text('"hello"').first() == "hello"
+
+You can also call the older ``input()`` method by passing:
+
+* a valid JSON value, such as the values returned from ``json.load``, as a positional argument
+* unparsed JSON text passed as the keyword argument ``text``
+
+For instance:
 
 .. code-block:: python
 
@@ -75,43 +113,61 @@ and return the first output element.
 
     assert jq.compile(".").input("hello").first() == "hello"
     assert jq.compile(".").input(text='"hello"').first() == "hello"
-    assert jq.compile("[.[]+1]").input([1, 2, 3]).first() == [2, 3, 4]
-    assert jq.compile(".[]+1").input([1, 2, 3]).first() == 2
+
+Return methods
+~~~~~~~~~~~~~~
+
+Calling ``first()`` on the result will run the program with the given input,
+and return the first output element.
+
+.. code-block:: python
+
+    import jq
+
+    assert jq.compile(".").input_value("hello").first() == "hello"
+    assert jq.compile("[.[]+1]").input_value([1, 2, 3]).first() == [2, 3, 4]
+    assert jq.compile(".[]+1").input_value([1, 2, 3]).first() == 2
 
 Call ``text()`` instead of ``first()`` to serialise the output into JSON text:
 
 .. code-block:: python
 
-    assert jq.compile(".").input("42").text() == '"42"'
+    assert jq.compile(".").input_value("42").text() == '"42"'
 
 When calling ``text()``, if there are multiple output elements, each element is represented by a separate line:
 
 .. code-block:: python
 
-    assert jq.compile(".[]").input([1, 2, 3]).text() == "1\n2\n3"
+    assert jq.compile(".[]").input_value([1, 2, 3]).text() == "1\n2\n3"
 
 Call ``all()`` to get all of the output elements in a list:
 
 .. code-block:: python
 
-    assert jq.compile(".[]+1").input([1, 2, 3]).all() == [2, 3, 4]
+    assert jq.compile(".[]+1").input_value([1, 2, 3]).all() == [2, 3, 4]
 
 Call ``iter()`` to get all of the output elements as an iterator:
 
 .. code-block:: python
 
-    iterator = iter(jq.compile(".[]+1").input([1, 2, 3]))
+    iterator = iter(jq.compile(".[]+1").input_value([1, 2, 3]))
     assert next(iterator, None) == 2
     assert next(iterator, None) == 3
     assert next(iterator, None) == 4
     assert next(iterator, None) == None
 
+Arguments
+~~~~~~~~~
+
 Calling ``compile()`` with the ``args`` argument allows predefined variables to be used within the program:
 
 .. code-block:: python
 
     program = jq.compile("$a + $b + .", args={"a": 100, "b": 20})
-    assert program.input(3).first() == 123
+    assert program.input_value(3).first() == 123
+
+Convenience functions
+~~~~~~~~~~~~~~~~~~~~~
 
 Convenience functions are available to get the output for a program and input in one call:
 
@@ -123,6 +179,9 @@ Convenience functions are available to get the output for a program and input in
     assert jq.all(".[] + 1", [1, 2, 3]) == [2, 3, 4]
     assert list(jq.iter(".[] + 1", [1, 2, 3])) == [2, 3, 4]
 
+Original program string
+~~~~~~~~~~~~~~~~~~~~~~~
+
 The original program string is available on a compiled program as the ``program_string`` attribute:
 
 .. code-block:: python