added usage information

README.rst

@@ -15,4 +15,58 @@ Usage
 
 ``manipulator`` mainly exposes three functions, ``get``, ``update``, and ``set``.
 ``get`` retrieves data, ``update`` transforms it based on its form, and ``set``
-transforms it by simply resetting.
+transforms it by simply resetting. Transformations can be applied in place or
+on a copy. The default is in place, because copying is expensive. If you want a
+copy of the data, set the keyword argument ``in_place`` to ``True``.
+
+It uses a query "language" not unlike CSS, albeit much, much simpler. The only
+two entities in this "language" are IDs—denoted by ``#``—and Classes—denoted by
+``.``. IDs are unique, whereas Classes are collections of all leaf values that
+conform.
+
+A few motivating examples (a more exhaustive list can be found in the ``test`` directory):
+
+.. code-block:: python
+    import manipulator
+
+    manipulator.get({"k": [1, [2], 3]}, "#k #1 #0")
+    # => 2 (note how list indices are coerced into integers)
+
+    manipulator.get([{"k": "v"}, {"k": "v2", "k2": "v3"}], ".k")
+    # => ["v", "v2"]
+
+    manipulator.get([{"k": "v"},
+                     {"k": {
+                        "a": [{"k": 10}, {"k": 11}]
+                      }
+                     }], ".k #1 #a .k")
+    # => [10, 11]
+
+    manipulator.set({"k": [1, [2], 3]}, "#k #1 #0", 3)
+    # => {"k": [1, [3], 3]} (in place)
+
+    manipulator.set({"k": [1, [2], 3]}, "#k #1 #0", 3, in_place=False)
+    # => {"k": [1, [3], 3]} (will create a copy of the data)
+
+    manipulator.set([{"k": "v"},
+                     {"k": {
+                        "a": [{"k": 10}, {"k": 11}]
+                      }
+                     }], ".k #1 #a .k", 100)
+    # => [{"k": "v"}, {"k": {"a": [{"k": 100}, {"k": 100}]}}]
+
+    manipulator.update({"k": [1, [2], 3]}, "#k #1 #0", lambda x: x-1)
+    # => {"k": [1, [1], 3]} (in place, use in_place=False to copy)
+
+    manipulator.set([{"k": "v"},
+                     {"k": {
+                        "a": [{"k": 10}, {"k": 11}]
+                      }
+                     }], ".k #1 #a .k", lambda x: x+1)
+    # => [{"k": "v"}, {"k": {"a": [{"k": 11}, {"k": 12}]}}]
+
+
+That is all.
+
+
+Have fun!

manipulator/query.py

@@ -26,7 +26,7 @@ def select_id(name, data):
 def select_class(name, data):
     if isinstance(data, list):
         return manipulate_all(name, data), [select_id(name, elem)[1] for elem in data]
-    return name, data[name]
+    return name, [data[name]]
 
 
 def lookup_selector(start):