Merge pull request #1 from hylang/master

update from upstream

.travis.yml

@@ -1,13 +1,21 @@
 sudo: false
 language: python
-python:
-  - "pypy"
-  - "2.7"
-  - "3.3"
-  - "3.4"
-cache: pip
-# command to run tests
-script: make travis
+matrix:
+  include:
+    - python: 3.5
+      env: TOXENV=py35
+env:
+  - TOXENV=py27
+  - TOXENV=py33
+  - TOXENV=py34
+  - TOXENV=pypy
+  - TOXENV=flake8
+install: pip install tox
+script: tox
+cache:
+  directories:
+    - .tox
+    - $HOME/.cache/pip
 after_success: make coveralls
 notifications:
   email:

AUTHORS

@@ -65,3 +65,7 @@
 * Antony Woods <antony@teamwoods.org>
 * Matthew Egan Odendahl <github.gilch@xoxy.net>
 * Tim Martin <tim@asymptotic.co.uk>
+* Johnathon Mlady <john@digitalvectorz.com>
+* Andrew Savchyn <dev@scorpil.com>
+* Lev Kravinsky <kravinskylev@gmail.com>
+* Luna Lunapiena <lunacodes@gmail.com>

CONTRIBUTING.rst

@@ -6,11 +6,20 @@ 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
+- `Fork the repo`_ and create a topic branch for a feature/fix. Avoid
   making changes directly on the master branch.
+  (If you're new to Git: `Start Here`_)
 
 - All incoming features should be accompanied with tests.
 
+- If you are contributing a major change to the Hy language (e.g. changing
+  the behavior of or removing functions or macros), or you're unsure of
+  the proposed change, please open an issue in the `issue tracker`_ before
+  submitting the PR. This will allow others to give feedback on your idea,
+  and it will avoid constant changes or wasted work. For other PRs (such as
+  documentation fixes or code cleanup), you can directly open the PR without
+  first opening a corresponding issue.
+
 - 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::
 
@@ -82,3 +91,6 @@ version 1.1.0, available at
 http://contributor-covenant.org/version/1/1/0/.
 
 .. _Contributor Covenant: http://contributor-covenant.org
+.. _issue tracker: https://github.com/hylang/hy/issues
+.. _Fork the Repo: https://help.github.com/articles/fork-a-repo/
+.. _Start Here: http://rogerdudler.github.io/git-guide/)

Makefile

@@ -67,14 +67,6 @@ endif
 	$(pip) install coveralls
 	$(pip) install --allow-all-external -e .
 
-travis: python
-	$(nose) -s --with-coverage --cover-package hy
-ifeq (PyPy,$(findstring PyPy,$(shell python -V 2>&1 | tail -1)))
-	@echo "skipping flake8 on pypy"
-else
-	flake8 hy bin tests
-endif
-
 coveralls:
 	$(coveralls)
 

NEWS

@@ -60,7 +60,7 @@ Changes from 0.10.0
   * nth returns default value when out of bounds
   * merge-with added
   * doto macro added
-  * keyword? to findout keywords
+  * keyword? to find out keywords
   * setv no longer allows "." in names
 
   [Internals ]
@@ -107,7 +107,7 @@ Changes from 0.9.12
    Many thanks to algernon for working on adderall, which helped
    push Hy further this cycle. Adderall is an implementation of miniKanren
    in Hy. If you're interested in using Adderall, check out hydiomatic,
-   which prettfies Hy source using Adderall rules.
+   which prettifies Hy source using Adderall rules.
 
    This release saw an increase of about 11 contributors for a point
    release, you guys rock!

README.md

@@ -6,7 +6,7 @@ Hy
 [![Version](https://img.shields.io/pypi/v/hy.svg)](https://pypi.python.org/pypi/hy)
 [![Coverage Status](https://img.shields.io/coveralls/hylang/hy/master.svg)](https://coveralls.io/r/hylang/hy)
 
-![XKCD #224](https://raw.github.com/hylang/shyte/18f6925e08684b0e1f52b2cc2c803989cd62cd91/imgs/xkcd.png)
+[![XKCD #224](https://raw.github.com/hylang/shyte/18f6925e08684b0e1f52b2cc2c803989cd62cd91/imgs/xkcd.png)](https://xkcd.com/224/)
 
 Lisp and Python should love each other. Let's make it happen. [Try it](http://try-hy.appspot.com/).
 
@@ -32,7 +32,7 @@ It's really awesome.
 
 Oh, and lisps are neat.
 
-![Cuddles the Hacker](http://i.imgur.com/QbPMXTN.png)
+![Cuddles the Hacker](https://i.imgur.com/QbPMXTN.png)
 
 (fan art from the one and only [doctormo](http://doctormo.deviantart.com/art/Cuddles-the-Hacker-372184766))
 
@@ -46,3 +46,4 @@ Project
 * Bug reports: We have no bugs! Your bugs are your own! (https://github.com/hylang/hy/issues)
 * License: MIT (Expat)
 * [Contributor Guidelines & Code of Conduct](https://github.com/hylang/hy/blob/master/CONTRIBUTING.rst)
+* IRC: Join #hy on [freenode](https://webchat.freenode.net/)

docs/contrib/anaphoric.rst

@@ -13,6 +13,9 @@ concise and easy to read.
 
     -- Wikipedia (http://en.wikipedia.org/wiki/Anaphoric_macro)
 
+To use these macros you need to require the hy.contrib.anaphoric module like so:
+
+``(require hy.contrib.anaphoric)``
 
 .. _ap-if:
 
@@ -233,7 +236,7 @@ xi
 
 Usage ``(xi body ...)``
 
-Returns a function with parameters implicitly determined by the presence in the body of xi parameters. An xi symbol designates the ith parameter (1-based, e.g. x1, x2, x3, etc.), or all remaining parameters for xi itself. This is not a replacement for lambda. The xi forms cannot be nested. 
+Returns a function with parameters implicitly determined by the presence in the body of xi parameters. An xi symbol designates the ith parameter (1-based, e.g. x1, x2, x3, etc.), or all remaining parameters for xi itself. This is not a replacement for lambda. The xi forms cannot be nested.
 
 This is similar to Clojure's anonymous function literals (``#()``).
 
@@ -244,5 +247,3 @@ This is similar to Clojure's anonymous function literals (``#()``).
    => (def add-10 (xi + 10 x1))
    => (add-10 6)
    16
-   
-

docs/language/api.rst

@@ -400,7 +400,7 @@ below:
 .. _defn:
 
 defn
-------------
+----
 
 ``defn`` macro is used to define functions. It takes three
 parameters: the *name* of the function to define, a vector of *parameters*,
@@ -430,7 +430,26 @@ Parameters may have the following keywords in front of them:
 	101.0
 
 &key
+    Parameter is a dict of keyword arguments. The keys of the dict
+    specify the parameter names and the values give the default values
+    of the parameters.
+
+    .. code-block:: clj
+
+       => (defn key-parameters [&key {"a" 1 "b" 2}]
+       ... (print "a is" a "and b is" b))
+       => (key-parameters :a 1 :b 2)
+       a is 1 and b is 2
+       => (key-parameters :b 1 :a 2)
+       a is 2 and b is 1
+
+    The following declarations are equivalent:
 
+    .. code-block:: clj
+
+       (defn key-parameters [&key {"a" 1 "b" 2}])
+
+       (defn key-parameters [&optional [a 1] [b 2]])
 
 &kwargs
     Parameter will contain 0 or more keyword arguments.
@@ -1489,6 +1508,27 @@ expands to:
    Section :ref:`using-gensym`
 
 
+xor
+---
+
+.. versionadded:: 0.12.0
+
+``xor`` is used in logical expressions to perform exclusive or. It takes two
+parameters. It returns ``True`` if only of the parameters is ``True``. In all
+other cases ``False`` is returned. Example usage:
+
+.. code-block:: clj
+
+    => (xor True False)
+    True
+
+    => (xor True True)
+    False
+
+    => (xor [] [0])
+    True
+
+
 yield
 -----
 
@@ -1502,7 +1542,7 @@ infinite series without consuming infinite amount of memory.
 .. code-block:: clj
 
     => (defn multiply [bases coefficients]
-    ...  (for [[(, base coefficient) (zip bases coefficients)]]
+    ...  (for [(, base coefficient) (zip bases coefficients)]
     ...   (yield (* base coefficient))))
 
     => (multiply (range 5) (range 5))
@@ -1514,7 +1554,7 @@ infinite series without consuming infinite amount of memory.
     => (import random)
     => (defn random-numbers [low high]
     ...  (while True (yield (.randint random low high))))
-    => (list-comp x [x (take 15 (random-numbers 1 50))])])
+    => (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]
 
 

docs/language/internals.rst

@@ -177,7 +177,7 @@ A cons cell is a 2-item object, containing a ``car`` (head) and a
 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
+``HyExpression``. However, the ``HyCons`` mimics the behavior of
 "usual" Lisp variants thusly:
 
  - ``(cons something nil)`` is ``(HyExpression [something])``
@@ -386,7 +386,7 @@ A first pass might be something like:
              [(zero? obscure-name) ~zero-form]
              [(neg? obscure-name) ~neg-form])))
 
-where ``obsure-name`` is an attempt to pick some variable name as not to
+where ``obscure-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.
 

docs/quickstart.rst

@@ -31,13 +31,18 @@ Quickstart
 
 7. Open up an elite programming editor and type::
 
+       #! /usr/bin/env hy
        (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::
+9. Make it executable::
 
-        hy awesome.hy
+        chmod +x awesome.hy
 
-10. Take a deep breath so as to not hyperventilate.
-11. Smile villainously and sneak off to your hydeaway and do
+10. And run your first Hy program::
+
+        ./awesome.hy
+
+11. Take a deep breath so as to not hyperventilate.
+12. Smile villainously and sneak off to your hydeaway and do
     unspeakable things.

docs/style-guide.rst

@@ -9,7 +9,7 @@ Hy Style Guide
 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.
+Lisp, while always maintaining Python interoperability.
 
 
 Prelude

docs/tutorial.rst

@@ -119,7 +119,7 @@ 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
+program and a data structure.)  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::
 
@@ -168,7 +168,7 @@ 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
+(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.)
@@ -258,6 +258,7 @@ In Hy, you would do:
 
 .. code-block:: clj
 
+   (setv somevar 33)
    (cond
     [(> somevar 50)
      (print "That variable is too big!")]
@@ -306,6 +307,13 @@ Comments start with semicolons:
   ; (print "but this will not")
   (+ 1 2 3)  ; we'll execute the addition, but not this comment!
 
+Hashbang (``#!``) syntax is supported:
+
+.. code-block:: clj
+
+   #! /usr/bin/env hy
+   (print "Make me executable, and run me!")
+
 Looping is not hard but has a kind of special structure.  In Python,
 we might do::
 
@@ -505,22 +513,22 @@ In Hy:
 Macros
 ======
 
-One really powerful feature of Hy are macros. They are small functios that are
+One really powerful feature of Hy are macros. They are small functions that are
 used to generate code (or data). When program written in Hy is started, the
-macros are executed and their output is placed in program source. After this,
+macros are executed and their output is placed in the program source. After this,
 the program starts executing normally. Very simple example:
 
 .. code-block:: clj
 
   => (defmacro hello [person]
   ...  `(print "Hello there," ~person))
-  => (Hello "Tuukka")
+  => (hello "Tuukka")
   Hello there, Tuukka
 
 The thing to notice here is that hello macro doesn't output anything on
 screen. Instead it creates piece of code that is then executed and prints on
-screen. Macro writes a piece of program that looks like this (provided that
-we used "Tuukka" as parameter:
+screen. This macro writes a piece of program that looks like this (provided that
+we used "Tuukka" as parameter):
 
 .. code-block:: clj
 
@@ -536,14 +544,14 @@ We can also manipulate code with macros:
   => (rev (1 2 3 +))
   6
 
-The code that was generated with this macro just switched around some the
-elements, so by the time program started executing, it actually red:
+The code that was generated with this macro just switched around some of the
+elements, so by the time program started executing, it actually reads:
 
 .. code-block:: clj
 
   (+ 1 2 3)
 
-Sometimes it's nice to have a very short name for macro that doesn't take much
+Sometimes it's nice to have a very short name for a macro that doesn't take much
 space or use extra parentheses. Reader macros can be pretty useful in these
 situations (and since Hy operates well with unicode, we aren't running out of
 characters that soon):
@@ -556,14 +564,14 @@ characters that soon):
   => #↻(1 2 3 +)
   6
 
-Macros are useful when one wishes to extend the Hy or write their own
+Macros are useful when one wishes to extend Hy or write their own
 language on top of that. Many features of Hy are macros, like ``when``,
 ``cond`` and ``->``.
 
 To use macros defined in a different module, it is not enough to
 ``import`` the module, because importing happens at run-time, while we
 would need macros at compile-time. Instead of importing the module
-with macros, it must be ``require``d:
+with macros, ``require`` must be used:
 
 .. code-block:: clj