1
0
Fork 0
mirror of https://github.com/jashkenas/coffeescript.git synced 2022-11-09 12:23:24 -05:00
jashkenas--coffeescript/documentation/site/body.html

207 lines
6.6 KiB
HTML
Raw Normal View History

<%= include('navbar.html') %>
2016-12-16 02:18:40 -05:00
2016-12-27 21:35:43 -05:00
<%= include('try.html') %>
<div class="container-fluid" id="top">
<div class="row flex-nowrap">
<nav class="sidebar col-lg-3 bg-ribbed-light">
<%= include('sidebar.html') %>
</nav>
<main class="main col-lg-9 ml-auto">
<header class="title-logo d-none d-lg-block">
<%= include('logo.svg') %>
2016-12-16 02:58:59 -05:00
</header>
<section id="overview">
<%= htmlFor('introduction') %>
<%= htmlFor('overview') %>
</section>
2016-12-19 02:25:01 -05:00
<section id="coffeescript-2">
<%= htmlFor('coffeescript_2') %>
2017-09-16 12:32:48 -04:00
<section id="whats-new-in-coffeescript-2">
<%= htmlFor('whats_new_in_coffeescript_2') %>
</section>
<section id="compatibility">
<%= htmlFor('compatibility') %>
</section>
</section>
<section id="installation">
<%= htmlFor('installation') %>
</section>
<section id="usage">
<%= htmlFor('usage') %>
[CS2] Comments (#4572) * Make `addLocationDataFn` more DRY * Style fixes * Provide access to full parser inside our custom function running in parser.js; rename the function to lay the groundwork for adding data aside from location data * Fix style. * Fix style. * Label test comments * Update grammar to remove comment tokens; update DSL to call new helper function that preserves comments through parsing * New implementation of compiling block comments: the lexer pulls them out of the token stream, attaching them as a property to a token; the rewriter moves the attachment around so it lives on a token that is destined to make it through to compilation (and in a good placement); and the nodes render the block comment. All tests but one pass (commented out). * If a comment follows a class declaration, move the comment inside the class body * Style * Improve indentation of multiline comments * Fix indentation for block comments, at least in the cases covered by the one failing test * Don’t reverse the order of unshifted comments * Simplify rewriter’s handling of comments, generalizing the special case * Expand the list of tokens we need to avoid for passing comments through the parser; get some literal tokens to have nodes created for them so that the comments pass through * Improve comments; fix multiline flag * Prepare HereComments for processing line comments * Line comments, first draft: the tests pass, but the line comments aren’t indented and sometimes trail previous lines when they shouldn’t; updated compiler output in following commit * Updated compiler, now with line comments * `process` doesn’t exist in the browser, so we should check for its existence first * Update parser output * Test that proves #4290 is fixed * Indent line comments, first pass * Compiled output with indented line comments * Comments that start a new line shouldn’t trail; don’t skip comments attached to generated tokens; stop looking for indentation once we hit a newline * Revised output * Cleanup * Split “multiline” line comment tokens, shifting them forward or back as appropriate * Fix comments in module specifiers * Abstract attaching comments to a node * Line comments in interpolated strings * Line comments can’t be multiline anymore * Improve handling of blank lines and indentation of following comments that start a new line (i.e. don’t trail) * Make comments compilation more object-oriented * Remove lots of dead code that we don’t need anymore because a comment is never a node, only a fragment * Improve eqJS helper * Fix #4290 definitively, with improved output for arrays with interspersed block comments * Add support for line comments output interspersed within arrays * Fix mistake, don’t lose the variable we’re working on * Remove redundant replacements * Check for indentation only from the start of the string * Indentations in generated JS are always multiples of two spaces (never tabs) so just look for 2+ spaces * Update package versions; run Babel twice, once for each preset, temporarily until a Babili bug is fixed that prevents it from running with the env preset * Don’t rely on `fragment.type`, which can break when the compiler is minified * Updated generated docs and browser compiler * Output block comments after function arguments * Comments appear above scope `var` declarations; better tracking of generated `JS` tokens created only to shepherd comments through to the output * Create new FuncGlyph node, to hold comments we want to output near the function parameters * Block comments between `)` and `->`/`=>` get output between `)` and `{`. * Fix indentation of comments that are the first line inside a bare mode block * Updated output * Full Flow example * Updated browser compiler * Abstract and organize comment fragment generation code; store more properties on the comment fragment objects; make `throw` behave like `return` * Abstract token insertion code * Add missing locationData to STRING_START token, giving it the locationData of the overall StringWithInterpolations token so that comments attached to STRING_START end up on the StringWithInterpolations node * Allow `SUPER` tokens to carry comments * Rescue comments from `Existence` nodes and `If` nodes’ conditions * Rescue comments after `\` line continuation tokens * Updated compiled output * Updated browser compiler * Output block comments in the same `compileFragments` method as line comments, except for inline block comments * Comments before splice * Updated browser compiler * Track compiledComments as a property of Base, to ensure that it’s not a global variable * Docs: split up the Usage section * Docs for type annotations via Flow; updated docs output * Update regular comments documentation * Updated browser compiler * Comments before soak * Comments before static methods, and probably before `@variable =` (this) assignments generally * Comments before ‘if exists?’, refactor comment before ‘if this.var’ to be more precise, improve helper methods * Comments before a method that contains ‘super()’ should output above the method property, not above the ‘super.method()’ call * Fix missing comments before `if not` (i.e. before a UNARY token) * Fix comments before ‘for’; add test for comment before assignment if (fixed in earlier commit) * Comments within heregexes * Updated browser compiler * Update description to reflect what’s now happening in compileCommentFragments * Preserve blank lines between line comments; output “whitespace-only” line comments as blank lines, rather than `//` following by whitespace * Better future-proof comments tests * Comments before object destructuring; abstract method for setting comments aside before compilation * Handle more cases of comments before or after `for` loop declaration lines * Fix indentation of comments preceding `for` loops * Fix comment before splat function parameter * Catch another RegexWithInterpolations comment edge case * Updated browser compiler * Change heregex example to one that’s more readable; update output * Remove a few last references to the defunct HERECOMMENT token * Abstract location hash creation into a function * Improved clarity per code review notes * Updated browser compiler
2017-08-02 22:34:34 -04:00
<section id="cli">
<%= htmlFor('command_line_interface') %>
</section>
<section id="nodejs-usage">
<%= htmlFor('nodejs_usage') %>
</section>
<section id="transpilation">
<%= htmlFor('transpilation') %>
</section>
</section>
<section id="language">
<%= htmlFor('language') %>
<section id="functions">
<%= htmlFor('functions') %>
</section>
<section id="strings">
<%= htmlFor('strings') %>
</section>
<section id="objects-and-arrays">
<%= htmlFor('objects_and_arrays') %>
</section>
<section id="comments">
<%= htmlFor('comments') %>
</section>
<section id="lexical-scope">
<%= htmlFor('lexical_scope') %>
</section>
<section id="conditionals">
<%= htmlFor('conditionals') %>
</section>
<section id="splats">
<%= htmlFor('splats') %>
</section>
<section id="loops">
<%= htmlFor('loops') %>
</section>
<section id="slices">
<%= htmlFor('slices') %>
</section>
<section id="expressions">
<%= htmlFor('expressions') %>
</section>
<section id="operators">
<%= htmlFor('operators') %>
</section>
<section id="existential-operator">
<%= htmlFor('existential_operator') %>
</section>
<section id="chaining">
<%= htmlFor('chaining') %>
</section>
<section id="destructuring">
<%= htmlFor('destructuring') %>
</section>
<section id="fat-arrow">
<%= htmlFor('fat_arrow') %>
</section>
<section id="generators">
<%= htmlFor('generators') %>
</section>
<section id="async-functions">
<%= htmlFor('async_functions') %>
</section>
<section id="classes">
<%= htmlFor('classes') %>
</section>
<section id="prototypal-inheritance">
<%= htmlFor('prototypal_inheritance') %>
</section>
<section id="switch">
<%= htmlFor('switch') %>
</section>
<section id="try">
<%= htmlFor('try') %>
</section>
<section id="comparisons">
<%= htmlFor('comparisons') %>
</section>
<section id="regexes">
<%= htmlFor('heregexes') %>
</section>
<section id="tagged-template-literals">
<%= htmlFor('tagged_template_literals') %>
</section>
<section id="modules">
<%= htmlFor('modules') %>
</section>
<section id="embedded">
<%= htmlFor('embedded') %>
</section>
<section id="jsx">
<%= htmlFor('jsx') %>
</section>
</section>
[CS2] Comments (#4572) * Make `addLocationDataFn` more DRY * Style fixes * Provide access to full parser inside our custom function running in parser.js; rename the function to lay the groundwork for adding data aside from location data * Fix style. * Fix style. * Label test comments * Update grammar to remove comment tokens; update DSL to call new helper function that preserves comments through parsing * New implementation of compiling block comments: the lexer pulls them out of the token stream, attaching them as a property to a token; the rewriter moves the attachment around so it lives on a token that is destined to make it through to compilation (and in a good placement); and the nodes render the block comment. All tests but one pass (commented out). * If a comment follows a class declaration, move the comment inside the class body * Style * Improve indentation of multiline comments * Fix indentation for block comments, at least in the cases covered by the one failing test * Don’t reverse the order of unshifted comments * Simplify rewriter’s handling of comments, generalizing the special case * Expand the list of tokens we need to avoid for passing comments through the parser; get some literal tokens to have nodes created for them so that the comments pass through * Improve comments; fix multiline flag * Prepare HereComments for processing line comments * Line comments, first draft: the tests pass, but the line comments aren’t indented and sometimes trail previous lines when they shouldn’t; updated compiler output in following commit * Updated compiler, now with line comments * `process` doesn’t exist in the browser, so we should check for its existence first * Update parser output * Test that proves #4290 is fixed * Indent line comments, first pass * Compiled output with indented line comments * Comments that start a new line shouldn’t trail; don’t skip comments attached to generated tokens; stop looking for indentation once we hit a newline * Revised output * Cleanup * Split “multiline” line comment tokens, shifting them forward or back as appropriate * Fix comments in module specifiers * Abstract attaching comments to a node * Line comments in interpolated strings * Line comments can’t be multiline anymore * Improve handling of blank lines and indentation of following comments that start a new line (i.e. don’t trail) * Make comments compilation more object-oriented * Remove lots of dead code that we don’t need anymore because a comment is never a node, only a fragment * Improve eqJS helper * Fix #4290 definitively, with improved output for arrays with interspersed block comments * Add support for line comments output interspersed within arrays * Fix mistake, don’t lose the variable we’re working on * Remove redundant replacements * Check for indentation only from the start of the string * Indentations in generated JS are always multiples of two spaces (never tabs) so just look for 2+ spaces * Update package versions; run Babel twice, once for each preset, temporarily until a Babili bug is fixed that prevents it from running with the env preset * Don’t rely on `fragment.type`, which can break when the compiler is minified * Updated generated docs and browser compiler * Output block comments after function arguments * Comments appear above scope `var` declarations; better tracking of generated `JS` tokens created only to shepherd comments through to the output * Create new FuncGlyph node, to hold comments we want to output near the function parameters * Block comments between `)` and `->`/`=>` get output between `)` and `{`. * Fix indentation of comments that are the first line inside a bare mode block * Updated output * Full Flow example * Updated browser compiler * Abstract and organize comment fragment generation code; store more properties on the comment fragment objects; make `throw` behave like `return` * Abstract token insertion code * Add missing locationData to STRING_START token, giving it the locationData of the overall StringWithInterpolations token so that comments attached to STRING_START end up on the StringWithInterpolations node * Allow `SUPER` tokens to carry comments * Rescue comments from `Existence` nodes and `If` nodes’ conditions * Rescue comments after `\` line continuation tokens * Updated compiled output * Updated browser compiler * Output block comments in the same `compileFragments` method as line comments, except for inline block comments * Comments before splice * Updated browser compiler * Track compiledComments as a property of Base, to ensure that it’s not a global variable * Docs: split up the Usage section * Docs for type annotations via Flow; updated docs output * Update regular comments documentation * Updated browser compiler * Comments before soak * Comments before static methods, and probably before `@variable =` (this) assignments generally * Comments before ‘if exists?’, refactor comment before ‘if this.var’ to be more precise, improve helper methods * Comments before a method that contains ‘super()’ should output above the method property, not above the ‘super.method()’ call * Fix missing comments before `if not` (i.e. before a UNARY token) * Fix comments before ‘for’; add test for comment before assignment if (fixed in earlier commit) * Comments within heregexes * Updated browser compiler * Update description to reflect what’s now happening in compileCommentFragments * Preserve blank lines between line comments; output “whitespace-only” line comments as blank lines, rather than `//` following by whitespace * Better future-proof comments tests * Comments before object destructuring; abstract method for setting comments aside before compilation * Handle more cases of comments before or after `for` loop declaration lines * Fix indentation of comments preceding `for` loops * Fix comment before splat function parameter * Catch another RegexWithInterpolations comment edge case * Updated browser compiler * Change heregex example to one that’s more readable; update output * Remove a few last references to the defunct HERECOMMENT token * Abstract location hash creation into a function * Improved clarity per code review notes * Updated browser compiler
2017-08-02 22:34:34 -04:00
<section id="type-annotations">
<%= htmlFor('type_annotations') %>
</section>
<section id="literate">
<%= htmlFor('literate') %>
</section>
<section id="source-maps">
<%= htmlFor('source_maps') %>
</section>
<section id="cake">
<%= htmlFor('cake') %>
</section>
<section id="scripts">
<%= htmlFor('scripts') %>
</section>
<section id="resources">
<%= htmlFor('resources') %>
<section id="books">
<%= htmlFor('books') %>
</section>
<section id="screencasts">
<%= htmlFor('screencasts') %>
</section>
<section id="examples">
<%= htmlFor('examples') %>
</section>
<section id="chat">
<%= htmlFor('chat') %>
</section>
<section id="annotated-source">
2016-12-19 02:24:43 -05:00
<%= htmlFor('annotated_source') %>
</section>
<section id="contributing">
<%= htmlFor('contributing') %>
</section>
</section>
<section id="unsupported">
<%= htmlFor('unsupported') %>
<section id="unsupported-let-const">
<%= htmlFor('unsupported_let_const') %>
</section>
<section id="unsupported-named-functions">
<%= htmlFor('unsupported_named_functions') %>
</section>
<section id="unsupported-get-set">
<%= htmlFor('unsupported_get_set') %>
</section>
</section>
<section id="breaking-changes">
<%= htmlFor('breaking_changes') %>
2.0.0-beta3 (#4594) * Don’t confuse the syntax highlighter * Comment Assign::compilePatternMatch a bit * Assignment expressions in conditionals are a bad practice * Rename `wrapInBraces` to `wrapInParentheses`, to set the stage for future `wrapInBraces` that uses `{` and `wrapInBrackets` that uses `[` * Correct comment * object destructuring * Allow custom position of the rest element. * Output simple array destructuring assignments to ES2015 * Output simple object destructured assignments to ES2015 * Compile shorthand object properties to ES2015 shorthand properties This dramatically improves the appearance of destructured imports. * Don’t confuse the syntax highlighter * Comment Assign::compilePatternMatch a bit * Assignment expressions in conditionals are a bad practice * Rename `wrapInBraces` to `wrapInParentheses`, to set the stage for future `wrapInBraces` that uses `{` and `wrapInBrackets` that uses `[` * object destructuring * Allow custom position of the rest element. * rest element in object destructuring * rest element in object destructuring * fix string interpolation * merging * fixing splats in object literal * Rest element in parameter destructuring * merging with CS2 * merged with CS2 * Add support for the object spread initializer. https://github.com/tc39/proposal-object-rest-spread/blob/master/Spread.md * Fix misspellings, trailing whitespace, other minor details * merging with beta2 * refactor object spread properties * small fix * - Fixed object spread function parameters. - Clean up "Assign" and moved all logic for object rest properties in single method (compileObjectDestruct). - Add helper function "objectWithoutKeys" to the "UTILITIES" for use with object rest properties, e.g. {a, b, r...} = obj => {a, b} = obj, r = objectWithoutKeys(...) - Clean up "Obj" and moved all logic for object spread properties in single method (compileSpread). - Clean up "Code". - Add method "hasSplat" to "Obj" and "Value" for checking if Obj contains the splat. - Enable placing spread syntax triple dots on either right or left, per #85 (https://github.com/coffeescript6/discuss/issues/85) * Fixed typos * Remove unused code * Removed dots (e.g. splat) on the left side from the grammar * Initial release for deep spread properties, e.g. obj2 = {obj.b..., a: 1} or {obj[b][c]..., d: 7} Tests need to be prepared! * 1. Object literal spread properties Object literals: - obj = { {b:{c:{d:1}}}..., a:1 } Parenthetical: - obj = { ( body ), a:1 } - obj = { ( body )..., a:1 } Invocation: - obj = { ( (args) -> ... )(params), a:1 } - obj = { ( (args) -> ... )(params)..., a:1 } - obj = { foo(), a:1 } - obj = { foo()..., a:1 } 2. Refactor, cleanup & other optimizations. * Merged with 2.0 * Cleanup * Some more cleanup. * Fixed error with freeVariable and object destructuring. * Fixed errors with object spread properties. * Improvements, fixed errors. * Minor improvement. * Minor improvements. * Typo. * Remove unnecessary whitespace. * Remove unnecessary whitespace. * Changed few "assertErrorFormat" tests since parentheses are now allowed in the Obj. * Whitespace cleanup * Comments cleanup * fix destructured obj param declarations * refine fix; add test * Refactor function args ({a, b...}) * Additional tests for object destructuring in function argument. * Minor improvement for object destructuring variable declaration. * refactor function args ({a, b...}) and ({a, b...} = {}); Obj And Param cleanup * fix comment * Fix object destructuring variable declaration. * more tests with default values * fix typo * Fixed default values in object destructuring. * small fix * Babel’s tests for object rest spread * Style: spaces after colons in object declarations * Cleanup comments * Simplify Babel tests * Fix comments * Fix destructuring with splats in multiple objects * Add test for default values in detsructuring assignment with splats * Handle default values when assigning to object splats * Rewrite traverseRest to fix handling of dynamic keys * Fix double parens around destructuring with splats * Update compileObjectDestruct comments * Improve formatting of top-level destructures with splats and tidy parens * Added a bigger destructuring-with-defaults test and fixed a bug * Refactor destructuring grammar to allow additional forms * Add a missing case to ObjSpreadExpr * These tests shouldn’t run in the browser * Fix test.html * Fix docs scroll position getting screwed up by CodeMirror initialization * Breaking change documentation about => (fixes #4593) * Spread/rest syntax documentation * Documentation about bound class methods * 2.0.0-beta3 changelog * Add note about ‘lib’ * Fix accidentally converting this to tabs * Bump version to 2.0.0-beta3 * Update annotated source and test.html
2017-06-30 12:58:05 -04:00
<section id="breaking-change-fat-arrow">
<%= htmlFor('breaking_change_fat_arrow') %>
</section>
<section id="breaking-changes-default-values">
<%= htmlFor('breaking_changes_default_values') %>
</section>
<section id="breaking-changes-bound-generator-functions">
<%= htmlFor('breaking_changes_bound_generator_functions') %>
</section>
<section id="breaking-changes-classes">
<%= htmlFor('breaking_changes_classes') %>
</section>
<section id="breaking-changes-super-extends">
<%= htmlFor('breaking_changes_super_extends') %>
</section>
<section id="breaking-changes-jsx-and-the-less-than-and-greater-than-operators">
<%= htmlFor('breaking_changes_jsx_and_the_less_than_and_greater_than_operators') %>
</section>
<section id="breaking-changes-literate-coffeescript">
<%= htmlFor('breaking_changes_literate_coffeescript') %>
</section>
[CS2] Add #! support for executable scripts on Linux. (#3946) * Add #! support for executable scripts on Linux. Pass arguments to executable script unchanged if using "#!/usr/bin/env coffee". (Previously, "./test.coffee -abck" would be turned into "-a -b -c -k", for example.) Fixes #1752. * refactor option parsing clean up parsing code and in the process fix oustanding bug where coffeescript modified arguments meant for an executable script * address comments * intermediate save * add note saying where OptionParser is used in coffee command * add some more work * fix flatten functions * refactor tests * make argument processing less confusing * add basic test * remove unused file * compilation now hangs * remove unnecessary changes * add tests!!! * add/fix some tests * clarify a test * fix helpers * fix opt parsing * fix infinite loop * make rule building easier to read * add tests for flag overlap * revamp argument parsing again and add more thorough testing * add tests, comment, clean unused method * address review comments * add test for direct invocation of shebang scripts * move shebang parsing test to separate file and check for browser * remove TODO * example backwards compatible warnings * add correct tests for warning 1 * add tests for warnings * commit output js libs and update docs * respond to review comments also add tests for help text * respond to review comments * fix example output * Rewrite argument parsing documentation to be more concise; add it to sidebar and body; add new output * Don’t mention deprecated syntax; clean up variable names
2017-07-19 19:25:06 -04:00
<section id="breaking-changes-argument-parsing-and-shebang-lines">
<%= htmlFor('breaking_changes_argument_parsing_and_shebang_lines') %>
</section>
</section>
<section id="changelog">
<%= htmlFor('changelog') %>
</section>
</main>
</div>
</div>