Beautiful literate programming. #1789

Closed
wants to merge 6 commits into
from

Conversation

Projects
None yet
5 participants
Contributor

revence27 commented Oct 21, 2011

As discussed at the issue jashkenas/coffee-script#1786
This patch enables very beautiful literate programming.

If it pleases @jashkenas, adding a magic test (instead or in conjunction with the filename test) shall be implemented as well.

Update:
Implemented magic test.

src/coffee-script.coffee
@@ -32,7 +32,7 @@ exports.helpers = require './helpers'
# compiler.
exports.compile = compile = (code, options = {}) ->
try
- (parser.parse lexer.tokenize code).compile options
+ (parser.parse lexer.tokenize (if (options.filename or '').match /\.literatecoffee$/ then code.replace(/(^|\n)(\S)/gi, '$1#$2') else code)).compile options
@michaelficarra

michaelficarra Oct 21, 2011

Collaborator

This line is WAY too long. Use a variable and split it.

@revence27

revence27 Oct 21, 2011

Contributor

Changed it in revence27/coffee-script@5a84fb4 to be three more lines, each of which is nevertheless shorter.

src/coffee-script.coffee
@@ -32,7 +32,10 @@ exports.helpers = require './helpers'
# compiler.
exports.compile = compile = (code, options = {}) ->
try
- (parser.parse lexer.tokenize code).compile options
+ transformedCode = code
+ if (options.filename or '').match /\.literatecoffee$/ then
@michaelficarra

michaelficarra Oct 21, 2011

Collaborator

if options.filename?.match /\.literatecoffee$/ then

@revence27

revence27 Oct 21, 2011

Contributor

Isn’t that the wrong use of it? We are not trying to soak up nulls; we are trying to return the better string for the method to work on. Soaking up nulls, because it is a monadic action, will also have to propagate, which is ugly, and which your snippet doesn’t do.

@michaelficarra

michaelficarra Oct 21, 2011

Collaborator

@revence27: what are the possible values of options.filename? I believe we are only expecting it to be undefined or a string literal. In the case that it is undefined, the test will fail as soon as it notices that options.filename is undefined. In the case that it is a string literal (well, not undefined or null), it will proceed to the match invocation, causing the test to fail if the result is falsey and pass if the result is truthy.

@revence27

revence27 Oct 21, 2011

Contributor

You are right.
Fixed it in revence27/coffee-script@95ac581 and now I am seriously going to bed. :-)

Changing

code.indexOf('Literate CoffeeScript\n') == 0

to for example

/^[^\n]*Literate CoffeeScript.*\n/.test code

would allow the first line to be inside a comment

    <!-- Literate CoffeeScript -->

or

    # Literate CoffeeScript

which can make it invisible when used with some tools.

Owner

revence27 replied Oct 25, 2011

No, when you need tools to ignore a preamble that is not “Literate CoffeeScript”, then you should use the file extension, .literatecoffee.
Your suggestion would make your comment, for example, pass as Literate CoffeeScript, even though it is not. :o) When the design is of something that executes arbitrary code, wooly heuristic tests are a strict no-no.

Or, tools that generate this stuff from the Literate CoffeeScript could be told to skip the first line (which, in their case, is generally easy to do).
Making the test any more complex than checking for exactly two tokens (known to be illegal in that position under valid CoffeeScript) would throw us back to having to use heuristics and, ultimately, to having false positives/negatives.

We should be readier to evolve new tools to work with Literate CoffeeScript (as @jashkenas said, regarding Docco) than to make the compiler less-correct. Beauty for the win.

It was indeed to make Literate CoffeeScript more compatible with existing markdown renderers. Love your direction and since you invoke beauty as a criteria: I retract the suggestion and look forward to new tools.

Contributor

revence27 commented Oct 25, 2011

@jashkenas As discussed in the issue, I have added the magic test.
It should be an alternative way to tell the compiler that we are doing Literate CoffeeScript.

any update on this?

Owner

jashkenas commented Sep 26, 2012

Let's move this conversation back over to #1786.

@jashkenas jashkenas closed this Sep 26, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment