Literate CoffeeScript

[revence27]

This file, as it is, has been taken from tests/literate.literatecoffee in my fork. Without making any changes to it whatsoever, it is valid literate CoffeeScript, if you just copy and paste it into an editor, and make my fork of CoffeeScript run on it. Make the file end in .literatecoffee to make it go into literate mode. I wonder if Mr. Jeremy Ashkenas thinks it is a good idea. It would be good to know, before I send a pull request. (Oops! Earlier pull request for binary literals was pending, and it subsumed this one. Oh, well.) The change is only one line in only one file, and it is bound to be faster than fast in use. It is in my commit revence27/coffee-script@132d306e3391182dc2c410b9c46251d476e74c3f with an accompanying modification (different commit) of the Cakefile, that it may look for .literatecoffee files in the tests.

This, of course, is inspired by the Haskell programming language, but it is neater that the Haskell version of literate programming.

Beautiful Literate Programming

If this file parses at all, that is the test, and it has passed.

Originally, literate programming did not mean heavily-commented code. However, owing to the System, that is what it evolved to mean. Literate programming is supposed to be where code invades the commentary, not lots of comments invading the code.

  test "If this parses, literate coffee works.", ->
    eq 'So beautiful, I want to cry.', 'So beautiful, I want to cry.'

Under this scheme, everything is a comment. Except the bits that are indented. If a line does not start with whitespace, it is a comment. Everything else is code.

  test "I parse, therefore I work.", ->
    eq 4, 100 - 96

This is how we shall proceed with writing a string reverse in CoffeeScript.

  reverse = (str) ->
    rez = ''
    for chr in str
      rez = chr + rez
    rez

And then we will use it.

  test "Using a function defined within literate CoffeeScript.", ->
    eq 'So beautiful, I want to cry.', reverse '.yrc ot tnaw I ,lufituaeb oS'

See? Wasn't ugly, was it? Work on a syntax mode should not be difficult, in my opinion. (Although the only syntax things I know how to do are Vim, and even those, not too perfectly.) That will be all.

[bergie]

@supersym good point. My noweb.php supports multiple files in very similar manner.

Defining a named chunk of code:

<<my cool chunk>>=
# some code
@

Defining a file and including code:

<<somefile.coffee>>=
  exports.foo = (somearg) ->
    <<my cool chunk>>
@

[supersym]

Yeah exactly I noticed something like that and, although I find the notation ugly, its a simple and elegant way of working with this style. Personally I like that I can stay on the same line with coffeescript, since the fences are there to stay I guess and the (path/filename) looks clean and clear enough to me. And since I know it to be parsable by coffee-script can just omit the .extension.

Last thing I noticed, that the used inline #macro() more or less inside the paragraphs to do stuff.

Any thoughts if we could call our methods in a non-significant whitespace manner? Probably, the best candidates might be to use the markdown _ or * or backtick + another symbol to escape out of the texts like the pound, or perhaps 3x _. Not sure.

[supersym]

Btw, if you have a customer who knows exactly what they want, have them write down the story and put code in between :) Or just comments there where you are unsure or want questions answered. My personal dialect will probably provide some conventions/enhanchements in that order of communicating messages as footnotes etc. Also I like to have some convention to autoindex and number illustrations etc like tex does.

Shame that Markdown/HTML doesn't handle 1., 1.1, 1.2 and that kind of enumerations. Or does it?

[supersym]

Well can't clean up so it seems... In short, perhaps implicit ```coffeescript blocks would be nice. That's the only thing bugging me still but its relatively easy made anyway.

He is another example of a literate program on GitHub: a Clojure to C++ compiler

And Emacs org-mode example http://doc.norang.ca/org-mode.org.html and http://orgmode.org/worg/org-contrib/babel/intro.html

Another example of Lisp dialect LP (Scheme/Racket) here and a blog post here

Maybe some want to learn from other language implementations.

[deanh]

Should this have closed with 1.5?

[michaelficarra]

Looks like it. Closing.