coffee-formatter

<!DOCTYPE html> <html> <head> <title>Coffee-Formatter</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1 id="coffee-formatter">Coffee-Formatter</h1> <h2 id="introduction">Introduction</h2> CoffeeFormatter (abbreviated as CF) is a, guess what, formatter for CoffeeScript. Let me know if you were actually expecting otherwise lol. The code is written in Literate CoffeeScript. Checkout Wikipedia for what “Literate Programming” means. <h2 id="code">Code</h2> <h3 id="dependencies">Dependencies</h3> CF relies on the following packages: <ul> <li><code>lazy</code> for reading files line by line. An example is given <a href="http://stackoverflow.com/questions/6156501/read-a-file-one-line-at-a-time-in-node-js">here</a>.</li> <li><code>fs</code> for file io.</li> <li><code>optimist</code> for command line parsing.</li> </ul> Code: <div class='highlight'><pre>Lazy = require 'lazy' fs = require 'fs'</pre></div> </div> By default, we use a tab width of 2 and use spaces exclusively. This is the style most widely used in the community. For a detailed guide of CoffeeScript style, check out <a href="https://github.com/polarmobile/coffeescript-style-guide">this</a>. <div class='highlight'><pre>argv = (require 'optimist') .default('tab-width', 2) .default('use-space', true) .argv</pre></div> <h3 id="constants">Constants</h3> We define a set of constants, including: Two-space operators. These operators should have one space both before and after. <div class='highlight'><pre>TWO_SPACE_OPERATORS = ['?=', '=', '+=', '-=', '==', '<=', '>=', '!', '>', '<', '+', '-', '*', '/', '%']</pre></div> One-space operators. They should have one space after. <div class='highlight'><pre>ONE_SPACE_OPERATORS = [':', '?', ')', '}', ',']</pre></div> <h3 id="helper-functions">Helper Functions</h3> Given a line and an index, the function determines whether or not the index is inside of a CoffeeScript string or part of a CoffeeScript comment. <div class='highlight'><pre>inStringOrComment = (index, line) -> for c, i in line if c == '#' and i <= index return true if c == "'" or c == '"' subLine = line.substr (i + 1) for cc, ii in subLine if cc == c if i <= index <= (ii + i + 1) return true else return inStringOrComment (index - (ii + 1)), (line.substr (ii + 1))</pre></div> Match regex <div class='highlight'><pre> if c == "/" subLine = line.substr (i + 1) for cc, ii in subLine if cc == " " continue if cc == c if i <= index <= (ii + i + 1) return true else return inStringOrComment (index - (ii + 1)), (line.substr (ii + 1)) return false</pre></div> The negation: <div class='highlight'><pre>notInStringOrComment = (index, line) -> return not inStringOrComment(index, line)</pre></div> <code>getExtension()</code> returns the extension of a filename, excluding the dot. <div class='highlight'><pre>getExtension = (filename) -> i = filename.lastIndexOf '.' return if i < 0 then '' else filename.substr (i+1)</pre></div> This function makes sure that there is one and only one space before and after the operators defined in <code>TWO_SPACE_OPERATORS</code>. Before it inserts spaces, however, it makes sure that the operator in question is not part of a string. The idea behind this implementation is that, we can firstly add one space both before and after the operator, and then use <code>shortenSpaces</code> (described later) to get rid of any additional spaces. The boolean logic is much more complex than I would like. It should be refactored at some point. <div class='highlight'><pre>formatTwoSpaceOperator = (line) -> for operator in TWO_SPACE_OPERATORS newLine = '' skipNext = false for c, i in line</pre></div> Test if the operator is at i <div class='highlight'><pre> if (line.substr(i).indexOf(operator) == 0) and (notInStringOrComment i, line) and (not ((operator.length == 1) and ((line[i + 1] in TWO_SPACE_OPERATORS) or (line[i-1] in TWO_SPACE_OPERATORS)))) newLine += " #{operator} " # Insert a space before and after skipNext = true if operator.length == 2 else unless skipNext newLine += c skipNext = false line = shortenSpaces newLine return line</pre></div> This method shortens consecutive spaces into one single space. <div class='highlight'><pre>formatOneSpaceOperator = (line) -> for operator in ONE_SPACE_OPERATORS newLine = '' for c, i in line thisCharAndNextOne = line.substr(i, 2) if (line.substr(i).indexOf(operator) == 0) and (notInStringOrComment i, line) and</pre></div> One exception has to be accounted for, which is expression of the form <code>Object::property</code> <div class='highlight'><pre> (line.substr(i).indexOf('::') != 0) and (line.substr(i-1).indexOf('::') != 0) and</pre></div> Another exception: <code>if (options = arguments[i])?</code> <div class='highlight'><pre> (line.substr(i+1).indexOf('?') != 0) and</pre></div> And also “),” “).” “)[“ and “))” shouldn’t be separated by space: <div class='highlight'><pre> (thisCharAndNextOne isnt "),") and (thisCharAndNextOne isnt ")(") and (thisCharAndNextOne isnt ").") and (thisCharAndNextOne isnt ")[") and (thisCharAndNextOne isnt "))") newLine += "#{operator} " # Insert a space after else newLine += c line = shortenSpaces newLine return line</pre></div> Note that the function should not shorten indentations. <div class='highlight'><pre>shortenSpaces = (line) -> trimTrailing = (str) -> str.replace /\s\s*$/, "" prevChar = null newLine = '' for c, i in line if c == ' ' newLine += c else line = line.substring(i) break for c, i in line unless notInStringOrComment(i, line) and (c == ' ' == prevChar) newLine = newLine + c prevChar = c return trimTrailing newLine</pre></div> <h3 id="body">Body</h3> The body of this module does the following: <ol> <li>Parse command line.</li> <li>Read the files specified by the user.</li> <li>Perform formatting.</li> </ol> We loop through <code>argv._</code>, which should be a list of filenames given by the user. <div class='highlight'><pre>for filename in argv._</pre></div> Then we check if the extension is “coffee”. Literate CoffeeScript will also be supported at some point. <div class='highlight'><pre> if (getExtension filename) isnt 'coffee' console.log "#{filename} doesn't appear to be a CoffeeScript file. Skipping..." console.log "Use --force to format it anyway."</pre></div> If the extension is “coffee”, we proceed to the actual formatting. Firstly, we read the file line by line: <div class='highlight'><pre> else file = '' lazy = new Lazy(fs.createReadStream filename, encoding: 'utf8') lazy.on 'end', -> fs.writeFileSync filename, file lazy.lines .forEach (line) -> line = String(line)</pre></div> For some weird reason regarding IO, empty line is read as ‘0’. Therefore I have to check against 0. This may cause weird bugs if a line actually contains only ‘0’. <div class='highlight'><pre> if line != '0' newLine = line</pre></div> <code>newLine</code> is used to hold a processed line. <code>file</code> is used to hold the processed file. Now we add spaces before and after a binary operator, using the helper function: <div class='highlight'><pre> newLine = formatTwoSpaceOperator newLine</pre></div> Do the same for single-space operators: <div class='highlight'><pre> newLine = formatOneSpaceOperator newLine</pre></div> Shorten any consecutive spaces into a single space: <div class='highlight'><pre> newLine = shortenSpaces newLine file += newLine + '\n' else file += '\n'</pre></div> After the <code>forEach</code> completes, we have a file that is formatted line by line. However, a comprehensive formatter needs to consider the code in a block level. Specifically: <ul> <li>Indentation should be formatted according to the parameters specified by the user.</li> </ul> This haven’t been implemented yet. <h3 id="exports">Exports</h3> <h4 id="test-only">Test Only</h4> The following exports are for testing only and should be commented out in production: <div class='highlight'><pre>exports.shortenSpaces = shortenSpaces exports.formatTwoSpaceOperator = formatTwoSpaceOperator exports.notInStringOrComment = notInStringOrComment exports.formatOneSpaceOperator = formatOneSpaceOperator</pre></div> <div class="fleur">h</div> </div> </div> </body> </html>