Merge branch 'intro_docs' of git://github.com/cwebber/hy

This commit is contained in:
Paul R. Tagliamonte 2013-04-01 07:35:16 -04:00
commit 64ef3ee5ec
2 changed files with 207 additions and 0 deletions

View File

@ -1,3 +1,4 @@
* Paul Tagliamonte <paultag@debian.org> * Paul Tagliamonte <paultag@debian.org>
* Thomas Mashek <thomas@thescoundrels.net> * Thomas Mashek <thomas@thescoundrels.net>
* Amrut Joshi <amrut.joshi@gmail.com> * Amrut Joshi <amrut.joshi@gmail.com>
* Christopher Allan Webber <cwebber@dustycloud.org>

View File

@ -4,3 +4,209 @@ Language Spec
This bit covers a bit about Hy's lovable quirks and eccentricities. This bit covers a bit about Hy's lovable quirks and eccentricities.
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::
(def result (- (/ (+ 1 3 88) 2) 8))
This would return 37. 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::
(def result (- (/ (+ 1 3 88) 2) 8))
# simplified to...
(def result (- (/ 92 2) 8))
# simplified to...
(def result (- 46 8))
# simplified to...
(def result 38)
As you probably guessed, this last expression with "def" 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!")
(def name (raw_input "What is your name? "))
(def age (raw_input "What is your age? "))
(print (+ "Hello " name "! I see you are "
age " years old.")))
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 python flavored lisp (or vice versa?)
-------------------------------------------
Hy converts to python's own abstract syntax tree, so you'll soon start
to find that all the familiar power of
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'}
(You may notice that at present, the common lisp method of quoting
things like so::
'(1 2 3)
does not work. Instead, use angle brackets as above.)
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:
(def this-string " fooooo ")
(this-string.strip)
What about conditionals?
(if (try-some-thing)
(print "this is if true")
(print "this is if false"))
Unfortunately there is no elif or cond that I can find yet. Hopefully
we'll get such a macro soon :)
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!"))
Comments start with semicolons::
(print "this will run")
; (print "but this will not")
(+ 1 2 3) ; we won't execute this either
TODO
----
- How do I define classes?
- Blow your mind with macros!
- Where's my banana???