From 5017e3c21176303cce2eb3a1ec12d1476a689948 Mon Sep 17 00:00:00 2001 From: Nicolas Dandrimont Date: Thu, 9 Jan 2014 03:46:35 +0100 Subject: [PATCH] Add documentation for the attribute access DSL --- docs/language/api.rst | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 57c64e7..cd57464 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -38,6 +38,37 @@ Hy features a number special forms that are used to help generate correct Python AST. The following are "special" forms, which may have behavior that's slightly unexpected in some situations. +. +- + +.. versionadded:: 0.9.13 + + +`.` is used to perform attribute access on objects. It uses a small DSL +to allow quick access to attributes and items in a nested datastructure. + +For instance, + +.. code-block:: clj + + (. foo bar baz [(+ 1 2)] frob) + +Compiles down to + +.. code-block:: python + + foo.bar.baz[1 + 2].frob + +`.` compiles its first argument (in the example, `foo`) as the object on +which to do the attribute dereference. It uses bare symbols as +attributes to access (in the example, `bar`, `baz`, `frob`), and +compiles the contents of lists (in the example, ``[(+ 1 2)]``) for +indexation. Other arguments throw a compilation error. + +Access to unknown attributes throws an :exc:`AttributeError`. Access to +unknown keys throws an :exc:`IndexError` (on lists and tuples) or a +:exc:`KeyError` (on dicts). + -> -- @@ -560,8 +591,8 @@ Example usages: .. note:: `get` raises a KeyError if a dictionary is queried for a non-existing key. -.. note:: `get` raises an IndexError if a list is queried for an index that is - out of bounds. +.. note:: `get` raises an IndexError if a list or a tuple is queried for an index + that is out of bounds. global