6 ms·

A Clojure Crash Course

252 points by nonrecursive 13y ago

nonrecursive 13y ago
I hope this provides a good introduction to the Clojure language, apart from concerns about building and running Clojure programs. I'd love any feedback :)
- jdludlow 13y ago
  I can't speak to the Clojure introduction, because I was already semi-familiar with the language. However, I found your site via Google a few weeks ago when I was looking for an introduction to Emacs + Clojure. Having gone down this road several times in the past, I have to say that this is the best tutorial I've ever found on that topic. The repl and window examples were just what I needed as a complete Emacs newbie. The Emacs chapter was similarly good. It seemed to be aimed at someone who wanted to start writing code quickly. This is the first time in years that I've worked through an Emacs tutorial without firing up vim to edit a config file (at which point I usually realize that I won't be switching to Emacs that day). Thank you for taking the time to write all of this.
  - nonrecursive 13y ago
    Thank you for the feedback! Encouraging comments like this really help keep me motivated. I'm glad that the emacs tutorial was useful for you :)
- pseut 13y ago
  I came across your website googling for how to set up emacs w/ clojure... for someone with prior emacs experience, your step 2: "Delete ~/.emacs or ~/.emacs.d if they exist" seemed... extreme. If you have a time, maybe listing the key packages and what they do (and what they replace) would be really helpful.
- aidos 13y ago
  Great introduction - really well written, enjoyable to read. I read an article about clojurescript / om / react [0] the other day which piqued my interest - this is the first tutorial I've gone through on Clojure. The api actually feels pretty similar to Python (eg rest-param ~= args) so it mapped over nicely for me. I studied functional programming some years ago and have tinkered with the like of erlang in the past so none of the concepts you presented felt too foreign. I might be going insane but it looks like you have a typo in there - 'whether the ;; the part's name'*. Kudos, again. [0] http://swannodette.github.io/2013/12/17/the-future-of-javascript-mvcs/ http://swannodette.github.io/2013/12/17/the-future-of-javasc...
phren0logy 13y ago
I have been really enjoying this tutorial. If you wanted to be super timely you could add instructions for doing it in Light Table.
- elwell 13y ago
  I was wondering the same thing. While I don't think Emacs users will ever say that LightTable is better, they should consider: 1. LightTable might be better for new Clojure users who aren't yet attached to Emacs 2. You can use (some) Emacs key bindings in LightTable /not to start an editor war/
  - hexasquid 13y ago
    At the risk of starting a war - I'm used to Vim. Is there a benefit to looking into LightTable or Emacs if I want to get into Clojure?
    - MBlume 13y ago
      There may be, I'm not that familiar with either, but do try vim-fireplace, it's pretty darn good.
    - grayrest 13y ago
      Lisps work better from an editor that can provide tight REPL integration. I've used vim for 15 years and use it for everything else but it does not do this well. Clojure support via vim-fireplace is better than nothing and I've used it (and it's predecessors) for couple hundred line projects spaced out over the last few years but it's never felt good to me. Fireplace and the nREPL, unlike the older integration schemes, almost always work but my current complaint is that I don't like how the output is presented. Light Table does the integration right. You load up a clojure file, hit eval, and it works without having to mess with it. Additionally, it works well with Clojurescript, which I never really got working with Vim fireplace. The doc system is integrated, autocomplete works. The Light Table vim plugin provides decent but not great vim emulation (e.g. the b text object is missing, which is important for a lisp) and while it's not as nice for editing as my heavily customized home vim setup, I'm happier doing Clojure in LT than in Vim.
bcarrell 13y ago
This is really helpful. As someone who's never worked with a JVM language (or Lisp, for that matter) or Emacs, braveclojure is really enjoyable. Thanks!
euphemize 13y ago
hey great tutorial! really easy to go through, super helpful. My only suggestion : it would be great to have a small reference/cheatsheet/table to convert equivalent data structures and other syntactic details from closure to other languages. I found myself scrolling back up a lot to remember what "def" meant (coming from python this was confusing), whether "vector" was a dict or a list, etc. It interrupted the reading for a few seconds every time until "ah ha!" I found it. I remember spending about 50% of my time learning Mongo syntax just checking out their mysql <-> mongo syntax table - I assume most people checking out your tutorial will have experience with some previous form of programming (like me).
- elwell 13y ago
  I think most FP's will wince at the notion of a 1:1 comparison with any imperative language.
  - masklinn 13y ago
    He's not really asking for a 1:1 comparison though, just a mapping of common constructs (and a note when a construct makes no sense) in order to get his bearings.
- ryanatkn 13y ago
  cljs <-> js http://himera.herokuapp.com/synonym.html http://himera.herokuapp.com/synonym.html
  - masklinn 13y ago
    A bit outdated though e.g. for the first one, since 0.0.2060 cljs has grown (enable-console-print!) which sets print-fn to a wrapper around console.log. As a result, one can use all the usual clojure printing functions[0] and the output will be sent to the browser console. [0] http://clojure.org/other_functions#Other%20Useful%20Functions%20and%20Macros-Printing http://clojure.org/other_functions#Other%20Useful%20Function...
  - elwell 13y ago
actsasbuffoon 13y ago
I love the pacing of this tutorial. It has a wonderful no-nonsense delivery, and the pacing is fast enough to feel excitingly informative, but not so fast as to be intimidating. This is really great writing. As an Emacs user who hasn't yet gotten very far into a lisp, I look forward to having time to sit down and really dig into this tutorial. Thanks for creating this!
danielweber 13y ago
I've been having fun using clojure over the past week or two, and it's really nice to get a tutorial on all the vocabulary. Thanks.
mjburgess 13y ago
There really needs to be a JVM crash-course for clojure... I can understand the syntax well-enough, but I want to know what java libs i need/how i use them/etc. ie. when I have to "leave clojure".
- grayrest 13y ago
  http://www.clojure-toolbox.com/ http://www.clojure-toolbox.com/ Clojure has been around long enough that people have wrappers around most of the interesting common use java libs. If you're looking for something domain specific then it's usually better to find which java libs cover the domain and work from there.
  - DigitalJack 13y ago
    On top of that, direct java interop is not bad at all. Here is a talk on it: http://www.infoq.com/presentations/Clojure-Java-Interop http://www.infoq.com/presentations/Clojure-Java-Interop I confess I haven't watched that talk yet and only remembered hearing about it as I wrote this. But I imagine it is a good Launchpad.
    - andrewflnr 13y ago
      The point is, direct Java interop is useless, potentially worse, if you don't know anything about Java.
- Skinney 13y ago
  What do you mean? If you know Clojures syntax for Java interop, reading Java API's shouldn't be much of a problem. Searching for java howtos on how to use sockets and such should also give you a fair amount of results...
  - mjburgess 13y ago
    Yes... but reading api documentation isnt a tutorial. I was asking for a tutorial for common java api stuff. If a tutorial goes through some common apis then you can get a feel for how to read the documentation through a clojure lens.
tokipin 13y ago
i found the Clojure koans useful. (http://clojurekoans.com/ http://clojurekoans.com/) they're aimed at beginners so they would be a good companion/followup to this
- elwell 13y ago
  this is a good read: https://github.com/bbatsov/clojure-style-guide https://github.com/bbatsov/clojure-style-guide
brudgers 13y ago
Concludes with: By this point I highly recommend actually writing some code to solidify your Clojure knowledge if you haven't started already. While I will be among the quickest to acknowledge that there is great value to be gained by typing in example code, without structured exercises, the article might be providing a fine tutorial or feature list or cookbook, but it is not a course. Courses look more like "Learn Python the Hard Way" than blog entries. They're hard to make and one for Clojure is sorely needed. The easy parts of Clojure are the syntax and the common idioms. That's why Lisps have a long history as introductory programming languages. The hard part is learning to apply them to the sort of hard problems that one applies other programming languages to. All that to say, that there's nothing wrong with the article as an article. In fact I think it represents an admirable amount of work for a positive purpose. My only criticism is that it is not what it says it is, and the only reason that is a criticism is that it claims to do heavy lifting which it does not.
- nonrecursive 13y ago
  Apologies if the title submitted to HN was confusing. The actual chapter title is "Do Things: a Clojure Language Crash Course" but I felt that was too verbose here. The text is explicit about what will be covered: "In this chapter, you're going to explore the elements which comprise this Lisp core: syntax, functions, and data." Clojure language crash course is meant to distinguish these aspects from the other aspects of Clojure: the environment, the artifact ecosystem, and the mindset. I mention this distinction in the introduction: http://www.braveclojure.com/ http://www.braveclojure.com/ Other chapters begin to cover the mindset, or how to do things the Clojure way. "The Joy of Clojure" also covers this, from what I understand. Rich Hickey's talks are also great, of course.
  - brudgers 13y ago
    I agree. Rich Hickey's talks are an excellent resource, and he refers to them as talks not as courses, even though he expects and hopes some people will learn something from them. There's nothing to apologize for. It's just that it isn't a crash course, or a course of any kind for any meaningful meaning of "course". And I meant what I said about the amount of effort and thought that the article represents being worthy of praise...and what I said about there being a need for actual courses in Clojure.
mattfenwick 13y ago
As a Clojure fan, while I appreciate the author's effort, and admit I would do a much worse job, I'm bothered by oversimplifications like these: - "Like all Lisps, it employs a uniform structure" - "All Clojure code is written in a uniform structure" - "Forms have a uniform structure." - "In other languages, different operations might have different structures depending on the operator and the operands." - "No matter what operator you're using or what kind of data you're operating on, the structure is the same." It's pretty obvious that forms don't have a uniform structure (e.g. the structure of a number is pretty different from the structure of a vector), and that the structure depends on the operator (e.g. `def` special form vs. `or` macro). Yes, Clojure syntax is relatively simple, no need to oversell it. Still, that's a minor issue that doesn't detract from the overall quality and usefulness of the work.
- nonrecursive 13y ago
  Thanks for the feedback, I've been finding it tricky to get the explanation right here. I don't have much time now and I'll try to reply with more later, but macros, special forms, and functions do indeed all have the same structure of opening parenthesis, operator, operands, closing parenthesis.
- nonrecursive 13y ago
  One of the ideas I'm trying to convey is that the structure of the code is different from the syntax. With Clojure, special forms like def, if, etc, provide syntax in that each one has different rules for how their arguments get evaluated or, in the case of def, how the environment is changed. On top of that, you have macros which allow you to introduce arbitrary syntax. However, all Clojure code does have the same uniform structure. It's all composed of s-expressions, which are either atoms or other s-expressions enclosed in parentheses (for lists), braces (for maps), or brackets (for vectors). Thanks again for this feedback, having to explain this has given me some ideas for how to improve the chapter :)
lgas 13y ago
Technically this is the transliteration of that ruby code: (def severity :mild) (def error_message "OH GOD! IT'S A DISASTER! WE'RE ") (if (= severity :mild) (def error_message (str error_message "MILDLY INCONVENIENCED!")) (when (= severity :terrible) (def error_message (str error_message "DOOOOOOOMED!")))) And if we consider that a good transliteration then I'm not sure why this wouldn't suffice for the second one: (def failed_protagonist_names [ "Larry Potter" "Doreen the Explorer" "The Incredible Bulk" ]) (def failed_protagonist_names (assoc failed_protagonist_names 0 "Gary Potter")) ;; => ["Gary Potter" "Doreen the Explorer" "The Incredible Bulk"]
- nonrecursive 13y ago
  This repl snippet should show that you're not actually changing a data structure in place. Rather, you're creating a new data structure and changing an existing binding: user=> (def a [1 2 3]) user=> (def b a) user=> (def a ["a" "b" "c"]) user=> a ["a" "b" "c"] user=> b [1 2 3]

252 points by nonrecursive 13y ago

I hope this provides a good introduction to the Clojure language, apart from concerns about building and running Clojure programs. I'd love any feedback :)

jdludlow 13y ago
I can't speak to the Clojure introduction, because I was already semi-familiar with the language. However, I found your site via Google a few weeks ago when I was looking for an introduction to Emacs + Clojure. Having gone down this road several times in the past, I have to say that this is the best tutorial I've ever found on that topic. The repl and window examples were just what I needed as a complete Emacs newbie. The Emacs chapter was similarly good. It seemed to be aimed at someone who wanted to start writing code quickly. This is the first time in years that I've worked through an Emacs tutorial without firing up vim to edit a config file (at which point I usually realize that I won't be switching to Emacs that day). Thank you for taking the time to write all of this.
- nonrecursive 13y ago
  Thank you for the feedback! Encouraging comments like this really help keep me motivated. I'm glad that the emacs tutorial was useful for you :)
pseut 13y ago
I came across your website googling for how to set up emacs w/ clojure... for someone with prior emacs experience, your step 2: "Delete ~/.emacs or ~/.emacs.d if they exist" seemed... extreme. If you have a time, maybe listing the key packages and what they do (and what they replace) would be really helpful.
aidos 13y ago
Great introduction - really well written, enjoyable to read. I read an article about clojurescript / om / react [0] the other day which piqued my interest - this is the first tutorial I've gone through on Clojure. The api actually feels pretty similar to Python (eg rest-param ~= args) so it mapped over nicely for me. I studied functional programming some years ago and have tinkered with the like of erlang in the past so none of the concepts you presented felt too foreign. I might be going insane but it looks like you have a typo in there - 'whether the ;; the part's name'*. Kudos, again. [0] http://swannodette.github.io/2013/12/17/the-future-of-javascript-mvcs/ http://swannodette.github.io/2013/12/17/the-future-of-javasc...

phren0logy 13y ago

I have been really enjoying this tutorial. If you wanted to be super timely you could add instructions for doing it in Light Table.

elwell 13y ago
I was wondering the same thing. While I don't think Emacs users will ever say that LightTable is better, they should consider: 1. LightTable might be better for new Clojure users who aren't yet attached to Emacs 2. You can use (some) Emacs key bindings in LightTable /not to start an editor war/
- hexasquid 13y ago
  At the risk of starting a war - I'm used to Vim. Is there a benefit to looking into LightTable or Emacs if I want to get into Clojure?
  - MBlume 13y ago
    There may be, I'm not that familiar with either, but do try vim-fireplace, it's pretty darn good.
  - grayrest 13y ago
    Lisps work better from an editor that can provide tight REPL integration. I've used vim for 15 years and use it for everything else but it does not do this well. Clojure support via vim-fireplace is better than nothing and I've used it (and it's predecessors) for couple hundred line projects spaced out over the last few years but it's never felt good to me. Fireplace and the nREPL, unlike the older integration schemes, almost always work but my current complaint is that I don't like how the output is presented. Light Table does the integration right. You load up a clojure file, hit eval, and it works without having to mess with it. Additionally, it works well with Clojurescript, which I never really got working with Vim fireplace. The doc system is integrated, autocomplete works. The Light Table vim plugin provides decent but not great vim emulation (e.g. the b text object is missing, which is important for a lisp) and while it's not as nice for editing as my heavily customized home vim setup, I'm happier doing Clojure in LT than in Vim.

bcarrell 13y ago

This is really helpful. As someone who's never worked with a JVM language (or Lisp, for that matter) or Emacs, braveclojure is really enjoyable. Thanks!

euphemize 13y ago

hey great tutorial! really easy to go through, super helpful. My only suggestion : it would be great to have a small reference/cheatsheet/table to convert equivalent data structures and other syntactic details from closure to other languages. I found myself scrolling back up a lot to remember what "def" meant (coming from python this was confusing), whether "vector" was a dict or a list, etc. It interrupted the reading for a few seconds every time until "ah ha!" I found it. I remember spending about 50% of my time learning Mongo syntax just checking out their mysql <-> mongo syntax table - I assume most people checking out your tutorial will have experience with some previous form of programming (like me).

elwell 13y ago
I think most FP's will wince at the notion of a 1:1 comparison with any imperative language.
- masklinn 13y ago
  He's not really asking for a 1:1 comparison though, just a mapping of common constructs (and a note when a construct makes no sense) in order to get his bearings.
ryanatkn 13y ago
cljs <-> js http://himera.herokuapp.com/synonym.html http://himera.herokuapp.com/synonym.html
- masklinn 13y ago
  A bit outdated though e.g. for the first one, since 0.0.2060 cljs has grown (enable-console-print!) which sets print-fn to a wrapper around console.log. As a result, one can use all the usual clojure printing functions[0] and the output will be sent to the browser console. [0] http://clojure.org/other_functions#Other%20Useful%20Functions%20and%20Macros-Printing http://clojure.org/other_functions#Other%20Useful%20Function...
- elwell 13y ago

actsasbuffoon 13y ago

I love the pacing of this tutorial. It has a wonderful no-nonsense delivery, and the pacing is fast enough to feel excitingly informative, but not so fast as to be intimidating. This is really great writing. As an Emacs user who hasn't yet gotten very far into a lisp, I look forward to having time to sit down and really dig into this tutorial. Thanks for creating this!

danielweber 13y ago

I've been having fun using clojure over the past week or two, and it's really nice to get a tutorial on all the vocabulary. Thanks.

mjburgess 13y ago

There really needs to be a JVM crash-course for clojure... I can understand the syntax well-enough, but I want to know what java libs i need/how i use them/etc. ie. when I have to "leave clojure".

grayrest 13y ago
http://www.clojure-toolbox.com/ http://www.clojure-toolbox.com/ Clojure has been around long enough that people have wrappers around most of the interesting common use java libs. If you're looking for something domain specific then it's usually better to find which java libs cover the domain and work from there.
- DigitalJack 13y ago
  On top of that, direct java interop is not bad at all. Here is a talk on it: http://www.infoq.com/presentations/Clojure-Java-Interop http://www.infoq.com/presentations/Clojure-Java-Interop I confess I haven't watched that talk yet and only remembered hearing about it as I wrote this. But I imagine it is a good Launchpad.
  - andrewflnr 13y ago
    The point is, direct Java interop is useless, potentially worse, if you don't know anything about Java.
Skinney 13y ago
What do you mean? If you know Clojures syntax for Java interop, reading Java API's shouldn't be much of a problem. Searching for java howtos on how to use sockets and such should also give you a fair amount of results...
- mjburgess 13y ago
  Yes... but reading api documentation isnt a tutorial. I was asking for a tutorial for common java api stuff. If a tutorial goes through some common apis then you can get a feel for how to read the documentation through a clojure lens.

tokipin 13y ago

i found the Clojure koans useful. (http://clojurekoans.com/ http://clojurekoans.com/) they're aimed at beginners so they would be a good companion/followup to this

elwell 13y ago
this is a good read: https://github.com/bbatsov/clojure-style-guide https://github.com/bbatsov/clojure-style-guide

brudgers 13y ago

Concludes with: By this point I highly recommend actually writing some code to solidify your Clojure knowledge if you haven't started already. While I will be among the quickest to acknowledge that there is great value to be gained by typing in example code, without structured exercises, the article might be providing a fine tutorial or feature list or cookbook, but it is not a course. Courses look more like "Learn Python the Hard Way" than blog entries. They're hard to make and one for Clojure is sorely needed. The easy parts of Clojure are the syntax and the common idioms. That's why Lisps have a long history as introductory programming languages. The hard part is learning to apply them to the sort of hard problems that one applies other programming languages to. All that to say, that there's nothing wrong with the article as an article. In fact I think it represents an admirable amount of work for a positive purpose. My only criticism is that it is not what it says it is, and the only reason that is a criticism is that it claims to do heavy lifting which it does not.

nonrecursive 13y ago
Apologies if the title submitted to HN was confusing. The actual chapter title is "Do Things: a Clojure Language Crash Course" but I felt that was too verbose here. The text is explicit about what will be covered: "In this chapter, you're going to explore the elements which comprise this Lisp core: syntax, functions, and data." Clojure language crash course is meant to distinguish these aspects from the other aspects of Clojure: the environment, the artifact ecosystem, and the mindset. I mention this distinction in the introduction: http://www.braveclojure.com/ http://www.braveclojure.com/ Other chapters begin to cover the mindset, or how to do things the Clojure way. "The Joy of Clojure" also covers this, from what I understand. Rich Hickey's talks are also great, of course.
- brudgers 13y ago
  I agree. Rich Hickey's talks are an excellent resource, and he refers to them as talks not as courses, even though he expects and hopes some people will learn something from them. There's nothing to apologize for. It's just that it isn't a crash course, or a course of any kind for any meaningful meaning of "course". And I meant what I said about the amount of effort and thought that the article represents being worthy of praise...and what I said about there being a need for actual courses in Clojure.

mattfenwick 13y ago

As a Clojure fan, while I appreciate the author's effort, and admit I would do a much worse job, I'm bothered by oversimplifications like these: - "Like all Lisps, it employs a uniform structure" - "All Clojure code is written in a uniform structure" - "Forms have a uniform structure." - "In other languages, different operations might have different structures depending on the operator and the operands." - "No matter what operator you're using or what kind of data you're operating on, the structure is the same." It's pretty obvious that forms don't have a uniform structure (e.g. the structure of a number is pretty different from the structure of a vector), and that the structure depends on the operator (e.g. `def` special form vs. `or` macro). Yes, Clojure syntax is relatively simple, no need to oversell it. Still, that's a minor issue that doesn't detract from the overall quality and usefulness of the work.

nonrecursive 13y ago
Thanks for the feedback, I've been finding it tricky to get the explanation right here. I don't have much time now and I'll try to reply with more later, but macros, special forms, and functions do indeed all have the same structure of opening parenthesis, operator, operands, closing parenthesis.
nonrecursive 13y ago
One of the ideas I'm trying to convey is that the structure of the code is different from the syntax. With Clojure, special forms like def, if, etc, provide syntax in that each one has different rules for how their arguments get evaluated or, in the case of def, how the environment is changed. On top of that, you have macros which allow you to introduce arbitrary syntax. However, all Clojure code does have the same uniform structure. It's all composed of s-expressions, which are either atoms or other s-expressions enclosed in parentheses (for lists), braces (for maps), or brackets (for vectors). Thanks again for this feedback, having to explain this has given me some ideas for how to improve the chapter :)

lgas 13y ago

Technically this is the transliteration of that ruby code: (def severity :mild) (def error_message "OH GOD! IT'S A DISASTER! WE'RE ") (if (= severity :mild) (def error_message (str error_message "MILDLY INCONVENIENCED!")) (when (= severity :terrible) (def error_message (str error_message "DOOOOOOOMED!")))) And if we consider that a good transliteration then I'm not sure why this wouldn't suffice for the second one: (def failed_protagonist_names [ "Larry Potter" "Doreen the Explorer" "The Incredible Bulk" ]) (def failed_protagonist_names (assoc failed_protagonist_names 0 "Gary Potter")) ;; => ["Gary Potter" "Doreen the Explorer" "The Incredible Bulk"]

nonrecursive 13y ago
This repl snippet should show that you're not actually changing a data structure in place. Rather, you're creating a new data structure and changing an existing binding: user=> (def a [1 2 3]) user=> (def b a) user=> (def a ["a" "b" "c"]) user=> a ["a" "b" "c"] user=> b [1 2 3]