diff options
Diffstat (limited to 'node_modules/uglify-js/README.md')
| -rw-r--r-- | node_modules/uglify-js/README.md | 284 |
1 files changed, 163 insertions, 121 deletions
diff --git a/node_modules/uglify-js/README.md b/node_modules/uglify-js/README.md index 6bfede087..8a34f6e49 100644 --- a/node_modules/uglify-js/README.md +++ b/node_modules/uglify-js/README.md @@ -153,10 +153,10 @@ Additional options: - `--source-map "filename='<NAME>'"` to specify the name of the source map. - `--source-map "root='<URL>'"` to pass the URL where the original files can be found. - Otherwise UglifyJS assumes HTTP `X-SourceMap` is being used and will omit the - `//# sourceMappingURL=` directive. - `--source-map "url='<URL>'"` to specify the URL where the source map can be found. + Otherwise UglifyJS assumes HTTP `X-SourceMap` is being used and will omit the + `//# sourceMappingURL=` directive. For example: @@ -203,11 +203,9 @@ Example: To enable the mangler you need to pass `--mangle` (`-m`). The following (comma-separated) options are supported: -- `toplevel` — mangle names declared in the top level scope (disabled by - default). +- `toplevel` (default `false`) -- mangle names declared in the top level scope. -- `eval` — mangle names visible in scopes where `eval` or `with` are used - (disabled by default). +- `eval` (default `false`) -- mangle names visible in scopes where `eval` or `with` are used. When mangling is enabled but you want to prevent certain names from being mangled, you can declare those names with `--mangle reserved` — pass a @@ -223,7 +221,7 @@ to prevent the `require`, `exports` and `$` names from being changed. is a separate step, different from variable name mangling. Pass `--mangle-props` to enable it. It will mangle all properties in the input code with the exception of built in DOM properties and properties -in core javascript classes. For example: +in core JavaScript classes. For example: ```javascript // example.js @@ -238,7 +236,7 @@ x.bar_ = 2; x["baz_"] = 3; console.log(x.calc()); ``` -Mangle all properties (except for javascript `builtins`): +Mangle all properties (except for JavaScript `builtins`): ```bash $ uglifyjs example.js -c -m --mangle-props ``` @@ -510,11 +508,13 @@ if (result.error) throw result.error; - `ie8` (default `false`) - set to `true` to support IE8. +- `keep_fnames` (default: `false`) - pass `true` to prevent discarding or mangling + of function names. Useful for code relying on `Function.prototype.name`. + ## Minify options structure ```javascript { - warnings: false, parse: { // parse options }, @@ -537,6 +537,7 @@ if (result.error) throw result.error; nameCache: null, // or specify a name cache object toplevel: false, ie8: false, + warnings: false, } ``` @@ -590,111 +591,87 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u ## Parse options - `bare_returns` (default `false`) -- support top level `return` statements + - `html5_comments` (default `true`) + - `shebang` (default `true`) -- support `#!command` as the first line ## Compress options -- `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_Func` (default: false) -- compress and mangle `Function(args, code)` - when both `args` and `code` are string literals. +- `booleans` (default: `true`) -- various optimizations for boolean context, + for example `!!a ? b : c → a ? b : c` -- `unsafe_math` (default: false) -- optimize numerical expressions like - `2 * x * 3` into `6 * x`, which may give imprecise floating point results. +- `cascade` (default: `true`) -- small optimization for sequences, transform + `x, x` into `x` and `x = something(), x` into `x = something()` -- `unsafe_proto` (default: false) -- optimize expressions like - `Array.prototype.slice.call(a)` into `[].slice.call(a)` +- `collapse_vars` (default: `true`) -- Collapse single-use non-constant variables, + side effects permitting. -- `unsafe_regexp` (default: false) -- enable substitutions of variables with - `RegExp` values the same way as if they are constants. +- `comparisons` (default: `true`) -- apply certain optimizations to binary nodes, + e.g. `!(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. -- `conditionals` -- apply optimizations for `if`-s and conditional +- `conditionals` (default: `true`) -- 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 +- `dead_code` (default: `true`) -- remove unreachable code -- `booleans` -- various optimizations for boolean context, for example `!!a - ? b : c → a ? b : c` +- `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. -- `typeofs` -- default `true`. Transforms `typeof foo == "undefined"` into - `foo === void 0`. Note: recommend to set this value to `false` for IE10 and - earlier versions due to known issues. +- `drop_debugger` (default: `true`) -- remove `debugger;` statements -- `loops` -- optimizations for `do`, `while` and `for` loops when we can - statically determine the condition +- `evaluate` (default: `true`) -- attempt to evaluate constant expressions -- `unused` -- drop unreferenced functions and variables (simple direct variable - assignments do not count as references unless set to `"keep_assign"`) +- `expression` (default: `false`) -- Pass `true` to preserve completion values + from terminal statements without `return`, e.g. in bookmarklets. -- `toplevel` -- drop unreferenced functions (`"funcs"`) and/or variables (`"vars"`) - in the top level scope (`false` by default, `true` to drop both unreferenced - functions and variables) +- `global_defs` (default: `{}`) -- see [conditional compilation](#conditional-compilation) -- `top_retain` -- prevent specific toplevel functions and variables from `unused` - removal (can be array, comma-separated, RegExp or function. Implies `toplevel`) +- `hoist_funs` (default: `true`) -- hoist function declarations -- `hoist_funs` -- hoist function declarations +- `hoist_props` (default: `true`) -- hoist properties from constant object and + array literals into regular variables subject to a set of constraints. For example: + `var o={p:1, q:2}; f(o.p, o.q);` is converted to `f(1, 2);`. Note: `hoist_props` + works best with `mangle` enabled, the `compress` option `passes` set to `2` or higher, + and the `compress` option `toplevel` enabled. -- `hoist_vars` (default: false) -- hoist `var` declarations (this is `false` +- `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 +- `if_return` (default: `true`) -- optimizations for if/return and if/continue -- `inline` -- embed simple functions +- `inline` (default: `true`) -- embed simple functions -- `join_vars` -- join consecutive `var` statements +- `join_vars` (default: `true`) -- join consecutive `var` statements -- `cascade` -- small optimization for sequences, transform `x, x` into `x` - and `x = something(), x` into `x = something()` +- `keep_fargs` (default: `true`) -- Prevents the compressor from discarding unused + function arguments. You need this for code which relies on `Function.length`. -- `collapse_vars` -- Collapse single-use non-constant variables - side - effects permitting. +- `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). -- `reduce_vars` -- Improve optimization on variables assigned with and - used as constant values. +- `keep_infinity` (default: `false`) -- Pass `true` to prevent `Infinity` from + being compressed into `1/0`, which may cause performance issues on Chrome. -- `warnings` -- display warnings when dropping unreachable code or unused - declarations etc. +- `loops` (default: `true`) -- optimizations for `do`, `while` and `for` loops + when we can statically determine the condition. -- `negate_iife` -- negate "Immediately-Called Function Expressions" +- `negate_iife` (default: `true`) -- 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`. +- `passes` (default: `1`) -- The maximum number of times to run compress. + In some cases more than one pass leads to further compressed code. Keep in + mind more passes will take more time. + +- `properties` (default: `true`) -- rewrite property access using the dot notation, for + example `foo["bar"] → foo.bar` -- `pure_funcs` -- default `null`. You can pass an array of names and +- `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 @@ -705,48 +682,90 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u 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. +- `pure_getters` (default: `"strict"`) -- 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`. -- `keep_fargs` -- default `true`. Prevents the - compressor from discarding unused function arguments. You need this - for code which relies on `Function.length`. +- `reduce_funcs` (default: `true`) -- Allows single-use functions to be + inlined as function expressions when permissible allowing further + optimization. Enabled by default. Option depends on `reduce_vars` + being enabled. Some code runs faster in the Chrome V8 engine if this + option is disabled. Does not negatively impact other major browsers. -- `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`. The maximum number of times to run compress. - In some cases more than one pass leads to further compressed code. Keep in - mind more passes will take more time. +- `reduce_vars` (default: `true`) -- Improve optimization on variables assigned with and + used as constant values. -- `keep_infinity` -- default `false`. Pass `true` to prevent `Infinity` from - being compressed into `1/0`, which may cause performance issues on Chrome. +- `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. -- `side_effects` -- default `true`. Pass `false` to disable potentially dropping +- `side_effects` (default: `true`) -- Pass `false` to disable potentially dropping functions marked as "pure". A function call is marked as "pure" if a comment annotation `/*@__PURE__*/` or `/*#__PURE__*/` immediately precedes the call. For example: `/*@__PURE__*/foo();` -## Mangle options +- `switches` (default: `true`) -- de-duplicate and remove unreachable `switch` branches -- `reserved` (default `[]`). Pass an array of identifiers that should be - excluded from mangling. Example: `["foo", "bar"]`. +- `toplevel` (default: `false`) -- drop unreferenced functions (`"funcs"`) and/or + variables (`"vars"`) in the top level scope (`false` by default, `true` to drop + both unreferenced functions and variables) -- `toplevel` (default `false`). Pass `true` to mangle names declared in the - top level scope. +- `top_retain` (default: `null`) -- prevent specific toplevel functions and + variables from `unused` removal (can be array, comma-separated, RegExp or + function. Implies `toplevel`) + +- `typeofs` (default: `true`) -- Transforms `typeof foo == "undefined"` into + `foo === void 0`. Note: recommend to set this value to `false` for IE10 and + earlier versions due to known issues. + +- `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. -- `keep_fnames` (default `false`). Pass `true` to not mangle function names. +- `unsafe_Func` (default: `false`) -- compress and mangle `Function(args, code)` + when both `args` and `code` are string literals. + +- `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)` + +- `unsafe_regexp` (default: `false`) -- enable substitutions of variables with + `RegExp` values the same way as if they are constants. + +- `unused` (default: `true`) -- drop unreferenced functions and variables (simple + direct variable assignments do not count as references unless set to `"keep_assign"`) + +- `warnings` (default: `false`) -- display warnings when dropping unreachable + code or unused declarations etc. + +## Mangle options + +- `eval` (default `false`) -- Pass `true` to mangle names visible in scopes + where `eval` or `with` are used. + +- `keep_fnames` (default `false`) -- Pass `true` to not mangle function names. Useful for code relying on `Function.prototype.name`. See also: the `keep_fnames` [compress option](#compress-options). -- `eval` (default `false`). Pass `true` to mangle names visible in scopes - where `eval` or `with` are used. +- `reserved` (default `[]`) -- Pass an array of identifiers that should be + excluded from mangling. Example: `["foo", "bar"]`. + +- `toplevel` (default `false`) -- Pass `true` to mangle names declared in the + top level scope. Examples: @@ -772,16 +791,20 @@ UglifyJS.minify(code, { mangle: { toplevel: true } }).code; ### Mangle properties options -- `reserved` (default: `[]`) -- Do not mangle property names listed in the - `reserved` array. -- `regex` (default: `null`) -— Pass a RegExp literal to only mangle property - names matching the regular expression. -- `keep_quoted` (default: `false`) -— Only mangle unquoted property names. -- `debug` (default: `false`) -— Mangle names with the original name still present. - Pass an empty string `""` to enable, or a non-empty string to set the debug suffix. - `builtins` (default: `false`) -- Use `true` to allow the mangling of builtin DOM properties. Not recommended to override this setting. +- `debug` (default: `false`) -— Mangle names with the original name still present. + Pass an empty string `""` to enable, or a non-empty string to set the debug suffix. + +- `keep_quoted` (default: `false`) -— Only mangle unquoted property names. + +- `regex` (default: `null`) -— Pass a RegExp literal to only mangle property + names matching the regular expression. + +- `reserved` (default: `[]`) -- Do not mangle property names listed in the + `reserved` array. + ## Output options The code generator tries to output shortest code possible by default. In @@ -790,31 +813,43 @@ can pass additional arguments that control the code output: - `ascii_only` (default `false`) -- escape Unicode characters in strings and regexps (affects directives with non-ascii characters becoming invalid) + - `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. + - `bracketize` (default `false`) -- always insert brackets in `if`, `for`, `do`, `while` or `with` statements, even if their body is a single statement. + - `comments` (default `false`) -- pass `true` or `"all"` to preserve all comments, `"some"` to preserve some comments, a regular expression string (e.g. `/^!/`) or a function. -- `indent_level` (default 4) -- `indent_start` (default 0) -- prefix all lines by that many spaces + +- `indent_level` (default `4`) + +- `indent_start` (default `0`) -- prefix all lines by that many spaces + - `inline_script` (default `false`) -- escape the slash in occurrences of `</script` in strings + - `keep_quoted_props` (default `false`) -- when turned on, prevents stripping quotes from property names in object literals. + - `max_line_len` (default `false`) -- maximum line length (for uglified code) + - `preamble` (default `null`) -- when passed it must be a string and it will be prepended to the output literally. The source map will adjust for this text. Can be used to insert a comment containing licensing information, for example. + - `preserve_line` (default `false`) -- pass `true` to preserve lines, but it only works if `beautify` is set to `false`. + - `quote_keys` (default `false`) -- pass `true` to quote all keys in literal objects + - `quote_style` (default `0`) -- preferred quote style for strings (affects quoted property names and directives as well): - `0` -- prefers double quotes, switches to single quotes when there are @@ -822,16 +857,23 @@ can pass additional arguments that control the code output: - `1` -- always use single quotes - `2` -- always use double quotes - `3` -- always use the original quotes + - `semicolons` (default `true`) -- separate statements with semicolons. If you pass `false` then whenever possible we will use a newline instead of a semicolon, leading to more readable output of uglified code (size before gzip could be smaller; size after gzip insignificantly larger). + - `shebang` (default `true`) -- preserve shebang `#!` in preamble (bash scripts) -- `width` (default 80) -- only takes effect when beautification is on, this + +- `webkit` (default `false`) -- enable workarounds for WebKit bugs. + PhantomJS users should set this option to `true`. + +- `width` (default `80`) -- only takes effect when beautification is on, this specifies an (orientative) line width that the beautifier will try to obey. It refers to the width of the line text (excluding indentation). It doesn't work very well currently, but it does make the code generated by UglifyJS more readable. + - `wrap_iife` (default `false`) -- pass `true` to wrap immediately invoked function expressions. See [#640](https://github.com/mishoo/UglifyJS2/issues/640) for more details. @@ -1033,7 +1075,7 @@ in total it's a bit more than just using UglifyJS's own parser. ### Uglify Fast Minify Mode It's not well known, but whitespace removal and symbol mangling accounts -for 95% of the size reduction in minified code for most javascript - not +for 95% of the size reduction in minified code for most JavaScript - not elaborate code transforms. One can simply disable `compress` to speed up Uglify builds by 3 to 4 times. In this fast `mangle`-only mode Uglify has comparable minify speeds and gzip sizes to |