hy (1)

[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

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" 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 and 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 datastructure 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 more "pure" lisps such as common lisp or emacs lisp, the data structure you see for 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 builtin 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 a 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 lisp 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]
=> (apply optional_arg []
...         {"keyword1" 1
...          "pos2" 2
...          "pos1" 3
...          "keyword2" 4})
...
[3, 2, 1, 4]

See how we use apply to handle the fancy passing? :)

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 (apply models.CharField [] {"max_length" 255})]
   [address (models.TextField)]
   [notes (models.TextField)]])

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!

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.

--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, it's going to come in handy.

These rules help make sure code is idiomatic and interface-able in both languages.

• Symbols in earmufs will be translated to the uppercased 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.

Builtins

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 datastructure.

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 dicts).

->

-> or 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))
=> (-> (+ 5 5) (output 5))
10 5

->>

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

=> (defn output [a b] (print a b))
=> (->> (+ 5 5) (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 form 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. Examples of usage:

=> (and True False)
False

=> (and True True)
True

=> (and True 1)
1

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

NOTE: and shortcuts 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. The example usage:

(assert (= variable expected-value))

Assert takes a single parameter, a conditional that evaluates to either True or False.

assoc

assoc form 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: datastructure to be modified, key or index and 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 macro can be used to build nested if-statements.

The following example shows the relationship between the macro and the expanded code:

(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, function (side-effect1) is called for each iteration. (side-effect2) however is called only for 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

the do and progn forms 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 by one of the 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 value, object or a 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: name of the function to define, vector of parameters and the body of the function:

(defn name [params] body)

Parameters may have 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 above, with the difference 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 have no other differences compared to 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, 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 case of a non-integer return from defmain, it's good to put (defmain) as the last bit 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!.

So 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 a mapping, a list, ...

=> (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 macro is used to make a sequence of method calls for an object easy.

=> (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 executed only if the for loop terminates normally. If the execution is halted with break, the else 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 that 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 form is used to generate a unique symbol to allow writing macros without accidental variable name clashes.

=> (gensym)
u':G_1235'

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

SEE ALSO: Section using-gensym

get

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

=> (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, just the assigning does.

Following example shows how global a is assigned a value in a function and later on printed on another function. Without the global keyword, the second function would 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

the if form is used to conditionally select code to be executed. It has to contain the condition block and the block to be executed if the condition evaluates True. Optionally it may contain a block that is executed in case the evaluation of the condition is False. The if-not form (new in 0.10.0) is similar, but the first block after the test will be executed when the test fails, while the other, conditional one, when the test succeeds - opposite of the order of the if form.

Example usage:

(if (money-left? account)
  (print "lets go shopping")
  (print "lets go and work"))

(if-not (money-left? account)
  (print "lets go and work")
  (print "lets go shopping"))

Truth values of Python objects are respected. Values None, False, zero of any numeric type, empty sequence and empty dictionary are considered False. Everything else is considered True.

lisp-if / lif

New in version 0.10.0.

For those that prefer a more lisp-y if clause, we have lisp-if, or lif. This only considers None/nil as false! All other values of python "falseiness" are considered true.

=> (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"

; And, same thing
=> (lif True "true" "false")
"true"
=> (lif nil "true" "false")
"false"

import

import is used to import modules, like in Python. There are several forms of import you can use.

;; 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: first parameter is vector of parameters and the rest is the body of the function. lambda returns a new function. In the 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 docstring. This is useful for giving class methods docstrings.

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

Then test it via the Python built-in help function:

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

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

let

let is used to create lexically scoped variables. They are created at the beginning of 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

let macro takes two parameters: a vector defining variables and body, which is being executed. variables is a vector where each element is either a single variable or a vector defining a variable value pair. In 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 form 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. Examples for usage:

=> (not True)
False

=> (not False)
True

=> (not None)
True

or

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

=> (or True False)
True

=> (and False False)
False

=> (and False 1 True False)
1

NOTE: or shortcuts and stops evaluating parameters as soon as the first true is encountered.

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

print

the print form 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 to 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 (\(ga) symbol.

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

quote

quote returns the form passed to it without evaluating. quote can be alternatively written using the (') 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, default value of None will be used instead. Third optional parameter is used to control step between the elements.

slice follows the same rules as the Python counterpart. Negative indecies are counted starting from the end of the list. Some examples of 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 have an else or finally block. If an error is raised with a matching catch block during execution of error-prone-function then that catch block will be executed. If no errors are raised the else block is executed. Regardless if an error was raised or not, the finally block is executed as last.

unless

unless macro is a shorthand for writing a if-statement that checks if the given conditional is False. The following shows how the macro expands into code.

(unless conditional statement)

(if conditional
  None
  (do statement))

unquote

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

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

\(ga(= 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)

\(ga(+ ~@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 when macro. The following shows how the macro is expanded into code.

(when conditional statement)

(if conditional (do statement))

while

while form is used to execute a single or more blocks as long as a condition is being met.

The following example will output "hello world!" on screen indefinitely:

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

with

with is used to wrap execution of a block with a context manager. The context manager can then set up the local system and tear it down in a controlled manner. Typical example of using with is 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 file NEWS and print its content on 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 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 & 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 function addition with a function that takes two parameters and calls the decorated function with values that are incremented by 1. When 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 form is used to generate a set of gensym for use in a macro.

(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 1 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

coll?

New in version 0.10.0.

Usage: (coll? x)

Returns true if argument 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)

Return 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 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)

Return True if coll is empty, i.e. (= 0 (len coll)).

=> (empty? [])
True

=> (empty? "")
True

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

every?

New in version 0.10.0.

Usage: (every? pred coll)

Return 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)

Return True if x is a float.

=> (float? 3.2)
True

=> (float? -2)
False

even?

Usage: (even? x)

Return 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 argument supplied to the function

=> (identity 4)
4

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

inc

Usage: (inc x)

Return 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)

Return 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)

Return 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 ...)

Return 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)

Return 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)

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

=> ;; 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)

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

=> ;; 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)

Generate 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:

\(ga\(ga

(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)

Return True if x is less than zero (0).

Raises TypeError if (not (numeric? x)).

=> (neg? -2)
True

=> (neg? 3)
False

=> (neg? 0)
False

nil?

Usage: (nil? x)

Return 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)

Return 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])

Return the nth item in a collection, counting from 0. Return the default value, nil, if out of bounds (unless specified otherwise). Raise 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)

Return True if x is a numeric, as defined in the Python numbers module class numbers.Number.

=> (numeric? -2)
True

=> (numeric? 3.2)
True

=> (numeric? "foo")
False

odd?

Usage: (odd? x)

Return True if x is odd.

Raises TypeError if (not (numeric? x)).

=> (odd? 13)
True

=> (odd? 2)
False

=> (odd? 0)
False

pos?

Usage: (pos? x)

Return True if x is greater than zero (0).

Raises TypeError if (not (numeric? x)).

=> (pos? 3)
True

=> (pos? -2)
False

=> (pos? 0)
False

second

Usage: (second coll)

Return 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)

Return the first logical 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)

Return True if x is a string.

=> (string? "foo")
True

=> (string? -2)
False

zero?

Usage: (zero? x)

Return True if x is zero (0).

=> (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-fn. Note that take-fn 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)

Return 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)

Return 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-while

Usage: (drop-while pred coll)

Return 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)

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

See also remove-fn.

=> (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)

Return 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)

Return an iterator of x, fn(x), fn(fn(x)).

=> (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 (defaults to sys.stdin), and can take a single byte as EOF (defaults to an empty string). Raises an 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)

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

See also filter-fn.

=> (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)

Return 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)

Return 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)

Return 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)

Return an iterator containing every nth 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)

Return an iterator from coll as long as predicate, 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] \(ga(, ~@expr))
=> #t(1 2 3)
(1, 2, 3)

You could even do like clojure, and have a literal for regular expressions!

=> (import re)
=> (defreader r [expr] \(ga(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 decorater saves the lambda in a dict 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:

• HyInteger

• HyFloat

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

• HyKeyword (if the atom starts with :)

• HyLambdaListKeyword (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.

HyLambdaListKeyword

hy.models.lambdalist.HyLambdaListKeyword represents lambda-list keywords, that is keywords used by the language definition inside function signatures. Lambda-list keywords are symbols starting with a &. The class inherits HyString

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 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]
  \(ga(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)]]
    \(ga(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]
    \(ga(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]
  \(ga(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 Builtins

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))

Evaluate the first form for trutheyness, and bind it to it in both the true and false branch.

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 clojures 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"

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 [email protected]:<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 pep8 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, 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 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 explanations etc. 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

Core development team of hy consists of following developers.

• Julien Danjou

• Morten Linderud

• J Kenneth King

• Gergely Nagy

• Tuukka Turto

• Karen Rustad

• Abhishek L

• Christopher Allan Webber

• Konrad Hinsen

• Will Kahn-Greene

• Paul Tagliamonte

• Nicolas Dandrimont

• Bob Tolbert

• Berker Peksag

• Clinton N. Dreisbach

• han semaj

Paul Tagliamonte

2013-2014, Paul Tagliamonte