Various changes to documentation pages
- Standardized capitalization of Hy, Lisp(s), and Python. - Added periods to the end of list items. - Use inline code blocks for inline code. - Stripped trailing whitespace. - Other miscellaneous grammatical changes.
This commit is contained in:
Kevin Yap
parent
74a8ead6dc
commit
3e0ea7a131
@ -1,35 +1,33 @@
|
||||
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:
|
||||
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
|
||||
- Fork the repo and create a topic branch for a feature/fix. Avoid
|
||||
making changes directly on the master branch.
|
||||
|
||||
- All incoming features should be accompanied with tests
|
||||
- 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::
|
||||
against the style guide. You can do both of these things at once::
|
||||
|
||||
$ make d
|
||||
|
||||
- Make commits into logical units, so that it is easier to track &
|
||||
navigate later. Before submitting a PR, try squashing the commits
|
||||
into changesets that are easy to come back to later. Also make sure
|
||||
you don't leave spurious whitespace in the changesets, this avoids
|
||||
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:
|
||||
- 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
|
||||
+ 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
|
||||
+ For more detail/explainations, follow this up with a blank line and
|
||||
continue describing the commit in detail.
|
||||
|
||||
|
||||
- Finally add yourself to the AUTHORS file (as a separate commit), you
|
||||
- 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
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
===============
|
||||
Hacking on hy
|
||||
Hacking on Hy
|
||||
===============
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
Join our hyve!
|
||||
Join our Hyve!
|
||||
==============
|
||||
|
||||
Please come hack on hy!
|
||||
Please come hack on Hy!
|
||||
|
||||
Please come hang out with us on ``#hy`` on ``irc.freenode.net``!
|
||||
|
||||
@ -23,7 +23,7 @@ Hack!
|
||||
|
||||
Do this:
|
||||
|
||||
1. create a `virtual environment
|
||||
1. Create a `virtual environment
|
||||
<https://pypi.python.org/pypi/virtualenv>`_::
|
||||
|
||||
$ virtualenv venv
|
||||
@ -38,23 +38,24 @@ Do this:
|
||||
$ mkvirtualenv hy
|
||||
$ workon hy
|
||||
|
||||
2. get the source code::
|
||||
2. Get the source code::
|
||||
|
||||
$ git clone https://github.com/hylang/hy.git
|
||||
|
||||
or use your fork::
|
||||
|
||||
$ git clone git@github.com:<YOUR_USERNAME>/hy.git
|
||||
3. install for hacking::
|
||||
|
||||
3. Install for hacking::
|
||||
|
||||
$ cd hy/
|
||||
$ pip install -e .
|
||||
|
||||
4. install other develop-y requirements::
|
||||
4. Install other develop-y requirements::
|
||||
|
||||
$ pip install -r requirements-dev.txt
|
||||
|
||||
5. do awesome things; make someone shriek in delight/disgust at what
|
||||
5. Do awesome things; make someone shriek in delight/disgust at what
|
||||
you have wrought.
|
||||
|
||||
|
||||
@ -70,8 +71,8 @@ To run the tests::
|
||||
|
||||
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::
|
||||
Also, it is good to run the tests for all the platforms supported and for
|
||||
PEP 8 compliant code. You can do so by running tox::
|
||||
|
||||
$ tox
|
||||
|
||||
@ -97,6 +98,6 @@ Contributing
|
||||
Core Team
|
||||
=========
|
||||
|
||||
Core development team of hy consists of following developers.
|
||||
The core development team of Hy consists of following developers:
|
||||
|
||||
.. include:: coreteam.rst
|
||||
|
||||
@ -11,10 +11,10 @@ Quickstart
|
||||
**HOW TO GET HY REAL FAST**:
|
||||
|
||||
1. Create a `Virtual Python Environment
|
||||
<https://pypi.python.org/pypi/virtualenv>`_
|
||||
2. Activate your Virtual Python Environment
|
||||
3. Install `hy from PyPI <https://pypi.python.org/pypi/hy>`_ with ``pip install hy``
|
||||
4. Start a REPL with ``hy``
|
||||
<https://pypi.python.org/pypi/virtualenv>`_.
|
||||
2. Activate your Virtual Python Environment.
|
||||
3. Install `hy from PyPI <https://pypi.python.org/pypi/hy>`_ with ``pip install hy``.
|
||||
4. Start a REPL with ``hy``.
|
||||
5. Type stuff in the REPL::
|
||||
|
||||
=> (print "Hy!")
|
||||
@ -25,19 +25,19 @@ Quickstart
|
||||
|
||||
etc
|
||||
|
||||
6. Hit CTRL-D when you're done
|
||||
6. Hit CTRL-D when you're done.
|
||||
|
||||
OMG! That's amazing! I want to write a hy program.
|
||||
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.")
|
||||
(print "I was going to code in Python syntax, but then I got Hy.")
|
||||
|
||||
8. Save as ``awesome.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
|
||||
10. Take a deep breath so as to not hyperventilate.
|
||||
11. Smile villainously and sneak off to your hydeaway and do
|
||||
unspeakable things
|
||||
unspeakable things.
|
||||
|
||||
@ -3,7 +3,7 @@ Tutorial
|
||||
========
|
||||
|
||||
.. TODO
|
||||
..
|
||||
..
|
||||
.. - How do I index into arrays or dictionaries?
|
||||
.. - How do I do array ranges? e.g. x[5:] or y[2:10]
|
||||
.. - Blow your mind with macros!
|
||||
@ -12,34 +12,34 @@ Tutorial
|
||||
|
||||
Welcome to the Hy tutorial!
|
||||
|
||||
In a nutshell, Hy is a lisp dialect, but one that converts its
|
||||
structure into Python... literally a conversion into Python's abstract
|
||||
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!)
|
||||
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
|
||||
- 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!
|
||||
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
|
||||
Basic intro to Lisp for Pythonistas
|
||||
===================================
|
||||
|
||||
Okay, maybe you've never used lisp before, but you've used python!
|
||||
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:
|
||||
A "hello world" program in Hy is actually super simple. Let's try it:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
(print "hello world")
|
||||
|
||||
See? Easy! As you may have guessed, this is the same as the python
|
||||
See? Easy! As you may have guessed, this is the same as the Python
|
||||
version of::
|
||||
|
||||
print "hello world"
|
||||
@ -58,7 +58,7 @@ Which would return 4 and would be the equivalent of:
|
||||
|
||||
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
|
||||
passed in. In fact, in Hy (as with most Lisps) we can pass in
|
||||
multiple arguments to the plus operator:
|
||||
|
||||
.. code-block:: clj
|
||||
@ -67,13 +67,13 @@ multiple arguments to the plus operator:
|
||||
|
||||
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
|
||||
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:
|
||||
the Hy interpreter:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -81,13 +81,13 @@ the hy interpreter:
|
||||
|
||||
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::
|
||||
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...
|
||||
@ -97,7 +97,7 @@ exercise first in python::
|
||||
# simplified to...
|
||||
result = 38
|
||||
|
||||
Now let's try the same thing in hy:
|
||||
Now let's try the same thing in Hy:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -109,28 +109,28 @@ Now let's try the same thing in hy:
|
||||
; simplified to...
|
||||
(setv result 38)
|
||||
|
||||
As you probably guessed, this last expression with "setv" means to
|
||||
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,
|
||||
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::
|
||||
examples, so let's write a simple Python program, test it, and then
|
||||
show the equivalent Hy program::
|
||||
|
||||
def simple_conversation():
|
||||
print "Hello! I'd like to get to know you. Tell me about yourself!"
|
||||
name = raw_input("What is your name? ")
|
||||
age = raw_input("What is your age? ")
|
||||
print "Hello " + name + "! I see you are " + age + " years old."
|
||||
|
||||
|
||||
simple_conversation()
|
||||
|
||||
|
||||
If we ran this program, it might go like::
|
||||
|
||||
Hello! I'd like to get to know you. Tell me about yourself!
|
||||
@ -138,7 +138,7 @@ If we ran this program, it might go like::
|
||||
What is your age? 38
|
||||
Hello Gary! I see you are 38 years old.
|
||||
|
||||
Now let's look at the equivalent hy program:
|
||||
Now let's look at the equivalent Hy program:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -155,7 +155,7 @@ 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
|
||||
(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
|
||||
@ -165,23 +165,23 @@ 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
|
||||
very simple data structure as the core of Lisp is based on. For one
|
||||
thing, it means that your programs are easy to parse and that the
|
||||
entire actual structure of the program is very clearly exposed to you.
|
||||
(There's an extra step in hy where the structure you see is converted
|
||||
to python's own representations... in more "pure" lisps such as common
|
||||
lisp or emacs lisp, the data structure you see for the code and the
|
||||
to Python's own representations ... in "purer" Lisps such as Common
|
||||
Lisp or Emacs Lisp, the data structure you see in the code and the
|
||||
data structure that is executed is much more literally close.)
|
||||
|
||||
Another implication of this is macros: if a program's structure is a
|
||||
simple data structure, that means you can write code that can write
|
||||
code very easily, meaning that implementing entirely new language
|
||||
features can be very fast. Previous to hy, this wasn't very possible
|
||||
for python programmers... now you too can make use of macros'
|
||||
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 is a Lisp-flavored Python
|
||||
============================
|
||||
|
||||
Hy converts to Python's own abstract syntax tree, so you'll soon start
|
||||
@ -199,7 +199,7 @@ Hy. Let's experiment with this in the hy interpreter::
|
||||
=> (, 1 2 3)
|
||||
(1, 2, 3)
|
||||
|
||||
If you are familiar with other lisps, you may be interested that Hy
|
||||
If you are familiar with other Lisps, you may be interested that Hy
|
||||
supports the Common Lisp method of quoting:
|
||||
|
||||
.. code-block:: clj
|
||||
@ -207,7 +207,7 @@ supports the Common Lisp method of quoting:
|
||||
=> '(1 2 3)
|
||||
(1L 2L 3L)
|
||||
|
||||
You also have access to all the builtin types' nice methods::
|
||||
You also have access to all the built-in types' nice methods::
|
||||
|
||||
=> (.strip " fooooo ")
|
||||
"fooooo"
|
||||
@ -216,7 +216,7 @@ 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
|
||||
That's right---Lisp with dot notation! If we have this string
|
||||
assigned as a variable, we can also do the following:
|
||||
|
||||
.. code-block:: clj
|
||||
@ -232,13 +232,13 @@ What about conditionals?:
|
||||
(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"!).
|
||||
As you can tell above, the first argument to ``if`` is a truth test, the
|
||||
second argument is the body if true, and the third argument (optional!)
|
||||
is if false (ie. ``else``).
|
||||
|
||||
If you need to do more complex conditionals, you'll find that you
|
||||
don't have elif available in hy. Instead, you should use something
|
||||
called "cond". In python, you might do something like::
|
||||
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:
|
||||
@ -248,7 +248,7 @@ called "cond". In python, you might do something like::
|
||||
else:
|
||||
print "That variable is jussssst right!"
|
||||
|
||||
In hy, you would do:
|
||||
In Hy, you would do:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -260,12 +260,12 @@ In hy, you would do:
|
||||
[true
|
||||
(print "That variable is jussssst right!")])
|
||||
|
||||
What you'll notice is that cond switches off between a some statement
|
||||
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!
|
||||
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:
|
||||
|
||||
@ -288,8 +288,8 @@ You can do the following:
|
||||
(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"
|
||||
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:
|
||||
@ -300,13 +300,13 @@ Comments start with semicolons:
|
||||
; (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,
|
||||
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:
|
||||
The equivalent in Hy would be:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -314,21 +314,21 @@ The equivalent in hy would be:
|
||||
(print (+ "'i' is now at " (str i))))
|
||||
|
||||
|
||||
You can also import and make use of various python libraries. For
|
||||
You can also import and make use of various Python libraries. For
|
||||
example:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
(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:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
(with [[f (open "/tmp/data.in")]]
|
||||
(print (.read f)))
|
||||
|
||||
@ -336,15 +336,15 @@ 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::
|
||||
|
||||
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:
|
||||
In Hy, you could do these like:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -359,12 +359,12 @@ In hy, you could do these like:
|
||||
|
||||
; 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'),
|
||||
@ -376,11 +376,11 @@ In hy, you could do these like:
|
||||
|
||||
|
||||
Python has support for various fancy argument and keyword arguments.
|
||||
In python we might see::
|
||||
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)
|
||||
@ -401,7 +401,7 @@ The same thing in Hy::
|
||||
... "pos2" 2
|
||||
... "pos1" 3
|
||||
... "keyword2" 4})
|
||||
...
|
||||
...
|
||||
[3, 2, 1, 4]
|
||||
|
||||
See how we use apply to handle the fancy passing? :)
|
||||
@ -431,7 +431,7 @@ The Hy equivalent:
|
||||
(import pprint)
|
||||
(pprint.pprint (, foo bar args kwargs)))
|
||||
|
||||
Finally, of course we need classes! In python we might have a class
|
||||
Finally, of course we need classes! In Python, we might have a class
|
||||
like::
|
||||
|
||||
class FooBar(object):
|
||||
@ -460,7 +460,7 @@ In Hy:
|
||||
; Currently needed for --init-- because __init__ needs None
|
||||
; Hopefully this will go away :)
|
||||
None)]
|
||||
|
||||
|
||||
[get-x
|
||||
(fn [self]
|
||||
"Return our copy of x"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user