xenial (1) hy.1.gz

Provided by: python3-hy_0.11.1-1_all bug

NAME

       hy - hy Documentation [image: Hy] [image]

       Try Hy https://try-hy.appspot.com

       PyPI   https://pypi.python.org/pypi/hy

       Source https://github.com/hylang/hy

       List   hylang-discuss

       IRC    #hy on Freenode

       Build status
              Travis CI.UNINDENT

              Hy is a wonderful dialect of Lisp that's embedded in Python.

              Since  Hy  transforms  its  Lisp  code  into  the  Python Abstract Syntax Tree, you have the whole
              beautiful world of Python at your fingertips, in Lisp form!

              Contents:

QUICKSTART

       [image: Karen Rustard's Cuddles] [image]

       (Thanks to Karen Rustad for Cuddles!)

       HOW TO GET HY REAL FAST:

       1. Create a Virtual Python Environment.

       2. Activate your Virtual Python Environment.

       3. Install hy from PyPI with pip install hy.

       4. Start a REPL with hy.

       5. Type stuff in the REPL:

             => (print "Hy!")
             Hy!
             => (defn salutationsnm [name] (print (+ "Hy " name "!")))
             => (salutationsnm "YourName")
             Hy YourName!

             etc

       6. Hit CTRL-D when you're done.

       OMG! That's amazing! I want to write a Hy program.

       7. Open up an elite programming editor and type:

             (print "I was going to code in Python syntax, but then I got Hy.")

       8. Save as awesome.hy.

       9. And run your first Hy program:

             hy awesome.hy

       10.
          Take a deep breath so as to not hyperventilate.

       11.
          Smile villainously and sneak off to your hydeaway and do unspeakable things.

TUTORIAL

       Welcome to the Hy tutorial!

       In a nutshell, Hy is a Lisp dialect, but one that converts its structure  into  Python  ...  literally  a
       conversion  into Python's abstract syntax tree!  (Or to put it in more crude terms, Hy is lisp-stick on a
       Python!)

       This is pretty cool because it means Hy is several things:

          • A Lisp that feels very Pythonic

          • For Lispers, a great way to use Lisp's crazy powers but in the wide world of Python's libraries (why
            yes, you now can write a Django application in Lisp!)

          • For Pythonistas, a great way to start exploring Lisp, from the comfort of Python!

          • For everyone: a pleasant language that has a lot of neat ideas!

   Basic intro to Lisp for Pythonistas
       Okay, maybe you've never used Lisp before, but you've used Python!

       A "hello world" program in Hy is actually super simple. Let's try it:

          (print "hello world")

       See?  Easy!  As you may have guessed, this is the same as the Python version of:

          print "hello world"

       To add up some super simple math, we could do:

          (+ 1 3)

       Which would return 4 and would be the equivalent of:

          1 + 3

       What  you'll  notice  is that the first item in the list is the function being called and the rest of the
       arguments are the arguments being passed in.  In fact, in Hy (as with most Lisps) we can pass in multiple
       arguments to the plus operator:

          (+ 1 3 55)

       Which would return 59.

       Maybe  you've  heard of Lisp before but don't know much about it.  Lisp isn't as hard as you might think,
       and Hy inherits from Python, so Hy is a great way to start learning Lisp.  The main thing that's  obvious
       about  Lisp  is  that  there's a lot of parentheses.  This might seem confusing at first, but it isn't so
       hard.  Let's look at some simple math that's wrapped in a bunch of parentheses that we could  enter  into
       the Hy interpreter:

          (setv result (- (/ (+ 1 3 88) 2) 8))

       This would return 38.  But why?  Well, we could look at the equivalent expression in python:

          result = ((1 + 3 + 88) / 2) - 8

       If  you  were  to  try to figure out how the above were to work in python, you'd of course figure out the
       results by solving each inner parenthesis.  That's the same basic idea in Hy.  Let's  try  this  exercise
       first in Python:

          result = ((1 + 3 + 88) / 2) - 8
          # simplified to...
          result = (92 / 2) - 8
          # simplified to...
          result = 46 - 8
          # simplified to...
          result = 38

       Now let's try the same thing in Hy:

          (setv result (- (/ (+ 1 3 88) 2) 8))
          ; simplified to...
          (setv result (- (/ 92 2) 8))
          ; simplified to...
          (setv result (- 46 8))
          ; simplified to...
          (setv result 38)

       As you probably guessed, this last expression with setv means to assign the variable "result" to 38.

       See?  Not too hard!

       This  is  the  basic premise of Lisp. Lisp stands for "list processing"; this means that the structure of
       the program is actually lists of lists.  (If you're familiar with Python lists, imagine the  entire  same
       structure  as  above  but  with square brackets instead, any you'll be able to see the structure above as
       both a program and a datastructure.)  This is easier to understand with more examples, so let's  write  a
       simple Python program, test it, and then show the equivalent Hy program:

          def simple_conversation():
              print "Hello!  I'd like to get to know you.  Tell me about yourself!"
              name = raw_input("What is your name? ")
              age = raw_input("What is your age? ")
              print "Hello " + name + "!  I see you are " + age + " years old."

          simple_conversation()

       If we ran this program, it might go like:

          Hello!  I'd like to get to know you.  Tell me about yourself!
          What is your name? Gary
          What is your age? 38
          Hello Gary!  I see you are 38 years old.

       Now let's look at the equivalent Hy program:

          (defn simple-conversation []
             (print "Hello!  I'd like to get to know you.  Tell me about yourself!")
             (setv name (raw-input "What is your name? "))
             (setv age (raw-input "What is your age? "))
             (print (+ "Hello " name "!  I see you are "
                        age " years old.")))

          (simple-conversation)

       If  you  look  at  the  above program, as long as you remember that the first element in each list of the
       program is the function (or macro... we'll get to those later) being called and that  the  rest  are  the
       arguments,  it's  pretty  easy to figure out what this all means.  (As you probably also guessed, defn is
       the Hy method of defining methods.)

       Still, lots of people find this confusing at first because there's so many  parentheses,  but  there  are
       plenty of things that can help make this easier: keep indentation nice and use an editor with parenthesis
       matching (this will help you figure out what each parenthesis pairs up with) and  things  will  start  to
       feel comfortable.

       There  are some advantages to having a code structure that's actually a very simple data structure as the
       core of Lisp is based on.  For one thing, it means that your programs are easy  to  parse  and  that  the
       entire  actual  structure  of  the  program is very clearly exposed to you.  (There's an extra step in hy
       where the structure you see is converted to Python's own representations ... in  "purer"  Lisps  such  as
       Common Lisp or Emacs Lisp, the data structure you see in the code and the data structure that is executed
       is much more literally close.)

       Another implication of this is macros: if a program's structure is a simple data  structure,  that  means
       you  can  write  code  that  can  write code very easily, meaning that implementing entirely new language
       features can be very fast.  Previous to Hy, this wasn't very possible for Python programmers ... now  you
       too can make use of macros' incredible power (just be careful to not aim them footward)!

   Hy is a Lisp-flavored Python
       Hy  converts  to  Python's  own  abstract syntax tree, so you'll soon start to find that all the familiar
       power of python is at your fingertips.

       You have full access to Python's data types and standard library in Hy.  Let's experiment  with  this  in
       the hy interpreter:

          => [1 2 3]
          [1, 2, 3]
          => {"dog" "bark"
          ... "cat" "meow"}
          ...
          {'dog': 'bark', 'cat': 'meow'}
          => (, 1 2 3)
          (1, 2, 3)

       If  you  are  familiar with other Lisps, you may be interested that Hy supports the Common Lisp method of
       quoting:

          => '(1 2 3)
          (1L 2L 3L)

       You also have access to all the built-in types' nice methods:

          => (.strip " fooooo   ")
          "fooooo"

       What's this?  Yes indeed, this is precisely the same as:

          " fooooo   ".strip()

       That's right---Lisp with dot notation!  If we have this string assigned as a variable, we can also do the
       following:

          (setv this-string " fooooo   ")
          (this-string.strip)

       What about conditionals?:

          (if (try-some-thing)
            (print "this is if true")
            (print "this is if false"))

       As you can tell above, the first argument to if is a truth test, the second argument is the body if true,
       and the third argument (optional!)  is if false (ie. else).

       If you need to do more complex conditionals, you'll find that  you  don't  have  elif  available  in  Hy.
       Instead, you should use something called cond.  In Python, you might do something like:

          somevar = 33
          if somevar > 50:
              print "That variable is too big!"
          elif somevar < 10:
              print "That variable is too small!"
          else:
              print "That variable is jussssst right!"

       In Hy, you would do:

          (cond
           [(> somevar 50)
            (print "That variable is too big!")]
           [(< somevar 10)
            (print "That variable is too small!")]
           [true
            (print "That variable is jussssst right!")])

       What  you'll  notice  is  that  cond  switches  off between a some statement that is executed and checked
       conditionally for true or falseness, and then a bit of code to execute  if  it  turns  out  to  be  true.
       You'll  also notice that the else is implemented at the end simply by checking for true -- that's because
       true will always be true, so if we get this far, we'll always run that one!

       You might notice above that if you have code like:

          (if some-condition
            (body-if-true)
            (body-if-false))

       But wait!  What if you want to execute more than one statement in the body of one of these?

       You can do the following:

          (if (try-some-thing)
            (do
              (print "this is if true")
              (print "and why not, let's keep talking about how true it is!))
            (print "this one's still simply just false"))

       You can see that we used do to wrap multiple statements.  If you're familiar with other  Lisps,  this  is
       the equivalent of progn elsewhere.

       Comments start with semicolons:

          (print "this will run")
          ; (print "but this will not")
          (+ 1 2 3)  ; we'll execute the addition, but not this comment!

       Looping is not hard but has a kind of special structure.  In Python, we might do:

          for i in range(10):
              print "'i' is now at " + str(i)

       The equivalent in Hy would be:

          (for [i (range 10)]
            (print (+ "'i' is now at " (str i))))

       You can also import and make use of various Python libraries.  For example:

          (import os)

          (if (os.path.isdir "/tmp/somedir")
            (os.mkdir "/tmp/somedir/anotherdir")
            (print "Hey, that path isn't there!"))

       Python's context managers (with statements) are used like this:

          (with [[f (open "/tmp/data.in")]]
            (print (.read f)))

       which is equivalent to:

          with open("/tmp/data.in") as f:
              print f.read()

       And yes, we do have List comprehensions!  In Python you might do:

          odds_squared = [
            pow(num, 2)
            for num in range(100)
            if num % 2 == 1]

       In Hy, you could do these like:

          (setv odds-squared
            (list-comp
              (pow num 2)
              (num (range 100))
              (= (% num 2) 1)))

          ; And, an example stolen shamelessly from a Clojure page:
          ; Let's list all the blocks of a Chessboard:

          (list-comp
            (, x y)
            (x (range 8)
             y "ABCDEFGH"))

          ; [(0, 'A'), (0, 'B'), (0, 'C'), (0, 'D'), (0, 'E'), (0, 'F'), (0, 'G'), (0, 'H'),
          ;  (1, 'A'), (1, 'B'), (1, 'C'), (1, 'D'), (1, 'E'), (1, 'F'), (1, 'G'), (1, 'H'),
          ;  (2, 'A'), (2, 'B'), (2, 'C'), (2, 'D'), (2, 'E'), (2, 'F'), (2, 'G'), (2, 'H'),
          ;  (3, 'A'), (3, 'B'), (3, 'C'), (3, 'D'), (3, 'E'), (3, 'F'), (3, 'G'), (3, 'H'),
          ;  (4, 'A'), (4, 'B'), (4, 'C'), (4, 'D'), (4, 'E'), (4, 'F'), (4, 'G'), (4, 'H'),
          ;  (5, 'A'), (5, 'B'), (5, 'C'), (5, 'D'), (5, 'E'), (5, 'F'), (5, 'G'), (5, 'H'),
          ;  (6, 'A'), (6, 'B'), (6, 'C'), (6, 'D'), (6, 'E'), (6, 'F'), (6, 'G'), (6, 'H'),
          ;  (7, 'A'), (7, 'B'), (7, 'C'), (7, 'D'), (7, 'E'), (7, 'F'), (7, 'G'), (7, 'H')]

       Python has support for various fancy argument and keyword arguments.  In Python we might see:

          >>> def optional_arg(pos1, pos2, keyword1=None, keyword2=42):
          ...   return [pos1, pos2, keyword1, keyword2]
          ...
          >>> optional_arg(1, 2)
          [1, 2, None, 42]
          >>> optional_arg(1, 2, 3, 4)
          [1, 2, 3, 4]
          >>> optional_arg(keyword1=1, pos2=2, pos1=3, keyword2=4)
          [3, 2, 1, 4]

       The same thing in Hy:

          => (defn optional-arg [pos1 pos2 &optional keyword1 [keyword2 42]]
          ...  [pos1 pos2 keyword1 keyword2])
          => (optional-arg 1 2)
          [1 2 None 42]
          => (optional-arg 1 2 3 4)
          [1 2 3 4]

       If  you're running a version of Hy past 0.10.1 (eg, git master), there's also a nice new keyword argument
       syntax:

          => (optional-arg :keyword1 1
          ...              :pos2 2
          ...              :pos1 3
          ...              :keyword2 4)
          [3, 2, 1, 4]

       Otherwise, you can always use apply.  But what's apply?

       Are you familiar with passing in *args and **kwargs in Python?:

          >>> args = [1 2]
          >>> kwargs = {"keyword2": 3
          ...           "keyword1": 4}
          >>> optional_arg(*args, **kwargs)

       We can reproduce this with apply:

          => (setv args [1 2])
          => (setv kwargs {"keyword2" 3
          ...              "keyword1" 4})
          => (apply optional-arg args kwargs)
          [1, 2, 4, 3]

       There's also a dictionary-style keyword arguments construction that looks like:

          (defn another-style [&key {"key1" "val1" "key2" "val2"}]
            [key1 key2])

       The difference here is that since it's a dictionary, you can't rely  on  any  specific  ordering  to  the
       arguments.

       Hy also supports *args and **kwargs.  In Python:

          def some_func(foo, bar, *args, **kwargs):
            import pprint
            pprint.pprint((foo, bar, args, kwargs))

       The Hy equivalent:

          (defn some-func [foo bar &rest args &kwargs kwargs]
            (import pprint)
            (pprint.pprint (, foo bar args kwargs)))

       Finally, of course we need classes!  In Python, we might have a class like:

          class FooBar(object):
              """
              Yet Another Example Class
              """
              def __init__(self, x):
                  self.x = x

              def get_x(self):
                  """
                  Return our copy of x
                  """
                  return self.x

       In Hy:

          (defclass FooBar [object]
            "Yet Another Example Class"
            [[--init--
              (fn [self x]
                (setv self.x x)
                ; Currently needed for --init-- because __init__ needs None
                ; Hopefully this will go away :)
                None)]

             [get-x
              (fn [self]
                "Return our copy of x"
                self.x)]])

       You can also do class-level attributes.  In Python:

          class Customer(models.Model):
              name = models.CharField(max_length=255)
              address = models.TextField()
              notes = models.TextField()

       In Hy:

          (defclass Customer [models.Model]
            [[name (models.CharField :max-length 255})]
             [address (models.TextField)]
             [notes (models.TextField)]])

   Hy <-> Python interop
       By importing Hy, you can use Hy directly from Python!

       If you save the following in greetings.hy:

          (defn greet [name] (print "hello from hy," name))

       Then you can use it directly from python, by importing hy before importing the module. In Python:

          import hy
          import greetings

          greetings.greet("Foo")

       You can also declare a function in python (or even a class!) and use it in Hy!

       If you save the following in greetings.py in Python:

          def greet(name):
              print("hello, %s" % (name))

       You can use it in Hy:

          (import greetings)
          (.greet greetings "foo")

       To use keyword arguments, you can use in greetings.py:

          def greet(name, title="Sir"):
              print("Greetings, %s %s" % (title,name))

          (import greetings)
          (.greet greetings "Foo")
          (.greet greetings "Foo" "Darth")
          (apply (. greetings greet) ["Foo"] {"title" "Lord"})

       Which would output:

          Greetings, Sir Foo

          Greetings, Darth Foo

          Greetings, Lord Foo

   Protips!
       Hy  also  features  something  known  as  the  "threading macro", a really neat feature of Clojure's. The
       "threading macro" (written as ->) is used to avoid deep nesting of expressions.

       The threading macro inserts each expression into the next expression's first argument place.

       Let's take the classic:

          (loop (print (eval (read))))

       Rather than write it like that, we can write it as follows:

          (-> (read) (eval) (print) (loop))

       Now, using python-sh, we can show how the threading macro (because of python-sh's setup) can be used like
       a pipe:

          => (import [sh [cat grep wc]])
          => (-> (cat "/usr/share/dict/words") (grep "-E" "^hy") (wc "-l"))
          210

       Which, of course, expands out to:

          (wc (grep (cat "/usr/share/dict/words") "-E" "^hy") "-l")

       Much more readable, no? Use the threading macro!

HY STYLE GUIDE

          “You  know, Minister, I disagree with Dumbledore on many counts…but you cannot deny he’s got style…” —
          Phineas Nigellus Black, Harry Potter and the Order of the Phoenix

       The Hy style guide intends to be a set of ground rules for the Hyve (yes, the Hy community prides  itself
       in  appending  Hy to everything) to write idiomatic Hy code. Hy derives a lot from Clojure & Common Lisp,
       while always maintaining Python interopability.

   Prelude
   The Tao of Hy
          Ummon asked the head monk, "What sutra are you lecturing on?"
          "The Nirvana Sutra."
          "The Nirvana Sutra has the Four Virtues, hasn't it?"
          "It has."
          Ummon asked, picking up a cup, "How many virtues has this?"
          "None at all," said the monk.
          "But ancient people said it had, didn't they?" said Ummon.
          "What do you think of what they said?"
          Ummon struck the cup and asked, "You understand?"
          "No," said the monk.
          "Then," said Ummon, "You'd better go on with your lectures on the sutra."
          — the (koan) macro

       The following illustrates a brief list of design decisions that went into the making of Hy.

       • Look like a Lisp; DTRT with it (e.g. dashes turn to underscores, earmuffs turn to all-caps).

       • We're still Python. Most of the internals translate 1:1 to Python internals.

       • Use Unicode everywhere.

       • Fix the bad decisions in Python 2 when we can (see true_division).

       • When in doubt, defer to Python.

       • If you're still unsure, defer to Clojure.

       • If you're even more unsure, defer to Common Lisp.

       • Keep in mind we're not Clojure. We're not Common Lisp. We're Homoiconic Python, with  extra  bits  that
         make sense.

   Layout & Indentation
       • Avoid trailing spaces. They suck!

       • Indentation  shall  be  2  spaces  (no hard tabs), except when matching the indentation of the previous
         line.

            ;; Good (and preferred)
            (defn fib [n]
              (if (<= n 2)
                n
                (+ (fib (- n 1)) (fib (- n 2)))))

            ;; Still okay
            (defn fib [n]
              (if (<= n 2) n (+ (fib (- n 1)) (fib (- n 2)))))

            ;; Still okay
            (defn fib [n]
              (if (<= n 2)
                n
                (+ (fib (- n 1)) (fib (- n 2)))))

            ;; Hysterically ridiculous
            (defn fib [n]
                (if (<= n 2)
                        n ;; yes, I love randomly hitting the space key
                  (+ (fib (- n 1)) (fib (- n 2)))))

       • Parentheses must never be left alone, sad and lonesome on their own line.

            ;; Good (and preferred)
            (defn fib [n]
              (if (<= n 2)
                n
                (+ (fib (- n 1)) (fib (- n 2)))))

            ;; Hysterically ridiculous
            (defn fib [n]
              (if (<= n 2)
                n
                (+ (fib (- n 1)) (fib (- n 2)))
              )
            )  ; GAH, BURN IT WITH FIRE

       • Vertically align let blocks.

            (let [[foo (bar)]
                  [qux (baz)]]
               (foo qux))

       • Inline comments shall be two spaces from the end of the code; they must always have a space between the
         comment character and the start of the comment. Also, try to not comment the obvious.

          ;; Good
          (setv ind (dec x))  ; indexing starts from 0

          ;; Style-compliant but just states the obvious
          (setv ind (dec x))  ; sets index to x-1

          ;; Bad
          (setv ind (dec x));typing words for fun

   Coding Style
       • As  a  convention,  try  not  to  use  def  for  anything  other than global variables; use setv inside
         functions, loops, etc.

            ;; Good (and preferred)
            (def *limit* 400000)

            (defn fibs [a b]
              (while true
                (yield a)
                (setv (, a b) (, b (+ a b)))))

            ;; Bad (and not preferred)
            (defn fibs [a b]
              (while true
                (yield a)
                (def (, a b) (, b (+ a b)))))

       • Do not use s-expression syntax where vector syntax is intended.  For instance, the fact that the former
         of  these  two examples works is just because the compiler isn't overly strict. In reality, the correct
         syntax in places such as this is the latter.

            ;; Bad (and evil)
            (defn foo (x) (print x))
            (foo 1)

            ;; Good (and preferred)
            (defn foo [x] (print x))
            (foo 1)

       • Use the threading macro or the threading tail macros when  encountering  deeply  nested  s-expressions.
         However,  be  judicious  when  using  them.  Do  use them when clarity and readability improves; do not
         construct convoluted, hard to understand expressions.

            ;; Preferred
            (def *names*
              (with [f (open "names.txt")]
                (-> (.read f) (.strip) (.replace "\"" "") (.split ",") (sorted))))

            ;; Not so good
            (def *names*
              (with [f (open "names.txt")]
              (sorted (.split "," (.replace "\"" "" (.strip (.read f)))))))

            ;; Probably not a good idea
            (defn square? [x]
              (->> 2 (pow (int (sqrt x))) (= x)))

       • Clojure-style dot notation is preferred over the direct call of the object's method, though  both  will
         continue to be supported.

            ;; Good
            (with [fd (open "/etc/passwd")]
              (print (.readlines fd)))

            ;; Not so good
            (with [fd (open "/etc/passwd")]
              (print (fd.readlines)))

   Conclusion
          “Fashions fade, style is eternal” —Yves Saint Laurent

       This  guide  is just a set of community guidelines, and obviously, community guidelines do not make sense
       without an active community. Contributions are welcome. Join us at #hy in freenode, blog about it,  tweet
       about it, and most importantly, have fun with Hy.

   Thanks
       • This guide is heavily inspired from @paultag 's blog post Hy Survival Guide

       • The Clojure Style Guide

DOCUMENTATION INDEX

       Contents:

   Command Line Interface
   hy
   Command Line Options
       -c <command>
              Execute the Hy code in command.

                 $ hy -c "(print (+ 2 2))"
                 4

       -i <command>
              Execute the Hy code in command, then stay in REPL.

       -m <module>
              Execute the Hy code in module, including defmain if defined.

              The  -m flag terminates the options list so that all arguments after the module name are passed to
              the module in sys.argv.

              New in version 0.10.2.

       --spy  Print equivalent Python code before executing. For example:

                 => (defn salutationsnm [name] (print (+ "Hy " name "!")))
                 def salutationsnm(name):
                     return print(((u'Hy ' + name) + u'!'))
                 => (salutationsnm "YourName")
                 salutationsnm(u'YourName')
                 Hy YourName!
                 =>

              New in version 0.9.11.

       --show-tracebacks
              Print extended tracebacks for Hy exceptions.

              New in version 0.9.12.

       -v     Print the Hy version number and exit.

   hyc
   Command Line Options
       file[, fileN]
              Compile Hy code to Python bytecode. For example, save the following code as hyname.hy:

                 (defn hy-hy [name]
                   (print (+ "Hy " name "!")))

                 (hy-hy "Afroman")

              Then run:

                 $ hyc hyname.hy
                 $ python hyname.pyc
                 Hy Afroman!

   hy2py
       New in version 0.10.1.

   Command Line Options
       -s

       --with-source
              Show the parsed source structure.

       -a

       --with-ast
              Show the generated AST.

       -np

       --without-python
              Do not show the Python code generated from the AST.

   Hy (the language)
       WARNING:
          This is incomplete; please consider contributing to the documentation effort.

   Theory of Hy
       Hy maintains, over everything else, 100% compatibility in both directions with Python itself. All Hy code
       follows a few simple rules. Memorize this, as it's going to come in handy.

       These rules help ensure that Hy code is idiomatic and interfaceable in both languages.

          • Symbols  in  earmufs  will be translated to the upper-cased version of that string. For example, foo
            will become FOO.

          • UTF-8 entities will be encoded using punycode and prefixed with hy_. For  instance,    will  become
            hy_w7h,  will become hy_g6h, and i♥u will become hy_iu_t0x.

          • Symbols  that  contain dashes will have them replaced with underscores. For example, render-template
            will become render_template. This means that  symbols  with  dashes  will  shadow  their  underscore
            equivalents, and vice versa.

   Built-Ins
       Hy  features  a  number of 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.

   .
       New in version 0.10.0.

       . is used to perform attribute access on objects. It uses a small DSL to allow quick access to attributes
       and items in a nested data structure.

       For instance,

          (. foo bar baz [(+ 1 2)] frob)

       Compiles down to:

          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 AttributeError. Access to unknown keys throws  an  IndexError  (on
       lists and tuples) or a KeyError (on dictionaries).

   ->
       ->  (or  the  threading  macro) is used to avoid nesting of expressions. The threading macro inserts each
       expression into the next expression's first argument place. The following code demonstrates this:

          => (defn output [a b] (print a b))
          => (-> (+ 4 6) (output 5))
          10 5

   ->>
       ->> (or the threading tail macro) is similar to the  threading  macro,  but  instead  of  inserting  each
       expression  into  the next expression's first argument, it appends it as the last argument. The following
       code demonstrates this:

          => (defn output [a b] (print a b))
          => (->> (+ 4 6) (output 5))
          5 10

   apply
       apply is used to apply an optional list of arguments and an optional dictionary of kwargs to a function.

       Usage: (apply fn-name [args] [kwargs])

       Examples:

          (defn thunk []
            "hy there")

          (apply thunk)
          ;=> "hy there"

          (defn total-purchase [price amount &optional [fees 1.05] [vat 1.1]]
            (* price amount fees vat))

          (apply total-purchase [10 15])
          ;=> 173.25

          (apply total-purchase [10 15] {"vat" 1.05})
          ;=> 165.375

          (apply total-purchase [] {"price" 10 "amount" 15 "vat" 1.05})
          ;=> 165.375

   and
       and is used in logical expressions. It takes at least two parameters. If all parameters evaluate to True,
       the last parameter is returned. In any other case, the first false value will be returned. Example usage:

          => (and True False)
          False

          => (and True True)
          True

          => (and True 1)
          1

          => (and True [] False True)
          []

       NOTE:
          and short-circuits and stops evaluating parameters as soon as the first false is encountered.

          => (and False (print "hello"))
          False

   assert
       assert  is  used  to  verify  conditions  while  the  program is running. If the condition is not met, an
       AssertionError is raised. assert may take one or two parameters.  The first parameter is the condition to
       check, and it should evaluate to either True or False. The second parameter, optional, is a label for the
       assert, and is the string that will be raised with the AssertionError. For example:

          (assert (= variable expected-value))

          (assert False)
          ; AssertionError

          (assert (= 1 2) "one should equal two")
          ; AssertionError: one should equal two

   assoc
       assoc is used to associate a key with a value in a dictionary or to set an index of a list to a value. It
       takes  at least three parameters: the data structure to be modified, a key or index, and a value. If more
       than three parameters are used, it will associate in pairs.

       Examples of usage:

          =>(let [[collection {}]]
          ... (assoc collection "Dog" "Bark")
          ... (print collection))
          {u'Dog': u'Bark'}

          =>(let [[collection {}]]
          ... (assoc collection "Dog" "Bark" "Cat" "Meow")
          ... (print collection))
          {u'Cat': u'Meow', u'Dog': u'Bark'}

          =>(let [[collection [1 2 3 4]]]
          ... (assoc collection 2 None)
          ... (print collection))
          [1, 2, None, 4]

       NOTE:
          assoc modifies the datastructure in place and returns None.

   break
       break is used to break out from a loop. It terminates the loop immediately.  The following example has an
       infinite while loop that is terminated as soon as the user enters k.

          (while True (if (= "k" (raw-input "? "))
                        (break)
                        (print "Try again")))

   cond
       cond  can be used to build nested if statements. The following example shows the relationship between the
       macro and its expansion:

          (cond [condition-1 result-1]
                [condition-2 result-2])

          (if condition-1 result-1
            (if condition-2 result-2))

       As shown below, only the first matching result block is executed.

          => (defn check-value [value]
          ...  (cond [(< value 5) (print "value is smaller than 5")]
          ...        [(= value 5) (print "value is equal to 5")]
          ...        [(> value 5) (print "value is greater than 5")]
          ...        [True (print "value is something that it should not be")]))

          => (check-value 6)
          value is greater than 5

   continue
       continue returns execution to the start of a loop. In the following example, (side-effect1) is called for
       each iteration. (side-effect2), however, is only called on every other value in the list.

          ;; assuming that (side-effect1) and (side-effect2) are functions and
          ;; collection is a list of numerical values

          (for [x collection]
            (do
              (side-effect1 x)
              (if (% x 2)
                (continue))
              (side-effect2 x)))

   dict-comp
       dict-comp  is  used  to create dictionaries. It takes three or four parameters.  The first two parameters
       are for controlling the return value (key-value pair) while the third is used  to  select  items  from  a
       sequence.  The  fourth and optional parameter can be used to filter out some of the items in the sequence
       based on a conditional expression.

          => (dict-comp x (* x 2) [x (range 10)] (odd? x))
          {1: 2, 3: 6, 9: 18, 5: 10, 7: 14}

   do / progn
       do and progn are used to evaluate each of their arguments and return the last  one.  Return  values  from
       every  other than the last argument are discarded.  It can be used in lambda or list-comp to perform more
       complex logic as shown in one of the following examples.

       Some example usage:

          => (if true
          ...  (do (print "Side effects rock!")
          ...      (print "Yeah, really!")))
          Side effects rock!
          Yeah, really!

          ;; assuming that (side-effect) is a function that we want to call for each
          ;; and every value in the list, but whose return value we do not care about
          => (list-comp (do (side-effect x)
          ...               (if (< x 5) (* 2 x)
          ...                   (* 4 x)))
          ...           (x (range 10)))
          [0, 2, 4, 6, 8, 20, 24, 28, 32, 36]

       do can accept any number of arguments, from 1 to n.

   def / setv
       def and setv are used to bind a value, object, or function to a symbol.  For example:

          => (def names ["Alice" "Bob" "Charlie"])
          => (print names)
          [u'Alice', u'Bob', u'Charlie']

          => (setv counter (fn [collection item] (.count collection item)))
          => (counter [1 2 3 4 5 2 3] 2)
          2

   defclass
       New classes are declared with defclass. It can  takes  two  optional  parameters:  a  vector  defining  a
       possible super classes and another vector containing attributes of the new class as two item vectors.

          (defclass class-name [super-class-1 super-class-2]
            [[attribute value]])

       Both values and functions can be bound on the new class as shown by the example below:

          => (defclass Cat []
          ...  [[age None]
          ...   [colour "white"]
          ...   [speak (fn [self] (print "Meow"))]])

          => (def spot (Cat))
          => (setv spot.colour "Black")
          'Black'
          => (.speak spot)
          Meow

   defn / defun
       defn  and defun macros are used to define functions. They take three parameters: the name of the function
       to define, a vector of parameters, and the body of the function:

          (defn name [params] body)

       Parameters may have the following keywords in front of them:

       &optional
              Parameter is optional. The parameter can be given as a two item list, where the first  element  is
              parameter  name  and  the second is the default value. The parameter can be also given as a single
              item, in which case the default value is None.

                 => (defn total-value [value &optional [value-added-tax 10]]
                 ...  (+ (/ (* value value-added-tax) 100) value))

                 => (total-value 100)
                 110.0

                 => (total-value 100 1)
                 101.0

       &key

       &kwargs
              Parameter will contain 0 or more keyword arguments.

              The following code examples defines a function that will print all  keyword  arguments  and  their
              values.

                 => (defn print-parameters [&kwargs kwargs]
                 ...    (for [(, k v) (.items kwargs)] (print k v)))

                 => (apply print-parameters [] {"parameter-1" 1 "parameter-2" 2})
                 parameter-2 2
                 parameter-1 1

       &rest  Parameter  will  contain  0  or  more  positional  arguments. No other positional arguments may be
              specified after this one.

              The following code example defines a function that can be given 0 to n  numerical  parameters.  It
              then sums every odd number and subtracts every even number.

                 => (defn zig-zag-sum [&rest numbers]
                      (let [[odd-numbers (list-comp x [x numbers] (odd? x))]
                            [even-numbers (list-comp x [x numbers] (even? x))]]
                        (- (sum odd-numbers) (sum even-numbers))))

                 => (zig-zag-sum)
                 0
                 => (zig-zag-sum 3 9 4)
                 8
                 => (zig-zag-sum 1 2 3 4 5 6)
                 -3

   defn-alias / defun-alias
       New in version 0.10.0.

       The defn-alias and defun-alias macros are much like defn, with the distinction that instead of defining a
       function with a single name, these can also define aliases. Other than  taking  a  list  of  symbols  for
       function names as the first parameter, defn-alias and defun-alias are no different from defn and defun.

          => (defn-alias [main-name alias] []
          ...  (print "Hello!"))
          => (main-name)
          "Hello!"
          => (alias)
          "Hello!"

   defmain
       New in version 0.10.1.

       The  defmain  macro  defines a main function that is immediately called with sys.argv as arguments if and
       only if this file is being executed as a script.  In other words, this:

          (defmain [&rest args]
            (do-something-with args))

       is the equivalent of:

          def main(*args):
              do_something_with(args)
              return 0

          if __name__ == "__main__":
              import sys
              retval = main(*sys.arg)

              if isinstance(retval, int):
                  sys.exit(retval)

       Note that as you can see above, if you return an integer from this function, this will  be  used  as  the
       exit  status  for  your  script.   (Python  defaults to exit status 0 otherwise, which means everything's
       okay!)

       (Since (sys.exit 0) is not run explicitly in the case of a non-integer return from defmain, it's  a  good
       idea to put (defmain) as the last piece of code in your file.)

   defmacro
       defmacro is used to define macros. The general format is (defmacro name [parameters] expr).

       The  following  example  defines a macro that can be used to swap order of elements in code, allowing the
       user to write code in infix notation, where operator is in between the operands.

          => (defmacro infix [code]
          ...  (quasiquote (
          ...    (unquote (get code 1))
          ...    (unquote (get code 0))
          ...    (unquote (get code 2)))))

          => (infix (1 + 1))
          2

   defmacro-alias
       defmacro-alias  is  used  to  define  macros  with  multiple  names  (aliases).  The  general  format  is
       (defmacro-alias  [names]  [parameters] expr). It creates multiple macros with the same parameter list and
       body, under the specified list of names.

       The following example defines two macros, both of which allow the user to write code in infix notation.

          => (defmacro-alias [infix infi] [code]
          ...  (quasiquote (
          ...    (unquote (get code 1))
          ...    (unquote (get code 0))
          ...    (unquote (get code 2)))))

          => (infix (1 + 1))
          2
          => (infi (1 + 1))
          2

   defmacro/g!
       New in version 0.9.12.

       defmacro/g! is a special version of defmacro that is used to automatically generate gensym for any symbol
       that starts with g!.

       For example, g!a would become (gensym "a").

       SEE ALSO:
          Section using-gensym

   defreader
       New in version 0.9.12.

       defreader defines a reader macro, enabling you to restructure or modify syntax.

          => (defreader ^ [expr] (print expr))
          => #^(1 2 3 4)
          (1 2 3 4)
          => #^"Hello"
          "Hello"

       SEE ALSO:
          Section Reader Macros

   del
       New in version 0.9.12.

       del removes an object from the current namespace.

          => (setv foo 42)
          => (del foo)
          => foo
          Traceback (most recent call last):
            File "<console>", line 1, in <module>
          NameError: name 'foo' is not defined

       del can also remove objects from mappings, lists, and more.

          => (setv test (list (range 10)))
          => test
          [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
          => (del (slice test 2 4)) ;; remove items from 2 to 4 excluded
          => test
          [0, 1, 4, 5, 6, 7, 8, 9]
          => (setv dic {"foo" "bar"})
          => dic
          {"foo": "bar"}
          => (del (get dic "foo"))
          => dic
          {}

   doto
       New in version 0.10.1.

       doto is used to simplify a sequence of method calls to an object.

          => (doto [] (.append 1) (.append 2) .reverse)
          [2 1]

          => (setv collection [])
          => (.append collection 1)
          => (.append collection 2)
          => (.reverse collection)
          => collection
          [2 1]

   eval
       eval evaluates a quoted expression and returns the value.

          => (eval '(print "Hello World"))
          "Hello World"

   eval-and-compile
   eval-when-compile
   first / car
       first and car are macros for accessing the first element of a collection:

          => (first (range 10))
          0

   for
       for  is  used  to  call  a  function  for each element in a list or vector.  The results of each call are
       discarded and the for expression returns None instead. The example code iterates over collection and  for
       each element in collection calls the side-effect function with element as its argument:

          ;; assuming that (side-effect) is a function that takes a single parameter
          (for [element collection] (side-effect element))

          ;; for can have an optional else block
          (for [element collection] (side-effect element)
               (else (side-effect-2)))

       The  optional else block is only executed if the for loop terminates normally. If the execution is halted
       with break, the else block does not execute.

          => (for [element [1 2 3]] (if (< element 3)
          ...                             (print element)
          ...                             (break))
          ...    (else (print "loop finished")))
          1
          2

          => (for [element [1 2 3]] (if (< element 4)
          ...                             (print element)
          ...                             (break))
          ...    (else (print "loop finished")))
          1
          2
          3
          loop finished

   genexpr
       genexpr is used to create generator expressions. It takes two or three parameters. The first parameter is
       the  expression  controlling  the return value, while the second is used to select items from a list. The
       third and optional parameter can be used to filter out  some  of  the  items  in  the  list  based  on  a
       conditional  expression.  genexpr  is  similar to list-comp, except it returns an iterable that evaluates
       values one by one instead of evaluating them immediately.

          => (def collection (range 10))
          => (def filtered (genexpr x [x collection] (even? x)))
          => (list filtered)
          [0, 2, 4, 6, 8]

   gensym
       New in version 0.9.12.

       gensym is used to generate a unique symbol that allows macros to be written without  accidental  variable
       name clashes.

          => (gensym)
          u':G_1235'

          => (gensym "x")
          u':x_1236'

       SEE ALSO:
          Section using-gensym

   get
       get  is  used  to  access  single  elements in lists and dictionaries. get takes two parameters: the data
       structure and the index or key of the item.  It  will  then  return  the  corresponding  value  from  the
       dictionary or the list. Example usage:

          => (let [[animals {"dog" "bark" "cat" "meow"}]
          ...      [numbers ["zero" "one" "two" "three"]]]
          ...  (print (get animals "dog"))
          ...  (print (get numbers 2)))
          bark
          two

       NOTE:
          get raises a KeyError if a dictionary is queried for a non-existing key.

       NOTE:
          get raises an IndexError if a list or a tuple is queried for an index that is out of bounds.

   global
       global  can  be used to mark a symbol as global. This allows the programmer to assign a value to a global
       symbol. Reading a global symbol does not require the global keyword -- only assigning it does.

       The following example shows how the global symbol a is assigned a value in a function  and  is  later  on
       printed  in  another  function.  Without  the  global  keyword,  the  second function would have thrown a
       NameError.

          (defn set-a [value]
            (global a)
            (setv a value))

          (defn print-a []
            (print a))

          (set-a 5)
          (print-a)

   if / if-not
       New in version 0.10.0: if-not

       if is used to conditionally select code to be executed. It has to contain a condition block and the block
       to be executed if the condition block evaluates to True. Optionally, it may contain a final block that is
       executed in case the evaluation of the condition is False.

       if-not is similar, but the second block will be executed when the condition fails  while  the  third  and
       final block is executed when the test succeeds -- the opposite order of if.

       Example usage:

          (if (money-left? account)
            (print "let's go shopping")
            (print "let's go and work"))

          (if-not (money-left? account)
            (print "let's go and work")
            (print "let's go shopping"))

       Python  truthiness  is  respected. None, False, zero of any numeric type, an empty sequence, and an empty
       dictionary are considered False; everything else is considered True.

   lisp-if / lif and lisp-if-not / lif-not
       New in version 0.10.0.

       New in version 0.10.2: lisp-if-not / lif-not

       For those that prefer a more Lispy if clause, we have lisp-if, or lif. This only considers None / nil  to
       be  false!  All  other "false-ish" Python values are considered true. Conversely, we have lisp-if-not and
       lif-not in parallel to if and if-not which reverses the comparison.

          => (lisp-if True "true" "false")
          "true"
          => (lisp-if False "true" "false")
          "true"
          => (lisp-if 0 "true" "false")
          "true"
          => (lisp-if nil "true" "false")
          "false"
          => (lisp-if None "true" "false")
          "false"
          => (lisp-if-not nil "true" "false")
          "true"
          => (lisp-if-not None "true" "false")
          "true"
          => (lisp-if-not False "true" "false")
          "false"

          ; Equivalent but shorter
          => (lif True "true" "false")
          "true"
          => (lif nil "true" "false")
          "false"
          => (lif-not None "true" "false")
          "true"

   import
       import is used to import modules, like in Python. There are several ways that import can be used.

          ;; Imports each of these modules
          ;;
          ;; Python:
          ;; import sys
          ;; import os.path
          (import sys os.path)

          ;; Import from a module
          ;;
          ;; Python: from os.path import exists, isdir, isfile
          (import [os.path [exists isdir isfile]])

          ;; Import with an alias
          ;;
          ;; Python: import sys as systest
          (import [sys :as systest])

          ;; You can list as many imports as you like of different types.
          (import [tests.resources [kwtest function-with-a-dash]]
                  [os.path [exists isdir isfile]]
                  [sys :as systest])

          ;; Import all module functions into current namespace
          (import [sys [*]])

   lambda / fn
       lambda and fn can be used to define an anonymous function. The parameters are similar to defn: the  first
       parameter  is  vector  of  parameters  and  the  rest  is  the body of the function. lambda returns a new
       function. In the following example, an anonymous function is defined and passed to another  function  for
       filtering output.

          => (def people [{:name "Alice" :age 20}
          ...             {:name "Bob" :age 25}
          ...             {:name "Charlie" :age 50}
          ...             {:name "Dave" :age 5}])

          => (defn display-people [people filter]
          ...  (for [person people] (if (filter person) (print (:name person)))))

          => (display-people people (fn [person] (< (:age person) 25)))
          Alice
          Dave

       Just  as  in  normal  function  definitions, if the first element of the body is a string, it serves as a
       docstring. This is useful for giving class methods docstrings.

          => (setv times-three
          ...   (fn [x]
          ...    "Multiplies input by three and returns the result."
          ...    (* x 3)))

       This can be confirmed via Python's built-in help function:

          => (help times-three)
          Help on function times_three:

          times_three(x)
          Multiplies input by three and returns result
          (END)

   last
       New in version 0.10.2.

       last can be used for accessing the last element of a collection:

          => (last [2 4 6])
          6

   let
       let is used to create lexically scoped variables. They are created at the beginning of the let  form  and
       cease to exist after the form. The following example showcases this behaviour:

          => (let [[x 5]] (print x)
          ...  (let [[x 6]] (print x))
          ...  (print x))
          5
          6
          5

       The  let  macro  takes  two  parameters:  a  vector  defining variables and the body which gets executed.
       variables is a vector where each element is either a single variable or  a  vector  defining  a  variable
       value pair. In the case of a single variable, it is assigned value None; otherwise, the supplied value is
       used.

          => (let [x [y 5]] (print x y))
          None 5

   list-comp
       list-comp performs list comprehensions. It takes two or three parameters.  The  first  parameter  is  the
       expression  controlling the return value, while the second is used to select items from a list. The third
       and optional parameter can be used to filter out some of the items in the list  based  on  a  conditional
       expression. Some examples:

          => (def collection (range 10))
          => (list-comp x [x collection])
          [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

          => (list-comp (* x 2) [x collection])
          [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

          => (list-comp (* x 2) [x collection] (< x 5))
          [0, 2, 4, 6, 8]

   not
       not  is  used  in logical expressions. It takes a single parameter and returns a reversed truth value. If
       True is given as a parameter, False will be returned, and vice-versa. Example usage:

          => (not True)
          False

          => (not False)
          True

          => (not None)
          True

   or
       or is used in logical expressions. It takes at least two parameters. It will return the  first  non-false
       parameter. If no such value exists, the last parameter will be returned.

          => (or True False)
          True

          => (and False False)
          False

          => (and False 1 True False)
          1

       NOTE:
          or short-circuits and stops evaluating parameters as soon as the first true value is encountered.

          => (or True (print "hello"))
          True

   print
       print is used to output on screen. Example usage:

          (print "Hello world!")

       NOTE:
          print always returns None.

   quasiquote
       quasiquote  allows  you  to quote a form, but also selectively evaluate expressions. Expressions inside a
       quasiquote can be selectively evaluated using unquote (~). The evaluated form can also be  spliced  using
       unquote-splice (~@). Quasiquote can be also written using the backquote (`) symbol.

          ;; let `qux' be a variable with value (bar baz)
          `(foo ~qux)
          ; equivalent to '(foo (bar baz))
          `(foo ~@qux)
          ; equivalent to '(foo bar baz)

   quote
       quote  returns  the form passed to it without evaluating it. quote can alternatively be written using the
       apostrophe (') symbol.

          => (setv x '(print "Hello World"))
          ; variable x is set to expression & not evaluated
          => x
          (u'print' u'Hello World')
          => (eval x)
          Hello World

   require
       require is used to import macros from a given module. It takes at  least  one  parameter  specifying  the
       module which macros should be imported. Multiple modules can be imported with a single require.

       The following example will import macros from module-1 and module-2:

          (require module-1 module-2)

   rest / cdr
       rest and cdr return the collection passed as an argument without the first element:

          => (rest (range 10))
          [1, 2, 3, 4, 5, 6, 7, 8, 9]

   set-comp
       set-comp  is  used  to  create  sets.  It  takes  two  or  three  parameters.  The first parameter is for
       controlling the return value, while the second is used to select items from a  sequence.  The  third  and
       optional  parameter  can  be  used to filter out some of the items in the sequence based on a conditional
       expression.

          => (setv data [1 2 3 4 5 2 3 4 5 3 4 5])
          => (set-comp x [x data] (odd? x))
          {1, 3, 5}

   slice
       slice can be used to take a subset of a list and create a new list from it.  The form takes at least  one
       parameter  specifying  the  list  to slice. Two optional parameters can be used to give the start and end
       position of the subset. If they are not supplied, the default value of None will  be  used  instead.  The
       third optional parameter is used to control step between the elements.

       slice  follows  the  same rules as its Python counterpart. Negative indices are counted starting from the
       end of the list. Some example usage:

          => (def collection (range 10))

          => (slice collection)
          [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

          => (slice collection 5)
          [5, 6, 7, 8, 9]

          => (slice collection 2 8)
          [2, 3, 4, 5, 6, 7]

          => (slice collection 2 8 2)
          [2, 4, 6]

          => (slice collection -4 -2)
          [6, 7]

   throw / raise
       The throw or raise forms can be used to raise an Exception at runtime. Example usage:

          (throw)
          ; re-rase the last exception

          (throw IOError)
          ; Throw an IOError

          (throw (IOError "foobar"))
          ; Throw an IOError("foobar")

       throw can accept a single argument (an Exception class or instance) or no arguments to re-raise the  last
       Exception.

   try
       The try form is used to start a try / catch block. The form is used as follows:

          (try
              (error-prone-function)
              (catch [e ZeroDivisionError] (print "Division by zero"))
              (else (print "no errors"))
              (finally (print "all done")))

       try  must  contain  at  least one catch block, and may optionally include an else or finally block. If an
       error is raised with a matching catch block during the  execution  of  error-prone-function,  that  catch
       block  will  be  executed. If no errors are raised, the else block is executed. The finally block will be
       executed last regardless of whether or not an error was raised.

   unless
       The unless macro is a shorthand for writing an if statement that  checks  if  the  given  conditional  is
       False. The following shows the expansion of this macro.

          (unless conditional statement)

          (if conditional
            None
            (do statement))

   unquote
       Within  a  quasiquoted  form,  unquote forces evaluation of a symbol. unquote is aliased to the tilde (~)
       symbol.

          (def name "Cuddles")
          (quasiquote (= name (unquote name)))
          ;=> (u'=' u'name' u'Cuddles')

          `(= name ~name)
          ;=> (u'=' u'name' u'Cuddles')

   unquote-splice
       unquote-splice forces the  evaluation  of  a  symbol  within  a  quasiquoted  form,  much  like  unquote.
       unquote-splice  can  only  be  used  when  the  symbol  being  unquoted contains an iterable value, as it
       "splices" that iterable into the quasiquoted form. unquote-splice is aliased to the ~@ symbol.

          (def nums [1 2 3 4])
          (quasiquote (+ (unquote-splice nums)))
          ;=> (u'+' 1L 2L 3L 4L)

          `(+ ~@nums)
          ;=> (u'+' 1L 2L 3L 4L)

   when
       when is similar to unless, except it tests when the given conditional is True. It is not possible to have
       an else block in a when macro. The following shows the expansion of the macro.

          (when conditional statement)

          (if conditional (do statement))

   while
       while  is  used  to execute one or more blocks as long as a condition is met.  The following example will
       output "Hello world!" to the screen indefinitely:

          (while True (print "Hello world!"))

   with
       with is used to wrap the execution of a block within a context manager. The context manager can then  set
       up  the  local  system and tear it down in a controlled manner. The archetypical example of using with is
       when processing files.  with can bind context to an argument or ignore it completely, as shown below:

          (with [[arg (expr)]] block)

          (with [[(expr)]] block)

          (with [[arg (expr)] [(expr)]] block)

       The following example will open the NEWS  file  and  print  its  content  to  the  screen.  The  file  is
       automatically closed after it has been processed.

          (with [[f (open "NEWS")]] (print (.read f)))

   with-decorator
       with-decorator  is  used  to  wrap a function with another. The function performing the decoration should
       accept a single value: the function being decorated, and return a new function.  with-decorator  takes  a
       minimum of two parameters: the function performing decoration and the function being decorated. More than
       one decorator function can be applied; they will be applied in order from outermost to innermost, ie. the
       first  decorator  will  be the outermost one, and so on. Decorators with arguments are called just like a
       function call.

          (with-decorator decorator-fun
             (defn some-function [] ...)

          (with-decorator decorator1 decorator2 ...
             (defn some-function [] ...)

          (with-decorator (decorator arg) ..
             (defn some-function [] ...)

       In the following example, inc-decorator is used to decorate the function addition with  a  function  that
       takes  two  parameters  and  calls the decorated function with values that are incremented by 1. When the
       decorated addition is called with values 1 and 1, the end result will be 4 (1+1 + 1+1).

          => (defn inc-decorator [func]
          ...  (fn [value-1 value-2] (func (+ value-1 1) (+ value-2 1))))
          => (defn inc2-decorator [func]
          ...  (fn [value-1 value-2] (func (+ value-1 2) (+ value-2 2))))

          => (with-decorator inc-decorator (defn addition [a b] (+ a b)))
          => (addition 1 1)
          4
          => (with-decorator inc2-decorator inc-decorator
          ...  (defn addition [a b] (+ a b)))
          => (addition 1 1)
          8

   with-gensyms
       New in version 0.9.12.

       with-gensym is used to generate a set of gensym for use in a macro.  The following code:

          (with-gensyms [a b c]
            ...)

       expands to:

          (let [[a (gensym)
                [b (gensym)
                [c (gensym)]]
            ...)

       SEE ALSO:
          Section using-gensym

   yield
       yield is used to create a generator object that returns one or more values.  The  generator  is  iterable
       and therefore can be used in loops, list comprehensions and other similar constructs.

       The  function  random-numbers  shows  how  generators  can  be  used  to generate infinite series without
       consuming infinite amount of memory.

          => (defn multiply [bases coefficients]
          ...  (for [[(, base coefficient) (zip bases coefficients)]]
          ...   (yield (* base coefficient))))

          => (multiply (range 5) (range 5))
          <generator object multiply at 0x978d8ec>

          => (list-comp value [value (multiply (range 10) (range 10))])
          [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

          => (import random)
          => (defn random-numbers [low high]
          ...  (while True (yield (.randint random low high))))
          => (list-comp x [x (take 15 (random-numbers 1 50))])])
          [7, 41, 6, 22, 32, 17, 5, 38, 18, 38, 17, 14, 23, 23, 19]

   yield-from
       New in version 0.9.13.

       PYTHON 3.3 AND UP ONLY!

       yield-from is used to call a subgenerator.  This is useful if you want  your  coroutine  to  be  able  to
       delegate its processes to another coroutine, say, if using something fancy like asyncio.

   Hy Core
   Core Functions
   butlast
       Usage: (butlast coll)

       Returns an iterator of all but the last item in coll.

          => (list (butlast (range 10)))
          [0, 1, 2, 3, 4, 5, 6, 7, 8]

          => (list (butlast [1]))
          []

          => (list (butlast []))
          []

          => (import itertools)
          => (list (take 5 (butlast (itertools.count 10))))
          [10, 11, 12, 13, 14]

   coll?
       New in version 0.10.0.

       Usage: (coll? x)

       Returns True if x is iterable and not a string.

          => (coll? [1 2 3 4])
          True

          => (coll? {"a" 1 "b" 2})
          True

          => (coll? "abc")
          False

   cons
       New in version 0.10.0.

       Usage: (cons a b)

       Returns a fresh cons cell with car a and cdr b.

          => (setv a (cons 'hd 'tl))

          => (= 'hd (car a))
          True

          => (= 'tl (cdr a))
          True

   cons?
       New in version 0.10.0.

       Usage: (cons? foo)

       Checks whether foo is a cons cell.

          => (setv a (cons 'hd 'tl))

          => (cons? a)
          True

          => (cons? nil)
          False

          => (cons? [1 2 3])
          False

   dec
       Usage: (dec x)

       Returns one less than x. Equivalent to (- x 1). Raises TypeError if (not (numeric? x)).

          => (dec 3)
          2

          => (dec 0)
          -1

          => (dec 12.3)
          11.3

   disassemble
       New in version 0.10.0.

       Usage: (disassemble tree &optional [codegen false])

       Dump  the Python AST for given Hy tree to standard output. If codegen is True, the function prints Python
       code instead.

          => (disassemble '(print "Hello World!"))
          Module(
           body=[
               Expr(value=Call(func=Name(id='print'), args=[Str(s='Hello World!')], keywords=[], starargs=None, kwargs=None))])

          => (disassemble '(print "Hello World!") true)
          print('Hello World!')

   empty?
       Usage: (empty? coll)

       Returns True if coll is empty. Equivalent to (= 0 (len coll)).

          => (empty? [])
          True

          => (empty? "")
          True

          => (empty? (, 1 2))
          False

   every?
       New in version 0.10.0.

       Usage: (every? pred coll)

       Returns True if (pred x) is logical true for every x in coll, otherwise False. Return  True  if  coll  is
       empty.

          => (every? even? [2 4 6])
          True

          => (every? even? [1 3 5])
          False

          => (every? even? [2 4 5])
          False

          => (every? even? [])
          True

   float?
       Usage: (float? x)

       Returns True if x is a float.

          => (float? 3.2)
          True

          => (float? -2)
          False

   even?
       Usage: (even? x)

       Returns True if x is even. Raises TypeError if (not (numeric? x)).

          => (even? 2)
          True

          => (even? 13)
          False

          => (even? 0)
          True

   identity
       Usage: (identity x)

       Returns the argument supplied to the function.

          => (identity 4)
          4

          => (list (map identity [1 2 3 4]))
          [1 2 3 4]

   inc
       Usage: (inc x)

       Returns one more than x. Equivalent to (+ x 1). Raises TypeError if (not (numeric? x)).

          => (inc 3)
          4

          => (inc 0)
          1

          => (inc 12.3)
          13.3

   instance?
       Usage: (instance? class x)

       Returns True if x is an instance of class.

          => (instance? float 1.0)
          True

          => (instance? int 7)
          True

          => (instance? str (str "foo"))
          True

          => (defclass TestClass [object])
          => (setv inst (TestClass))
          => (instance? TestClass inst)
          True

   integer?
       Usage: (integer? x)

       Returns True if x is an integer. For Python 2, this is either int or long. For Python 3, this is int.

          => (integer? 3)
          True

          => (integer? -2.4)
          False

   interleave
       New in version 0.10.1.

       Usage: (interleave seq1 seq2 ...)

       Returns an iterable of the first item in each of the sequences, then the second, etc.

          => (list (interleave (range 5) (range 100 105)))
          [0, 100, 1, 101, 2, 102, 3, 103, 4, 104]

          => (list (interleave (range 1000000) "abc"))
          [0, 'a', 1, 'b', 2, 'c']

   interpose
       New in version 0.10.1.

       Usage: (interpose item seq)

       Returns an iterable of the elements of the sequence separated by the item.

          => (list (interpose "!" "abcd"))
          ['a', '!', 'b', '!', 'c', '!', 'd']

          => (list (interpose -1 (range 5)))
          [0, -1, 1, -1, 2, -1, 3, -1, 4]

   iterable?
       Usage: (iterable? x)

       Returns  True  if x is iterable. Iterable objects return a new iterator when (iter x) is called. Contrast
       with iterator?.

          => ;; works for strings
          => (iterable? (str "abcde"))
          True

          => ;; works for lists
          => (iterable? [1 2 3 4 5])
          True

          => ;; works for tuples
          => (iterable? (, 1 2 3))
          True

          => ;; works for dicts
          => (iterable? {:a 1 :b 2 :c 3})
          True

          => ;; works for iterators/generators
          => (iterable? (repeat 3))
          True

   iterator?
       Usage: (iterator? x)

       Returns True if x is an iterator. Iterators are objects that return themselves as an iterator when  (iter
       x) is called. Contrast with iterable?.

          => ;; doesn't work for a list
          => (iterator? [1 2 3 4 5])
          False

          => ;; but we can get an iter from the list
          => (iterator? (iter [1 2 3 4 5]))
          True

          => ;; doesn't work for dict
          => (iterator? {:a 1 :b 2 :c 3})
          False

          => ;; create an iterator from the dict
          => (iterator? (iter {:a 1 :b 2 :c 3}))
          True

   list*
       Usage: (list* head &rest tail)

       Generates  a  chain  of  nested cons cells (a dotted list) containing the arguments. If the argument list
       only has one element, return it.

          => (list* 1 2 3 4)
          (1 2 3 . 4)

          => (list* 1 2 3 [4])
          [1, 2, 3, 4]

          => (list* 1)
          1

          => (cons? (list* 1 2 3 4))
          True

   macroexpand
       New in version 0.10.0.

       Usage: (macroexpand form)

       Returns the full macro expansion of form.

          => (macroexpand '(-> (a b) (x y)))
          (u'x' (u'a' u'b') u'y')

          => (macroexpand '(-> (a b) (-> (c d) (e f))))
          (u'e' (u'c' (u'a' u'b') u'd') u'f')

   macroexpand-1
       New in version 0.10.0.

       Usage: (macroexpand-1 form)

       Returns the single step macro expansion of form.

          => (macroexpand-1 '(-> (a b) (-> (c d) (e f))))
          (u'_>' (u'a' u'b') (u'c' u'd') (u'e' u'f'))

   merge-with
       New in version 0.10.1.

       Usage: (merge-with f &rest maps)

       Returns a map that consist of the rest of the maps joined onto first.  If a key occurs in more  than  one
       map,  the  mapping(s)  from the latter (left-to-right) will be combined with the mapping in the result by
       calling (f val-in-result val-in-latter).

          => (merge-with (fn [x y] (+ x y)) {"a" 10 "b" 20} {"a" 1 "c" 30})
          {u'a': 11L, u'c': 30L, u'b': 20L}

   neg?
       Usage: (neg? x)

       Returns True if x is less than zero. Raises TypeError if (not (numeric? x)).

          => (neg? -2)
          True

          => (neg? 3)
          False

          => (neg? 0)
          False

   nil?
       Usage: (nil? x)

       Returns True if x is nil / None.

          => (nil? nil)
          True

          => (nil? None)
          True

          => (nil? 0)
          False

          => (setf x nil)
          => (nil? x)
          True

          => ;; list.append always returns None
          => (nil? (.append [1 2 3] 4))
          True

   none?
       Usage: (none? x)

       Returns True if x is None.

          => (none? None)
          True

          => (none? 0)
          False

          => (setf x None)
          => (none? x)
          True

          => ;; list.append always returns None
          => (none? (.append [1 2 3] 4))
          True

   nth
       Usage: (nth coll n &optional [default nil])

       Returns the n-th item in a collection, counting from 0. Return the default value, nil, if out  of  bounds
       (unless specified otherwise).  Raises ValueError if n is negative.

          => (nth [1 2 4 7] 1)
          2

          => (nth [1 2 4 7] 3)
          7

          => (nil? (nth [1 2 4 7] 5))
          True

          => (nth [1 2 4 7] 5 "default")
          'default'

          => (nth (take 3 (drop 2 [1 2 3 4 5 6])) 2))
          5

          => (nth [1 2 4 7] -1)
          Traceback (most recent call last):
            ...
          ValueError: Indices for islice() must be None or an integer: 0 <= x <= sys.maxsize.

   numeric?
       Usage: (numeric? x)

       Returns True if x is a numeric, as defined in Python's numbers.Number class.

          => (numeric? -2)
          True

          => (numeric? 3.2)
          True

          => (numeric? "foo")
          False

   odd?
       Usage: (odd? x)

       Returns True if x is odd. Raises TypeError if (not (numeric? x)).

          => (odd? 13)
          True

          => (odd? 2)
          False

          => (odd? 0)
          False

   pos?
       Usage: (pos? x)

       Returns True if x is greater than zero. Raises TypeError if (not (numeric? x)).

          => (pos? 3)
          True

          => (pos? -2)
          False

          => (pos? 0)
          False

   second
       Usage: (second coll)

       Returns the second member of coll. Equivalent to (get coll 1).

          => (second [0 1 2])
          1

   some
       New in version 0.10.0.

       Usage: (some pred coll)

       Returns  the  first logically-true value of (pred x) for any x in coll, otherwise nil. Return nil if coll
       is empty.

          => (some even? [2 4 6])
          True

          => (nil? (some even? [1 3 5]))
          True

          => (nil? (some identity [0 "" []]))
          True

          => (some identity [0 "non-empty-string" []])
          'non-empty-string'

          => (nil? (some even? []))
          True

   string?
       Usage: (string? x)

       Returns True if x is a string.

          => (string? "foo")
          True

          => (string? -2)
          False

   symbol?
       Usage: (symbol? x)

       Returns True if x is a symbol.

          => (symbol? 'foo)
          True

          => (symbol? '[a b c])
          False

   zero?
       Usage: (zero? x)

       Returns True if x is zero.

          => (zero? 3)
          False

          => (zero? -2)
          False

          => (zero? 0)
          True

   Sequence Functions
       Sequence functions can either create or operate on a potentially infinite sequence without requiring  the
       sequence be fully realized in a list or similar container. They do this by returning a Python iterator.

       We  can  use  the canonical infinite Fibonacci number generator as an example of how to use some of these
       functions.

          (defn fib []
            (setv a 0)
            (setv b 1)
            (while true
              (yield a)
              (setv (, a b) (, b (+ a b)))))

       Note the (while true ...) loop. If we run this in the REPL,

          => (fib)
          <generator object fib at 0x101e642d0>

       Calling the function only returns an iterator, but does no work until we  consume  it.  Trying  something
       like  this is not recommend as the infinite loop will run until it consumes all available RAM, or in this
       case until I killed it.

          => (list (fib))
          [1]    91474 killed     hy

       To get the first 10 Fibonacci numbers, use take. Note that take also returns a generator, so I  create  a
       list from it.

          => (list (take 10 (fib)))
          [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

       To get the Fibonacci number at index 9, (starting from 0):

          => (nth (fib) 9)
          34

   cycle
       Usage: (cycle coll)

       Returns an infinite iterator of the members of coll.

          => (list (take 7 (cycle [1 2 3])))
          [1, 2, 3, 1, 2, 3, 1]

          => (list (take 2 (cycle [1 2 3])))
          [1, 2]

   distinct
       Usage: (distinct coll)

       Returns an iterator containing only the unique members in coll.

          => (list (distinct [ 1 2 3 4 3 5 2 ]))
          [1, 2, 3, 4, 5]

          => (list (distinct []))
          []

          => (list (distinct (iter [ 1 2 3 4 3 5 2 ])))
          [1, 2, 3, 4, 5]

   drop
       Usage: (drop n coll)

       Returns an iterator, skipping the first n members of coll.  Raises ValueError if n is negative.

          => (list (drop 2 [1 2 3 4 5]))
          [3, 4, 5]

          => (list (drop 4 [1 2 3 4 5]))
          [5]

          => (list (drop 0 [1 2 3 4 5]))
          [1, 2, 3, 4, 5]

          => (list (drop 6 [1 2 3 4 5]))
          []

   drop-last
       Usage: (drop-last n coll)

       Returns an iterator of all but the last n items in coll. Raises ValueError if n is negative.

          => (list (drop-last 5 (range 10 20)))
          [10, 11, 12, 13, 14]

          => (list (drop-last 0 (range 5)))
          [0, 1, 2, 3, 4]

          => (list (drop-last 100 (range 100)))
          []

          => (import itertools)
          => (list (take 5 (drop-last 100 (itertools.count 10))))
          [10, 11, 12, 13, 14]

   drop-while
       Usage: (drop-while pred coll)

       Returns an iterator, skipping members of coll until pred is False.

          => (list (drop-while even? [2 4 7 8 9]))
          [7, 8, 9]

          => (list (drop-while numeric? [1 2 3 None "a"])))
          [None, u'a']

          => (list (drop-while pos? [2 4 7 8 9]))
          []

   filter
       Usage: (filter pred coll)

       Returns an iterator for all items in coll that pass the predicate pred.

       See also remove.

          => (list (filter pos? [1 2 3 -4 5 -7]))
          [1, 2, 3, 5]

          => (list (filter even? [1 2 3 -4 5 -7]))
          [2, -4]

   flatten
       New in version 0.9.12.

       Usage: (flatten coll)

       Returns a single list of all the items in coll, by flattening all contained lists and/or tuples.

          => (flatten [1 2 [3 4] 5])
          [1, 2, 3, 4, 5]

          => (flatten ["foo" (, 1 2) [1 [2 3] 4] "bar"])
          ['foo', 1, 2, 1, 2, 3, 4, 'bar']

   iterate
       Usage: (iterate fn x)

       Returns an iterator of x, fn(x), fn(fn(x)), etc.

          => (list (take 5 (iterate inc 5)))
          [5, 6, 7, 8, 9]

          => (list (take 5 (iterate (fn [x] (* x x)) 5)))
          [5, 25, 625, 390625, 152587890625]

   read
       Usage: (read &optional [from-file eof])

       Reads  the next Hy expression from from-file (defaulting to sys.stdin), and can take a single byte as EOF
       (defaults to an empty string). Raises EOFError if from-file ends before  a  complete  expression  can  be
       parsed.

          => (read)
          (+ 2 2)
          ('+' 2 2)
          => (eval (read))
          (+ 2 2)
          4

          => (import io)
          => (def buffer (io.StringIO "(+ 2 2)\n(- 2 1)"))
          => (eval (apply read [] {"from_file" buffer}))
          4
          => (eval (apply read [] {"from_file" buffer}))
          1

          => ; assuming "example.hy" contains:
          => ;   (print "hello")
          => ;   (print "hyfriends!")
          => (with [[f (open "example.hy")]]
          ...   (try
          ...     (while true
          ...            (let [[exp (read f)]]
          ...              (do
          ...                (print "OHY" exp)
          ...                (eval exp))))
          ...     (catch [e EOFError]
          ...            (print "EOF!"))))
          OHY ('print' 'hello')
          hello
          OHY ('print' 'hyfriends!')
          hyfriends!
          EOF!

   remove
       Usage: (remove pred coll)

       Returns an iterator from coll with elements that pass the predicate, pred, removed.

       See also filter.

          => (list (remove odd? [1 2 3 4 5 6 7]))
          [2, 4, 6]

          => (list (remove pos? [1 2 3 4 5 6 7]))
          []

          => (list (remove neg? [1 2 3 4 5 6 7]))
          [1, 2, 3, 4, 5, 6, 7]

   repeat
       Usage: (repeat x)

       Returns an iterator (infinite) of x.

          => (list (take 6 (repeat "s")))
          [u's', u's', u's', u's', u's', u's']

   repeatedly
       Usage: (repeatedly fn)

       Returns an iterator by calling fn repeatedly.

          => (import [random [randint]])

          => (list (take 5 (repeatedly (fn [] (randint 0 10)))))
          [6, 2, 0, 6, 7]

   take
       Usage: (take n coll)

       Returns an iterator containing the first n members of coll.  Raises ValueError if n is negative.

          => (list (take 3 [1 2 3 4 5]))
          [1, 2, 3]

          => (list (take 4 (repeat "s")))
          [u's', u's', u's', u's']

          => (list (take 0 (repeat "s")))
          []

   take-nth
       Usage: (take-nth n coll)

       Returns an iterator containing every n-th member of coll.

          => (list (take-nth 2 [1 2 3 4 5 6 7]))
          [1, 3, 5, 7]

          => (list (take-nth 3 [1 2 3 4 5 6 7]))
          [1, 4, 7]

          => (list (take-nth 4 [1 2 3 4 5 6 7]))
          [1, 5]

          => (list (take-nth 10 [1 2 3 4 5 6 7]))
          [1]

   take-while
       Usage: (take-while pred coll)

       Returns an iterator from coll as long as pred returns True.

          => (list (take-while pos? [ 1 2 3 -4 5]))
          [1, 2, 3]

          => (list (take-while neg? [ -4 -3 1 2 5]))
          [-4, -3]

          => (list (take-while neg? [ 1 2 3 -4 5]))
          []

   zipwith
       New in version 0.9.13.

       Usage: (zipwith fn coll ...)

       Equivalent  to  zip, but uses a multi-argument function instead of creating a tuple. If zipwith is called
       with N collections, then fn must accept N arguments.

          => (import operator)
          => (list (zipwith operator.add [1 2 3] [4 5 6]))
          [5, 7, 9]

   Reader Macros
       Reader macros gives Lisp the power to modify and  alter  syntax  on  the  fly.   You  don't  want  Polish
       notation? A reader macro can easily do just that. Want Clojure's way of having a regex? Reader macros can
       also do this easily.

   Syntax
          => (defreader ^ [expr] (print expr))
          => #^(1 2 3 4)
          (1 2 3 4)
          => #^"Hello"
          "Hello"
          => #^1+2+3+4+3+2
          1+2+3+4+3+2

       Hy has no literal for tuples. Lets say you dislike (, ...) and want something else.  This  is  a  problem
       reader macros are able to solve in a neat way.

          => (defreader t [expr] `(, ~@expr))
          => #t(1 2 3)
          (1, 2, 3)

       You could even do it like Clojure and have a literal for regular expressions!

          => (import re)
          => (defreader r [expr] `(re.compile ~expr))
          => #r".*"
          <_sre.SRE_Pattern object at 0xcv7713ph15#>

   Implementation
       defreader  takes  a  single character as symbol name for the reader macro; anything longer will return an
       error. Implementation-wise, defreader expands into a lambda covered  with  a  decorator.  This  decorator
       saves the lambda in a dictionary with its module name and symbol.

          => (defreader ^ [expr] (print expr))
          ;=> (with_decorator (hy.macros.reader ^) (fn [expr] (print expr)))

       #  expands  into  (dispatch_reader_macro  ...)  where  the symbol and expression is passed to the correct
       function.

          => #^()
          ;=> (dispatch_reader_macro ^ ())
          => #^"Hello"
          "Hello"

       WARNING:
          Because of a limitation in Hy's lexer and parser, reader macros can't redefine defined syntax such  as
          ()[]{}. This will most likely be addressed in the future.

   Internal Hy Documentation
       NOTE:
          These  bits  are mostly useful for folks who hack on Hy itself, but can also be used for those delving
          deeper in macro programming.

   Hy Models
   Introduction to Hy Models
       Hy models are a very thin layer on top of regular Python objects, representing Hy source  code  as  data.
       Models only add source position information, and a handful of methods to support clean manipulation of Hy
       source code, for instance in macros. To achieve that goal, Hy models are mixins of a  base  Python  class
       and HyObject.

   HyObject
       hy.models.HyObject is the base class of Hy models. It only implements one method, replace, which replaces
       the source position of the current object with the one passed as argument. This allows us to  keep  track
       of  the  original position of expressions that get modified by macros, be that in the compiler or in pure
       hy macros.

       HyObject is not intended to be used directly to instantiate Hy models, but only  as  a  mixin  for  other
       classes.

   Compound Models
       Parenthesized and bracketed lists are parsed as compound models by the Hy parser.

   HyList
       hy.models.list.HyList  is the base class of "iterable" Hy models. Its basic use is to represent bracketed
       [] lists, which, when used  as  a  top-level  expression,  translate  to  Python  list  literals  in  the
       compilation phase.

       Adding  a  HyList  to  another  iterable  object  reuses the class of the left-hand-side object, a useful
       behavior when you want to concatenate Hy objects in a macro, for instance.

   HyExpression
       hy.models.expression.HyExpression inherits HyList  for  parenthesized  ()  expressions.  The  compilation
       result of those expressions depends on the first element of the list: the compiler dispatches expressions
       between compiler special-forms, user-defined macros, and regular Python function calls.

   HyDict
       hy.models.dict.HyDict inherits HyList for curly-bracketed {} expressions, which compile down to a  Python
       dictionary literal.

       The decision of using a list instead of a dict as the base class for HyDict allows easier manipulation of
       dicts in macros, with the added benefit of allowing compound expressions as dict keys (as, for  instance,
       the HyExpression Python class isn't hashable).

   Atomic Models
       In  the  input stream, double-quoted strings, respecting the Python notation for strings, are parsed as a
       single token, which is directly parsed as a HyString.

       An uninterrupted string of characters, excluding spaces, brackets, quotes, double-quotes and comments, is
       parsed as an identifier.

       Identifiers are resolved to atomic models during the parsing phase in the following order:

          • HyIntegerHyFloatHyComplex (if the atom isn't a bare j)

          • HyKeyword (if the atom starts with :)

          • HySymbol

   HyString
       hy.models.string.HyString  is  the  base  class  of  string-equivalent  Hy  models.  It  also  represents
       double-quoted string literals, "", which compile down to unicode string  literals  in  Python.  HyStrings
       inherit  unicode  objects  in  Python  2,  and  string  objects  in  Python  3  (and  are  therefore  not
       encoding-dependent).

       HyString based models are immutable.

       Hy literal strings can span multiple lines, and are considered by the parser as a single unit, respecting
       the Python escapes for unicode strings.

   Numeric Models
       hy.models.integer.HyInteger  represents  integer  literals  (using  the long type on Python 2, and int on
       Python 3).

       hy.models.float.HyFloat represents floating-point literals.

       hy.models.complex.HyComplex represents complex literals.

       Numeric models are parsed using the corresponding Python routine, and valid numeric python literals  will
       be turned into their Hy counterpart.

   HySymbol
       hy.models.symbol.HySymbol  is  the  model  used  to  represent  symbols  in  the Hy language. It inherits
       HyString.

       HySymbol objects are mangled in the parsing phase, to help Python interoperability:

          • Symbols surrounded by asterisks (*) are turned into uppercase;

          • Dashes (-) are turned into underscores (_);

          • One trailing question mark (?) is turned into a leading is_.

       Caveat: as the mangling is done during the parsing phase, it is  possible  to  programmatically  generate
       HySymbols  that  can't  be  generated with Hy source code. Such a mechanism is used by gensym to generate
       "uninterned" symbols.

   HyKeyword
       hy.models.keyword.HyKeyword represents keywords in Hy. Keywords are symbols starting with a :. The  class
       inherits HyString.

       To  distinguish  HyKeywords  from  HySymbols,  without  the  possibility  of  (involuntary)  clashes, the
       private-use unicode character "\uFDD0" is prepended to the keyword literal before storage.

   Cons Cells
       hy.models.cons.HyCons is a representation of Python-friendly  cons  cells.   Cons  cells  are  especially
       useful to mimic features of "usual" LISP variants such as Scheme or Common Lisp.

       A cons cell is a 2-item object, containing a car (head) and a cdr (tail). In some Lisp variants, the cons
       cell is the fundamental building block, and S-expressions are actually represented  as  linked  lists  of
       cons  cells.  This  is not the case in Hy, as the usual expressions are made of Python lists wrapped in a
       HyExpression. However, the HyCons mimicks the behavior of "usual" Lisp variants thusly:

          • (cons something nil) is (HyExpression [something])(cons something some-list) is ((type some-list) (+ [something] some-list))  (if  some-list  inherits
            from list).

          • (get (cons a b) 0) is a(slice (cons a b) 1) is b

       Hy  supports  a dotted-list syntax, where '(a . b) means (cons 'a 'b) and '(a b . c) means (cons 'a (cons
       'b 'c)). If the compiler encounters a cons cell at the top level, it raises a compilation error.

       HyCons wraps the passed arguments (car and cdr) in Hy types, to ease the manipulation of cons cells in  a
       macro context.

   Hy Internal Theory
   Overview
       The  Hy  internals  work  by acting as a front-end to Python bytecode, so that Hy itself compiles down to
       Python Bytecode, allowing an unmodified Python runtime to run Hy code, without even noticing it.

       The way we do this is by translating Hy into an internal Python AST datastructure, and building that  AST
       down  into  Python  bytecode  using  modules  from  the Python standard library, so that we don't have to
       duplicate all the work of the Python internals for every single Python release.

       Hy works in four stages. The following sections will cover each step of Hy from source to runtime.

   Steps 1 and 2: Tokenizing and Parsing
       The first stage of compiling Hy is to lex the source into tokens that we can deal with. We use a  project
       called rply, which is a really nice (and fast) parser, written in a subset of Python called rpython.

       The lexing code is all defined in hy.lex.lexer. This code is mostly just defining the Hy grammar, and all
       the actual hard parts are taken care of by rply -- we just define "callbacks" for rply in  hy.lex.parser,
       which takes the tokens generated, and returns the Hy models.

       You can think of the Hy models as the "AST" for Hy, it's what Macros operate on (directly), and it's what
       the compiler uses when it compiles Hy down.

       SEE ALSO:
          Section Hy Models for more information on Hy models and what they mean.

   Step 3: Hy Compilation to Python AST
       This is where most of the magic in Hy happens. This is where we take Hy AST  (the  models),  and  compile
       them  into  Python  AST.  A  couple  of  funky things happen here to work past a few problems in AST, and
       working in the compiler is some of the most important work we do have.

       The compiler is a bit complex, so don't feel bad if you don't grok it on the first shot, it  may  take  a
       bit of time to get right.

       The  main entry-point to the Compiler is HyASTCompiler.compile. This method is invoked, and the only real
       "public" method on the class (that is to say, we don't really promise the API beyond that method).

       In fact, even internally, we don't recurse directly hardly ever, we  almost  always  force  the  Hy  tree
       through  compile,  and will often do this with sub-elements of an expression that we have. It's up to the
       Type-based dispatcher to properly dispatch sub-elements.

       All methods that preform a compilation are marked with the @builds() decorator. You can either  pass  the
       class  of the Hy model that it compiles, or you can use a string for expressions. I'll clear this up in a
       second.

   First Stage Type-Dispatch
       Let's start in the compile method. The first thing we do is check the Type of the thing  we're  building.
       We  look up to see if we have a method that can build the type() that we have, and dispatch to the method
       that can handle it. If we don't have any  methods  that  can  build  that  type,  we  raise  an  internal
       Exception.

       For  instance,  if  we  have  a  HyString,  we have an almost 1-to-1 mapping of Hy AST to Python AST. The
       compile_string method takes the HyString, and returns an ast.Str()  that's  populated  with  the  correct
       line-numbers and content.

   Macro-Expand
       If  we get a HyExpression, we'll attempt to see if this is a known Macro, and push to have it expanded by
       invoking hy.macros.macroexpand, then push the result back into HyASTCompiler.compile.

   Second Stage Expression-Dispatch
       The only special case is the HyExpression, since we need to create different AST depending on the special
       form  in  question.  For instance, when we hit an (if true true false), we need to generate a ast.If, and
       properly compile the sub-nodes. This is where the @builds() with a String as an argument comes in.

       For the compile_expression (which is defined with an @builds(HyExpression)) will dispatch  based  on  the
       string  of  the first argument. If, for some reason, the first argument is not a string, it will properly
       handle that case as well (most likely by raising an Exception).

       If the String isn't known to Hy, it will default to create an ast.Call, which will try to  do  a  runtime
       call (in Python, something like foo()).

   Issues Hit with Python AST
       Python  AST  is  great;  it's what's enabled us to write such a powerful project on top of Python without
       having to fight Python too hard. Like anything, we've had our fair share of issues, and  here's  a  short
       list of the common ones you might run into.

       Python differentiates between Statements and Expressions.

       This  might  not sound like a big deal -- in fact, to most Python programmers, this will shortly become a
       "Well, yeah" moment.

       In Python, doing something like:

       print for x in range(10): pass, because print prints expressions, and for isn't  an  expression,  it's  a
       control  flow  statement.  Things  like  1 + 1 are Expressions, as is lambda x: 1 + x, but other language
       features, such as if, for, or while are statements.

       Since they have no "value" to Python, this makes working in Hy hard, since doing  something  like  (print
       (if true true false)) is not just common, it's expected.

       As a result, we auto-mangle things using a Result object, where we offer up any ast.stmt that need to get
       run, and a single ast.expr that can be used to get the value of whatever was just run. Hy  does  this  by
       forcing assignment to things while running.

       As example, the Hy:

          (print (if true true false))

       Will turn into:

          if True:
              _mangled_name_here = True
          else:
              _mangled_name_here = False

          print _mangled_name_here

       OK, that was a bit of a lie, since we actually turn that statement into:

          print True if True else False

       By forcing things into an ast.expr if we can, but the general idea holds.

   Step 4: Python Bytecode Output and Runtime
       After  we have a Python AST tree that's complete, we can try and compile it to Python bytecode by pushing
       it through eval. From here on out, we're no longer in control, and Python is taking care  of  everything.
       This is why things like Python tracebacks, pdb and django apps work.

   Hy Macros
   Using gensym for Safer Macros
       When  writing  macros,  one must be careful to avoid capturing external variables or using variable names
       that might conflict with user code.

       We will use an example macro nif (see http://letoverlambda.com/index.cl/guest/chap3.html#sec_5 for a more
       complete description.) nif is an example, something like a numeric if, where based on the expression, one
       of the 3 forms is called depending on if the expression is positive, zero or negative.

       A first pass might be something like:

          (defmacro nif [expr pos-form zero-form neg-form]
            `(let [[obscure-name ~expr]]
              (cond [(pos? obscure-name) ~pos-form]
                    [(zero? obscure-name) ~zero-form]
                    [(neg? obscure-name) ~neg-form])))

       where obsure-name is an attempt to pick some variable name as not to conflict with  other  code.  But  of
       course, while well-intentioned, this is no guarantee.

       The  method  gensym is designed to generate a new, unique symbol for just such an occasion. A much better
       version of nif would be:

          (defmacro nif [expr pos-form zero-form neg-form]
            (let [[g (gensym)]]
              `(let [[~g ~expr]]
                 (cond [(pos? ~g) ~pos-form]
                       [(zero? ~g) ~zero-form]
                       [(neg? ~g) ~neg-form]))))

       This is an easy case, since there is only one symbol. But if there is a need for several  gensym's  there
       is a second macro with-gensyms that basically expands to a series of let statements:

          (with-gensyms [a b c]
            ...)

       expands to:

          (let [[a (gensym)
                [b (gensym)
                [c (gensym)]]
            ...)

       so our re-written nif would look like:

          (defmacro nif [expr pos-form zero-form neg-form]
            (with-gensyms [g]
              `(let [[~g ~expr]]
                 (cond [(pos? ~g) ~pos-form]
                       [(zero? ~g) ~zero-form]
                       [(neg? ~g) ~neg-form]))))

       Finally,  though  we  can  make a new macro that does all this for us. defmacro/g!  will take all symbols
       that begin with g! and automatically call gensym with the remainder of the symbol. So  g!a  would  become
       (gensym "a").

       Our final version of nif, built with defmacro/g! becomes:

          (defmacro/g! nif [expr pos-form zero-form neg-form]
            `(let [[~g!res ~expr]]
               (cond [(pos? ~g!res) ~pos-form]
                     [(zero? ~g!res) ~zero-form]
                     [(neg? ~g!res) ~neg-form]))))

   Checking Macro Arguments and Raising Exceptions
   Hy Compiler Built-Ins

CONTRIBUTOR MODULES INDEX

       Contents:

   Anaphoric Macros
       New in version 0.9.12.

       The anaphoric macros module makes functional programming in Hy very concise and easy to read.
          An anaphoric macro is a type of programming macro that deliberately captures some form supplied to the
          macro which may be referred to by an anaphor (an expression referring to  another).   —  Wikipedia  (‐
          http://en.wikipedia.org/wiki/Anaphoric_macro)

   Macros
   ap-if
       Usage: (ap-if (foo) (print it))

       Evaluates the first form for truthiness, and bind it to it in both the true and false branches.

   ap-each
       Usage: (ap-each [1 2 3 4 5] (print it))

       Evaluate the form for each element in the list for side-effects.

   ap-each-while
       Usage: (ap-each-while list pred body)

       Evaluate the form for each element where the predicate form returns True.

          => (ap-each-while [1 2 3 4 5 6] (< it 4) (print it))
          1
          2
          3

   ap-map
       Usage: (ap-map form list)

       The anaphoric form of map works just like regular map except that instead of a function object it takes a
       Hy form. The special name it is bound to the current object from the list in the iteration.

          => (list (ap-map (* it 2) [1 2 3]))
          [2, 4, 6]

   ap-map-when
       Usage: (ap-map-when predfn rep list)

       Evaluate a mapping over the list using a predicate function to determin when to apply the form.

          => (list (ap-map-when odd? (* it 2) [1 2 3 4]))
          [2, 2, 6, 4]

          => (list (ap-map-when even? (* it 2) [1 2 3 4]))
          [1, 4, 3, 8]

   ap-filter
       Usage: (ap-filter form list)

       As with ap-map we take a special form instead of a function to filter  the  elements  of  the  list.  The
       special name it is bound to the current element in the iteration.

          => (list (ap-filter (> (* it 2) 6) [1 2 3 4 5]))
          [4, 5]

   ap-reject
       Usage: (ap-reject form list)

       This function does the opposite of ap-filter, it rejects the elements passing the predicate . The special
       name it is bound to the current element in the iteration.

          => (list (ap-reject (> (* it 2) 6) [1 2 3 4 5]))
          [1, 2, 3]

   ap-dotimes
       Usage (ap-dotimes n body)

       This function evaluates the body n times, with the special variable it bound from 0 to 1-n. It is  useful
       for side-effects.

           => (setv n [])
           => (ap-dotimes 3 (.append n it))
           => n
          [0, 1, 2]

   ap-first
       Usage (ap-first predfn list)

       This  function  returns the first element that passes the predicate or None, with the special variable it
       bound to the current element in iteration.

          =>(ap-first (> it 5) (range 10))
          6

   ap-last
       Usage (ap-last predfn list)

       This function returns the last element that passes the predicate or None, with the  special  variable  it
       bound to the current element in iteration.

          =>(ap-last (> it 5) (range 10))
          9

   ap-reduce
       Usage (ap-reduce form list &optional initial-value)

       This  function  returns  the result of applying form to the first 2 elements in the body and applying the
       result and the 3rd element etc. until the list is exhausted. Optionally an initial value can be  supplied
       so  the function will be applied to initial value and the first element instead. This exposes the element
       being iterated as it and the current accumulated value as acc.

          =>(ap-reduce (+ it acc) (range 10))
          45

   loop/recur
       New in version 0.10.0.

       The loop / recur macro gives programmers a simple way to use tail-call optimization  (TCO)  in  their  Hy
       code.
          A  tail  call  is  a subroutine call that happens inside another procedure as its final action; it may
          produce a return value which is then immediately returned by the calling procedure. If any call that a
          subroutine  performs,  such  that  it might eventually lead to this same subroutine being called again
          down the call chain, is in tail position, such a subroutine is said to be tail-recursive, which  is  a
          special case of recursion. Tail calls are significant because they can be implemented without adding a
          new stack frame to the call stack. Most of the frame of the current procedure is not needed any  more,
          and  it  can  be  replaced  by  the  frame  of  the tail call. The program can then jump to the called
          subroutine. Producing such code instead of a standard call sequence is called tail  call  elimination,
          or  tail  call  optimization.  Tail  call  elimination  allows  procedure calls in tail position to be
          implemented as efficiently as goto statements, thus  allowing  efficient  structured  programming.   —
          Wikipedia (http://en.wikipedia.org/wiki/Tail_call)

   Macros
   loop
       loop establishes a recursion point. With loop, recur rebinds the variables set in the recursion point and
       sends code execution back to that recursion point. If recur is used in a non-tail position, an  exception
       is thrown.

       Usage: (loop bindings &rest body)

       Example:

          (require hy.contrib.loop)

          (defn factorial [n]
            (loop [[i n] [acc 1]]
              (if (zero? i)
                acc
                (recur (dec i) (* acc i)))))

          (factorial 1000)

   defmulti
       New in version 0.10.0.

       defmulti  lets  you  arity-overload  a  function  by  the given number of args and/or kwargs. Inspired by
       Clojure's take on defn.

          => (require hy.contrib.multi)
          =>   (defmulti fun
          ...     ([a] "a")
          ...     ([a b] "a b")
          ...     ([a b c] "a b c"))
          => (fun 1)
          "a"
          => (fun 1 2)
          "a b"
          => (fun 1 2 3)
          "a b c"

HACKING ON HY

   Join our Hyve!
       Please come hack on Hy!

       Please come hang out with us on #hy on irc.freenode.net!

       Please talk about it on Twitter with the #hy hashtag!

       Please blog about it!

       Please don't spraypaint it on your neighbor's fence (without asking nicely)!

   Hack!
       Do this:

       1. Create a virtual environment:

             $ virtualenv venv

          and activate it:

             $ . venv/bin/activate

          or use virtualenvwrapper to create and manage your virtual environment:

             $ mkvirtualenv hy
             $ workon hy

       2. Get the source code:

             $ git clone https://github.com/hylang/hy.git

          or use your fork:

             $ git clone git@github.com:<YOUR_USERNAME>/hy.git

       3. Install for hacking:

             $ cd hy/
             $ pip install -e .

       4. Install other develop-y requirements:

             $ pip install -r requirements-dev.txt

       5. Do awesome things; make someone shriek in delight/disgust at what you have wrought.

   Test!
       Tests are located in tests/. We use nose.

       To run the tests:

          $ nosetests

       Write tests---tests are good!

       Also, it is good to run the tests for all the platforms supported and for PEP 8 compliant code.  You  can
       do so by running tox:

          $ tox

   Document!
       Documentation is located in docs/. We use Sphinx.

       To build the docs in HTML:

          $ cd docs
          $ make html

       Write docs---docs are good! Even this doc!

   Contributing
       Contributions are welcome & greatly appreciated, every little bit helps in making Hy more awesome.

       Pull requests are great! We love them; here is a quick guide:

       • Fork  the repo and create a topic branch for a feature/fix. Avoid making changes directly on the master
         branch.

       • All incoming features should be accompanied with tests.

       • Before you submit a PR, please run the tests and check your code against the style guide.  You  can  do
         both of these things at once:

            $ make d

       • Make  commits  into  logical units, so that it is easier to track & navigate later. Before submitting a
         PR, try squashing the commits into changesets that are easy to come back to later. Also, make sure  you
         don't  leave  spurious  whitespace  in  the  changesets; this avoids creation of whitespace fix commits
         later.

       • As far as commit messages go, try to adhere to the following:

         • Try sticking to the 50 character limit for the first line of Git commit messages.

         • For more detail/explainations, follow this up with a blank line and continue describing the commit in
           detail.

       • Finally, add yourself to the AUTHORS file (as a separate commit): you deserve it :)

       • All  incoming  changes need to be acked by 2 different members of Hylang's core team. Additional review
         is clearly welcome, but we need a minimum of 2 signoffs for any change.

       • If a core member is sending in a PR, please find 2 core members that doesn't include the PR  submitter.
         The idea here is that one can work with the PR author, and a second acks the entire change set.

       • For  documentation  & other trivial changes, we're good to merge after one ACK. We've got low coverage,
         so it'd be great to keep that barrier low.

   Core Team
       The core development team of Hy consists of following developers:

       • Julien DanjouMorten LinderudJ Kenneth KingGergely NagyTuukka TurtoKaren RustadAbhishek LChristopher Allan WebberKonrad HinsenWill Kahn-GreenePaul TagliamonteNicolas DandrimontBob TolbertBerker PeksagClinton N. Dreisbachhan semaj

AUTHOR

       Paul Tagliamonte

       2013-2016, Paul Tagliamonte