Skip to content

Commit

Permalink
Add modules documentation (#4309)
Browse files Browse the repository at this point in the history
  • Loading branch information
GeoffreyBooth authored and lydell committed Sep 18, 2016
1 parent 7667cb2 commit a8b77fb
Show file tree
Hide file tree
Showing 6 changed files with 123 additions and 6 deletions.
3 changes: 3 additions & 0 deletions Cakefile
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,9 @@ codeFor = ->
js = js.replace /^\/\/ generated.*?\n/i, ''

cshtml = "<pre><code>#{hljs.highlight('coffeescript', cs).value}</code></pre>"
# Temporary fix until highlight.js adds support for newer CoffeeScript reserved words
if file is 'modules'
cshtml = cshtml.replace /(import|export|from|as|default) /g, '<span class="reserved">$1</span> '
jshtml = "<pre><code>#{hljs.highlight('javascript', js).value}</code></pre>"
append = if executable is yes then '' else "alert(#{executable});"
if executable and executable != yes
Expand Down
2 changes: 1 addition & 1 deletion bower.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"devDependencies": {
"uglify-js": "~2.2",
"jison": ">=0.2.0",
"highlight.js": "~8.0.0",
"highlight.js": "~9.6.0",
"underscore": "~1.5.2",
"docco": "~0.6.2"
},
Expand Down
23 changes: 23 additions & 0 deletions documentation/coffee/modules.coffee
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import 'local-file.coffee'
import 'coffee-script'

import _ from 'underscore'
import * as underscore from 'underscore'

import { now } from 'underscore'
import { now as currentTimestamp } from 'underscore'
import { first, last } from 'underscore'
import utilityBelt, { each } from 'underscore'

export default Math
export square = (x) -> x * x
export class Mathematics
least: (x, y) -> if x < y then x else y

export { sqrt }
export { sqrt as squareRoot }
export { Mathematics as default, sqrt as squareRoot }

export * from 'underscore'
export { max, min } from 'underscore'

33 changes: 29 additions & 4 deletions documentation/index.html.js
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
<a href="#comparisons">Chained Comparisons</a>
<a href="#strings">String Interpolation, Block Strings, and Block Comments</a>
<a href="#regexes">Block Regular Expressions</a>
<a href="#modules">Modules</a>
<a href="#cake">Cake, and Cakefiles</a>
<a href="#source-maps">Source Maps</a>
<a href="#scripts">"text/coffeescript" Script Tags</a>
Expand Down Expand Up @@ -467,10 +468,11 @@ Expressions
</p>
<p>
If you'd like to create top-level variables for other scripts to use,
attach them as properties on <b>window</b>, or on the <b>exports</b>
object in CommonJS. The <b>existential operator</b> (covered below), gives you a
reliable way to figure out where to add them; if you're targeting both
CommonJS and the browser: <code>exports ? this</code>
attach them as properties on <b>window</b>; attach them as properties on the
<b>exports</b> object in CommonJS; or use an <a href="#modules"><code>export</code>
statement</a>. If you’re targeting both CommonJS and the browser, the
<b>existential operator</b> (covered below), gives you a
reliable way to figure out where to add them: <code>exports ? this</code>
</p>

<p>
Expand Down Expand Up @@ -937,6 +939,29 @@ Expressions
</p>
<%= codeFor('heregexes') %>

<p>
<span id="modules" class="bookmark"></span>
<b class="header">Modules</b>
ES2015 modules are supported in CoffeeScript, with very similar <code>import</code>
and <code>export</code> syntax:
</p>
<%= codeFor('modules') %>
<p>
Note that the CoffeeScript compiler <strong>does not resolve modules</strong>; writing an
<code>import</code> or <code>export</code> statement in CoffeeScript will produce an
<code>import</code> or <code>export</code> statement in the resulting output.
It is your responsibility attach another transpiler, such as
<a href="https://github.com/google/traceur-compiler">Traceur Compiler</a>,
<a href="http://babeljs.io/">Babel</a>&nbsp;or
<a href="https://github.com/rollup/rollup">Rollup</a>, to convert this ES2015 syntax into
code that will work in your target runtimes.
</p>
<p>
Also note that any file with an <code>import</code> or <code>export</code> statement will
be output without a <a href="#lexical-scope">top-level function safety wrapper</a>;
in other words, importing or exporting modules will automatically trigger
<a href="#usage">bare</a> mode for that file. This is because per the ES2015 spec,
<code>import</code> or <code>export</code> statements must occur at the topmost scope.

<h2>
<span id="cake" class="bookmark"></span>
Expand Down
66 changes: 66 additions & 0 deletions documentation/js/modules.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
"devDependencies": {
"uglify-js": "~2.2",
"jison": ">=0.2.0",
"highlight.js": "~8.0.0",
"highlight.js": "~9.6.0",
"underscore": "~1.5.2",
"docco": "~0.7.0"
}
Expand Down

0 comments on commit a8b77fb

Please sign in to comment.