From de98e0b232509d5f40c135d540a70e415272ff85 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 3 May 2017 15:35:00 +0200 Subject: node_modules --- node_modules/uglify-js/README.md | 1001 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1001 insertions(+) create mode 100644 node_modules/uglify-js/README.md (limited to 'node_modules/uglify-js/README.md') diff --git a/node_modules/uglify-js/README.md b/node_modules/uglify-js/README.md new file mode 100644 index 000000000..d15f114ce --- /dev/null +++ b/node_modules/uglify-js/README.md @@ -0,0 +1,1001 @@ +UglifyJS 2 +========== +[![Build Status](https://travis-ci.org/mishoo/UglifyJS2.svg)](https://travis-ci.org/mishoo/UglifyJS2) + +UglifyJS is a JavaScript parser, minifier, compressor or beautifier toolkit. + +This page documents the command line utility. For +[API and internals documentation see my website](http://lisperator.net/uglifyjs/). +There's also an +[in-browser online demo](http://lisperator.net/uglifyjs/#demo) (for Firefox, +Chrome and probably Safari). + +#### Note: +- release versions of `uglify-js` only support ECMAScript 5 (ES5). If you wish to minify +ES2015+ (ES6+) code then please use the [harmony](#harmony) development branch. +- Node 7 has a known performance regression and runs `uglify-js` twice as slow. + +Install +------- + +First make sure you have installed the latest version of [node.js](http://nodejs.org/) +(You may need to restart your computer after this step). + +From NPM for use as a command line app: + + npm install uglify-js -g + +From NPM for programmatic use: + + npm install uglify-js + +From Git: + + git clone git://github.com/mishoo/UglifyJS2.git + cd UglifyJS2 + npm link . + +Usage +----- + + uglifyjs [input files] [options] + +UglifyJS2 can take multiple input files. It's recommended that you pass the +input files first, then pass the options. UglifyJS will parse input files +in sequence and apply any compression options. The files are parsed in the +same global scope, that is, a reference from a file to some +variable/function declared in another file will be matched properly. + +If you want to read from STDIN instead, pass a single dash instead of input +files. + +If you wish to pass your options before the input files, separate the two with +a double dash to prevent input files being used as option arguments: + + uglifyjs --compress --mangle -- input.js + +The available options are: + +``` + --source-map Specify an output file where to generate source + map. + --source-map-root The path to the original source to be included + in the source map. + --source-map-url The path to the source map to be added in //# + sourceMappingURL. Defaults to the value passed + with --source-map. + --source-map-include-sources Pass this flag if you want to include the + content of source files in the source map as + sourcesContent property. + --source-map-inline Write base64-encoded source map to the end of js output. + --in-source-map Input source map, useful if you're compressing + JS that was generated from some other original + code. Specify "inline" if the source map is included + inline with the sources. + --screw-ie8 Use this flag if you don't wish to support + Internet Explorer 6/7/8. + By default UglifyJS will not try to be IE-proof. + --support-ie8 Use this flag to support Internet Explorer 6/7/8. + Equivalent to setting `screw_ie8: false` in `minify()` + for `compress`, `mangle` and `output` options. + --expr Parse a single expression, rather than a + program (for parsing JSON) + -p, --prefix Skip prefix for original filenames that appear + in source maps. For example -p 3 will drop 3 + directories from file names and ensure they are + relative paths. You can also specify -p + relative, which will make UglifyJS figure out + itself the relative paths between original + sources, the source map and the output file. + -o, --output Output file (default STDOUT). + -b, --beautify Beautify output/specify output options. + -m, --mangle Mangle names/pass mangler options. + -r, --reserved Reserved names to exclude from mangling. + -c, --compress Enable compressor/pass compressor options, e.g. + `-c 'if_return=false,pure_funcs=["Math.pow","console.log"]'` + Use `-c` with no argument to enable default compression + options. + -d, --define Global definitions + -e, --enclose Embed everything in a big function, with a + configurable parameter/argument list. + --comments Preserve copyright comments in the output. By + default this works like Google Closure, keeping + JSDoc-style comments that contain "@license" or + "@preserve". You can optionally pass one of the + following arguments to this flag: + - "all" to keep all comments + - a valid JS RegExp like `/foo/` or `/^!/` to + keep only matching comments. + Note that currently not *all* comments can be + kept when compression is on, because of dead + code removal or cascading statements into + sequences. + --preamble Preamble to prepend to the output. You can use + this to insert a comment, for example for + licensing information. This will not be + parsed, but the source map will adjust for its + presence. + --stats Display operations run time on STDERR. + --acorn Use Acorn for parsing. + --spidermonkey Assume input files are SpiderMonkey AST format + (as JSON). + --self Build itself (UglifyJS2) as a library (implies + --wrap=UglifyJS --export-all) + --wrap Embed everything in a big function, making the + “exports” and “global” variables available. You + need to pass an argument to this option to + specify the name that your module will take + when included in, say, a browser. + --export-all Only used when --wrap, this tells UglifyJS to + add code to automatically export all globals. + --lint Display some scope warnings + -v, --verbose Verbose + -V, --version Print version number and exit. + --noerr Don't throw an error for unknown options in -c, + -b or -m. + --bare-returns Allow return outside of functions. Useful when + minifying CommonJS modules and Userscripts that + may be anonymous function wrapped (IIFE) by the + .user.js engine `caller`. + --keep-fnames Do not mangle/drop function names. Useful for + code relying on Function.prototype.name. + --reserved-file File containing reserved names + --reserve-domprops Make (most?) DOM properties reserved for + --mangle-props + --mangle-props Mangle property names (default `0`). Set to + `true` or `1` to mangle all property names. Set + to `unquoted` or `2` to only mangle unquoted + property names. Mode `2` also enables the + `keep_quoted_props` beautifier option to + preserve the quotes around property names and + disables the `properties` compressor option to + prevent rewriting quoted properties with dot + notation. You can override these by setting + them explicitly on the command line. + --mangle-regex Only mangle property names matching the regex + --name-cache File to hold mangled names mappings + --pure-funcs Functions that can be safely removed if their + return value is not used, e.g. + `--pure-funcs Math.floor console.info` + (requires `--compress`) +``` + +Specify `--output` (`-o`) to declare the output file. Otherwise the output +goes to STDOUT. + +## Source map options + +UglifyJS2 can generate a source map file, which is highly useful for +debugging your compressed JavaScript. To get a source map, pass +`--source-map output.js.map` (full path to the file where you want the +source map dumped). + +Additionally you might need `--source-map-root` to pass the URL where the +original files can be found. In case you are passing full paths to input +files to UglifyJS, you can use `--prefix` (`-p`) to specify the number of +directories to drop from the path prefix when declaring files in the source +map. + +For example: + + uglifyjs /home/doe/work/foo/src/js/file1.js \ + /home/doe/work/foo/src/js/file2.js \ + -o foo.min.js \ + --source-map foo.min.js.map \ + --source-map-root http://foo.com/src \ + -p 5 -c -m + +The above will compress and mangle `file1.js` and `file2.js`, will drop the +output in `foo.min.js` and the source map in `foo.min.js.map`. The source +mapping will refer to `http://foo.com/src/js/file1.js` and +`http://foo.com/src/js/file2.js` (in fact it will list `http://foo.com/src` +as the source map root, and the original files as `js/file1.js` and +`js/file2.js`). + +### Composed source map + +When you're compressing JS code that was output by a compiler such as +CoffeeScript, mapping to the JS code won't be too helpful. Instead, you'd +like to map back to the original code (i.e. CoffeeScript). UglifyJS has an +option to take an input source map. Assuming you have a mapping from +CoffeeScript → compiled JS, UglifyJS can generate a map from CoffeeScript → +compressed JS by mapping every token in the compiled JS to its original +location. + +To use this feature you need to pass `--in-source-map +/path/to/input/source.map` or `--in-source-map inline` if the source map is +included inline with the sources. Normally the input source map should also +point to the file containing the generated JS, so if that's correct you can +omit input files from the command line. + +## Mangler options + +To enable the mangler you need to pass `--mangle` (`-m`). The following +(comma-separated) options are supported: + +- `toplevel` — mangle names declared in the toplevel scope (disabled by + default). + +- `eval` — mangle names visible in scopes where `eval` or `with` are used + (disabled by default). + +When mangling is enabled but you want to prevent certain names from being +mangled, you can declare those names with `--reserved` (`-r`) — pass a +comma-separated list of names. For example: + + uglifyjs ... -m -r '$,require,exports' + +to prevent the `require`, `exports` and `$` names from being changed. + +### Mangling property names (`--mangle-props`) + +**Note:** this will probably break your code. Mangling property names is a +separate step, different from variable name mangling. Pass +`--mangle-props`. It will mangle all properties that are seen in some +object literal, or that are assigned to. For example: + +```js +var x = { + foo: 1 +}; + +x.bar = 2; +x["baz"] = 3; +x[condition ? "moo" : "boo"] = 4; +console.log(x.something()); +``` + +In the above code, `foo`, `bar`, `baz`, `moo` and `boo` will be replaced +with single characters, while `something()` will be left as is. + +In order for this to be of any use, we should avoid mangling standard JS +names. For instance, if your code would contain `x.length = 10`, then +`length` becomes a candidate for mangling and it will be mangled throughout +the code, regardless if it's being used as part of your own objects or +accessing an array's length. To avoid that, you can use `--reserved-file` +to pass a filename that should contain the names to be excluded from +mangling. This file can be used both for excluding variable names and +property names. It could look like this, for example: + +```js +{ + "vars": [ "define", "require", ... ], + "props": [ "length", "prototype", ... ] +} +``` + +`--reserved-file` can be an array of file names (either a single +comma-separated argument, or you can pass multiple `--reserved-file` +arguments) — in this case it will exclude names from all those files. + +A default exclusion file is provided in `tools/domprops.json` which should +cover most standard JS and DOM properties defined in various browsers. Pass +`--reserve-domprops` to read that in. + +You can also use a regular expression to define which property names should be +mangled. For example, `--mangle-regex="/^_/"` will only mangle property names +that start with an underscore. + +When you compress multiple files using this option, in order for them to +work together in the end we need to ensure somehow that one property gets +mangled to the same name in all of them. For this, pass `--name-cache +filename.json` and UglifyJS will maintain these mappings in a file which can +then be reused. It should be initially empty. Example: + +``` +rm -f /tmp/cache.json # start fresh +uglifyjs file1.js file2.js --mangle-props --name-cache /tmp/cache.json -o part1.js +uglifyjs file3.js file4.js --mangle-props --name-cache /tmp/cache.json -o part2.js +``` + +Now, `part1.js` and `part2.js` will be consistent with each other in terms +of mangled property names. + +Using the name cache is not necessary if you compress all your files in a +single call to UglifyJS. + +#### Mangling unquoted names (`--mangle-props=unquoted` or `--mangle-props=2`) + +Using quoted property name (`o["foo"]`) reserves the property name (`foo`) +so that it is not mangled throughout the entire script even when used in an +unquoted style (`o.foo`). Example: + +``` +$ echo 'var o={"foo":1, bar:3}; o.foo += o.bar; console.log(o.foo);' | uglifyjs --mangle-props=2 -mc +var o={"foo":1,a:3};o.foo+=o.a,console.log(o.foo); +``` + +#### Debugging property name mangling + +You can also pass `--mangle-props-debug` in order to mangle property names +without completely obscuring them. For example the property `o.foo` +would mangle to `o._$foo$_` with this option. This allows property mangling +of a large codebase while still being able to debug the code and identify +where mangling is breaking things. + +You can also pass a custom suffix using `--mangle-props-debug=XYZ`. This would then +mangle `o.foo` to `o._$foo$XYZ_`. You can change this each time you compile a +script to identify how a property got mangled. One technique is to pass a +random number on every compile to simulate mangling changing with different +inputs (e.g. as you update the input script with new properties), and to help +identify mistakes like writing mangled keys to storage. + +## Compressor options + +You need to pass `--compress` (`-c`) to enable the compressor. Optionally +you can pass a comma-separated list of options. Options are in the form +`foo=bar`, or just `foo` (the latter implies a boolean option that you want +to set `true`; it's effectively a shortcut for `foo=true`). + +- `sequences` (default: true) -- join consecutive simple statements using the + comma operator. May be set to a positive integer to specify the maximum number + of consecutive comma sequences that will be generated. If this option is set to + `true` then the default `sequences` limit is `200`. Set option to `false` or `0` + to disable. The smallest `sequences` length is `2`. A `sequences` value of `1` + is grandfathered to be equivalent to `true` and as such means `200`. On rare + occasions the default sequences limit leads to very slow compress times in which + case a value of `20` or less is recommended. + +- `properties` -- rewrite property access using the dot notation, for + example `foo["bar"] → foo.bar` + +- `dead_code` -- remove unreachable code + +- `drop_debugger` -- remove `debugger;` statements + +- `unsafe` (default: false) -- apply "unsafe" transformations (discussion below) + +- `unsafe_comps` (default: false) -- Reverse `<` and `<=` to `>` and `>=` to + allow improved compression. This might be unsafe when an at least one of two + operands is an object with computed values due the use of methods like `get`, + or `valueOf`. This could cause change in execution order after operands in the + comparison are switching. Compression only works if both `comparisons` and + `unsafe_comps` are both set to true. + +- `unsafe_math` (default: false) -- optimize numerical expressions like + `2 * x * 3` into `6 * x`, which may give imprecise floating point results. + +- `unsafe_proto` (default: false) -- optimize expressions like + `Array.prototype.slice.call(a)` into `[].slice.call(a)` + +- `conditionals` -- apply optimizations for `if`-s and conditional + expressions + +- `comparisons` -- apply certain optimizations to binary nodes, for example: + `!(a <= b) → a > b` (only when `unsafe_comps`), attempts to negate binary + nodes, e.g. `a = !b && !c && !d && !e → a=!(b||c||d||e)` etc. + +- `evaluate` -- attempt to evaluate constant expressions + +- `booleans` -- various optimizations for boolean context, for example `!!a + ? b : c → a ? b : c` + +- `loops` -- optimizations for `do`, `while` and `for` loops when we can + statically determine the condition + +- `unused` -- drop unreferenced functions and variables (simple direct variable + assignments do not count as references unless set to `"keep_assign"`) + +- `toplevel` -- drop unreferenced functions (`"funcs"`) and/or variables (`"vars"`) + in the toplevel scope (`false` by default, `true` to drop both unreferenced + functions and variables) + +- `top_retain` -- prevent specific toplevel functions and variables from `unused` + removal (can be array, comma-separated, RegExp or function. Implies `toplevel`) + +- `hoist_funs` -- hoist function declarations + +- `hoist_vars` (default: false) -- hoist `var` declarations (this is `false` + by default because it seems to increase the size of the output in general) + +- `if_return` -- optimizations for if/return and if/continue + +- `join_vars` -- join consecutive `var` statements + +- `cascade` -- small optimization for sequences, transform `x, x` into `x` + and `x = something(), x` into `x = something()` + +- `collapse_vars` -- Collapse single-use `var` and `const` definitions + when possible. + +- `reduce_vars` -- Improve optimization on variables assigned with and + used as constant values. + +- `warnings` -- display warnings when dropping unreachable code or unused + declarations etc. + +- `negate_iife` -- negate "Immediately-Called Function Expressions" + where the return value is discarded, to avoid the parens that the + code generator would insert. + +- `pure_getters` -- the default is `false`. If you pass `true` for + this, UglifyJS will assume that object property access + (e.g. `foo.bar` or `foo["bar"]`) doesn't have any side effects. + Specify `"strict"` to treat `foo.bar` as side-effect-free only when + `foo` is certain to not throw, i.e. not `null` or `undefined`. + +- `pure_funcs` -- default `null`. You can pass an array of names and + UglifyJS will assume that those functions do not produce side + effects. DANGER: will not check if the name is redefined in scope. + An example case here, for instance `var q = Math.floor(a/b)`. If + variable `q` is not used elsewhere, UglifyJS will drop it, but will + still keep the `Math.floor(a/b)`, not knowing what it does. You can + pass `pure_funcs: [ 'Math.floor' ]` to let it know that this + function won't produce any side effect, in which case the whole + statement would get discarded. The current implementation adds some + overhead (compression will be slower). + +- `drop_console` -- default `false`. Pass `true` to discard calls to + `console.*` functions. If you wish to drop a specific function call + such as `console.info` and/or retain side effects from function arguments + after dropping the function call then use `pure_funcs` instead. + +- `expression` -- default `false`. Pass `true` to preserve completion values + from terminal statements without `return`, e.g. in bookmarklets. + +- `keep_fargs` -- default `true`. Prevents the + compressor from discarding unused function arguments. You need this + for code which relies on `Function.length`. + +- `keep_fnames` -- default `false`. Pass `true` to prevent the + compressor from discarding function names. Useful for code relying on + `Function.prototype.name`. See also: the `keep_fnames` [mangle option](#mangle). + +- `passes` -- default `1`. Number of times to run compress. Use an + integer argument larger than 1 to further reduce code size in some cases. + Note: raising the number of passes will increase uglify compress time. + +- `keep_infinity` -- default `false`. Pass `true` to prevent `Infinity` from + being compressed into `1/0`, which may cause performance issues on Chrome. + +### The `unsafe` option + +It enables some transformations that *might* break code logic in certain +contrived cases, but should be fine for most code. You might want to try it +on your own code, it should reduce the minified size. Here's what happens +when this flag is on: + +- `new Array(1, 2, 3)` or `Array(1, 2, 3)` → `[ 1, 2, 3 ]` +- `new Object()` → `{}` +- `String(exp)` or `exp.toString()` → `"" + exp` +- `new Object/RegExp/Function/Error/Array (...)` → we discard the `new` +- `typeof foo == "undefined"` → `foo === void 0` +- `void 0` → `undefined` (if there is a variable named "undefined" in + scope; we do it because the variable name will be mangled, typically + reduced to a single character) + +### Conditional compilation + +You can use the `--define` (`-d`) switch in order to declare global +variables that UglifyJS will assume to be constants (unless defined in +scope). For example if you pass `--define DEBUG=false` then, coupled with +dead code removal UglifyJS will discard the following from the output: +```javascript +if (DEBUG) { + console.log("debug stuff"); +} +``` + +You can specify nested constants in the form of `--define env.DEBUG=false`. + +UglifyJS will warn about the condition being always false and about dropping +unreachable code; for now there is no option to turn off only this specific +warning, you can pass `warnings=false` to turn off *all* warnings. + +Another way of doing that is to declare your globals as constants in a +separate file and include it into the build. For example you can have a +`build/defines.js` file with the following: +```javascript +const DEBUG = false; +const PRODUCTION = true; +// etc. +``` + +and build your code like this: + + uglifyjs build/defines.js js/foo.js js/bar.js... -c + +UglifyJS will notice the constants and, since they cannot be altered, it +will evaluate references to them to the value itself and drop unreachable +code as usual. The build will contain the `const` declarations if you use +them. If you are targeting < ES6 environments which does not support `const`, +using `var` with `reduce_vars` (enabled by default) should suffice. + + + +#### Conditional compilation, API +You can also use conditional compilation via the programmatic API. With the difference that the +property name is `global_defs` and is a compressor property: + +```js +uglifyJS.minify([ "input.js"], { + compress: { + dead_code: true, + global_defs: { + DEBUG: false + } + } +}); +``` + +## Beautifier options + +The code generator tries to output shortest code possible by default. In +case you want beautified output, pass `--beautify` (`-b`). Optionally you +can pass additional arguments that control the code output: + +- `beautify` (default `true`) -- whether to actually beautify the output. + Passing `-b` will set this to true, but you might need to pass `-b` even + when you want to generate minified code, in order to specify additional + arguments, so you can use `-b beautify=false` to override it. +- `indent-level` (default 4) +- `indent-start` (default 0) -- prefix all lines by that many spaces +- `quote-keys` (default `false`) -- pass `true` to quote all keys in literal + objects +- `space-colon` (default `true`) -- insert a space after the colon signs +- `ascii-only` (default `false`) -- escape Unicode characters in strings and + regexps (affects directives with non-ascii characters becoming invalid) +- `inline-script` (default `false`) -- escape the slash in occurrences of + `