[Pkg-javascript-commits] [uglifyjs] 68/491: reorg README for 3.x (#1942)
Jonas Smedegaard
dr at jones.dk
Wed Feb 14 19:51:22 UTC 2018
This is an automated email from the git hooks/post-receive script.
js pushed a commit to annotated tag debian/3.3.10-1
in repository uglifyjs.
commit 3be06ad0855b5fcb72e0c73b261c859e6e120ba2
Author: kzc <kzc at users.noreply.github.com>
Date: Mon May 15 13:12:00 2017 -0400
reorg README for 3.x (#1942)
---
README.md | 494 ++++++++++++++++++++++++++++++++++++--------------------------
1 file changed, 291 insertions(+), 203 deletions(-)
diff --git a/README.md b/README.md
index 8707939..f1927bc 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ UglifyJS 3
UglifyJS is a JavaScript parser, minifier, compressor and beautifier toolkit.
#### Note:
-- **`uglify-js at 3.x` has a simplified API and CLI that is not backwards compatible with [`uglify-js at 2.x`](https://github.com/mishoo/UglifyJS2/tree/v2.x)**.
+- **`uglify-js at 3` has a simplified [API](#api-reference) and [CLI](#command-line-usage) that is not backwards compatible with [`uglify-js at 2`](https://github.com/mishoo/UglifyJS2/tree/v2.x)**.
- **Documentation for UglifyJS `2.x` releases can be found [here](https://github.com/mishoo/UglifyJS2/tree/v2.x)**.
- `uglify-js` only supports ECMAScript 5 (ES5).
- Those wishing to minify
@@ -25,8 +25,7 @@ From NPM for programmatic use:
npm install uglify-js
-Usage
------
+# Command line usage
uglifyjs [input files] [options]
@@ -43,7 +42,7 @@ a double dash to prevent input files being used as option arguments:
uglifyjs --compress --mangle -- input.js
-The available options are:
+### Command line options
```
-h, --help Print usage information.
@@ -142,7 +141,7 @@ The available options are:
Specify `--output` (`-o`) to declare the output file. Otherwise the output
goes to STDOUT.
-## Source map options
+## CLI source map options
UglifyJS can generate a source map file, which is highly useful for
debugging your compressed JavaScript. To get a source map, pass
@@ -186,7 +185,20 @@ To use this feature pass `--source-map content="/path/to/input/source.map"`
or `--source-map content=inline` if the source map is included inline with
the sources.
-## Mangler options
+## CLI compress options
+
+You need to pass `--compress` (`-c`) to enable the compressor. Optionally
+you can pass a comma-separated list of [compress options](#compress-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`).
+
+Example:
+
+ uglifyjs file.js -c toplevel,sequences=false
+
+## CLI mangle options
To enable the mangler you need to pass `--mangle` (`-m`). The following
(comma-separated) options are supported:
@@ -205,7 +217,7 @@ comma-separated list of names. For example:
to prevent the `require`, `exports` and `$` names from being changed.
-### Mangling property names (`--mangle-props`)
+### CLI 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
@@ -255,7 +267,7 @@ 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 keep_quoted`)
+### Mangling unquoted names (`--mangle-props keep_quoted`)
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
@@ -266,7 +278,7 @@ $ echo 'var o={"foo":1, bar:3}; o.foo += o.bar; console.log(o.foo);' | uglifyjs
var o={foo:1,a:3};o.foo+=o.a,console.log(o.foo);
```
-#### Debugging property name mangling
+### 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`
@@ -281,12 +293,144 @@ 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`).
+# API Reference
+
+Assuming installation via NPM, you can load UglifyJS in your application
+like this:
+```javascript
+var UglifyJS = require("uglify-js");
+```
+
+There is a single high level minification function, `minify(files, options)`, which will
+performs all the steps in a configurable manner.
+Example:
+```javascript
+var result = UglifyJS.minify("var b = function() {};");
+console.log(result.code); // minified output
+console.log(result.error); // runtime error
+```
+
+You can also compress multiple files:
+```javascript
+var result = UglifyJS.minify({
+ "file1.js": "var a = function() {};",
+ "file2.js": "var b = function() {};"
+});
+console.log(result.code);
+```
+
+## Minify options
+
+- `warnings` (default `false`) — pass `true` to display compressor warnings.
+
+- `parse` (default `{}`) — pass an object if you wish to specify some
+ additional [parse options](#parse-options).
+
+- `compress` (default `{}`) — pass `false` to skip compressing entirely.
+ Pass an object to specify custom [compress options](#compress-options).
+
+- `mangle` (default `true`) — pass `false` to skip mangling names, or pass
+ an object to specify [mangle options](#mangle-options) (see below).
+
+ - `mangle.properties` (default `false`) — a subcategory of the mangle option.
+ Pass an object to specify custom [mangle property options](#mangle-properties-options).
+
+- `output` (default `null`) — pass an object if you wish to specify
+ additional [output options](#output-options). The defaults are optimized
+ for best compression.
+
+- `sourceMap` (default `false`) - pass an object if you wish to specify
+ [source map options](#source-map-options).
+
+- `toplevel` (default `false`) - set to `true` if you wish to enable top level
+ variable and function name mangling and to drop unused variables and functions.
+
+- `ie8` (default `false`) - set to `true` to support IE8.
+
+## Minify option structure
+
+```
+{
+ warnings: false,
+ parse: {
+ // parse options
+ },
+ compress: {
+ // compress options
+ },
+ mangle: {
+ // mangle options
+
+ properties: {
+ // mangle property options
+ }
+ },
+ output: {
+ // output options
+ },
+ sourceMap: {
+ // source map options
+ },
+ toplevel: false,
+ ie8: false,
+}
+```
+
+### Source map options
+
+To generate a source map:
+```javascript
+var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
+ sourceMap: {
+ filename: "out.js",
+ url: "out.js.map"
+ }
+});
+console.log(result.code); // minified output
+console.log(result.map); // source map
+```
+
+Note that the source map is not saved in a file, it's just returned in
+`result.map`. The value passed for `sourceMap.url` is only used to set
+`//# sourceMappingURL=out.js.map` in `result.code`. The value of
+`filename` is only used to set `file` attribute (see [the spec][sm-spec])
+in source map file.
+
+You can set option `sourceMap.url` to be `"inline"` and source map will
+be appended to code.
+
+You can also specify sourceRoot property to be included in source map:
+```javascript
+var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
+ sourceMap: {
+ root: "http://example.com/src",
+ url: "out.js.map"
+ }
+});
+```
+
+If you're compressing compiled JavaScript and have a source map for it, you
+can use `sourceMap.content`:
+```javascript
+var result = UglifyJS.minify({"compiled.js": "compiled code"}, {
+ sourceMap: {
+ content: "content from compiled.js.map",
+ url: "minified.js.map"
+ }
+});
+// same as before, it returns `code` and `map`
+```
+
+If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.url`.
+
+## 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
@@ -414,76 +558,51 @@ 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
-### The `unsafe` option
+- `reserved` - pass an array of identifiers that should be excluded from mangling
-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:
+- `toplevel` — mangle names declared in the toplevel scope (disabled by
+default).
-- `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)
+- `eval` — mangle names visible in scopes where eval or with are used
+(disabled by default).
-### Conditional compilation
+- `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).
+
+Examples:
-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");
+// test.js
+var globalVar;
+function funcName(firstLongName, anotherLongName)
+{
+ var myVariable = firstLongName + anotherLongName;
}
```
-
-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.
-```
+var code = fs.readFileSync("test.js", "utf8");
-and build your code like this:
+UglifyJS.minify(code).code;
+// 'function funcName(a,n){}var globalVar;'
- uglifyjs build/defines.js js/foo.js js/bar.js... -c
+UglifyJS.minify(code, { mangle: { reserved: ['firstLongName'] } }).code;
+// 'function funcName(firstLongName,a){}var globalVar;'
-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.
+UglifyJS.minify(code, { mangle: { toplevel: true } }).code;
+// 'function n(n,a){}var a;'
+```
-#### 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:
+### Mangle properties options
-```js
-uglifyJS.minify(fs.readFileSync("input.js", "utf8"), {
- compress: {
- dead_code: true,
- global_defs: {
- DEBUG: false
- }
- }
-});
-```
+- `regex` — Pass a RegExp to only mangle certain names
+- `keep_quoted` — Only mangle unquoted property names
+- `debug` — Mangle names with the original name still present. Defaults to `false`.
+ Pass an empty string to enable, or a non-empty string to set the suffix.
-## Beautifier options
+## Output options
The code generator tries to output shortest code possible by default. In
case you want beautified output, pass `--beautify` (`-b`). Optionally you
@@ -529,6 +648,9 @@ can pass additional arguments that control the code output:
- `keep_quoted_props` (default `false`) -- when turned on, prevents stripping
quotes from property names in object literals.
+
+# Miscellaneous
+
### Keeping copyright notices or other comments
You can pass `--comments` to retain certain comments in the output. By
@@ -557,169 +679,135 @@ discarded by the compressor as not referenced.
The safest comments where to place copyright information (or other info that
needs to be kept in the output) are comments attached to toplevel nodes.
-## Support for the SpiderMonkey AST
-
-UglifyJS has its own abstract syntax tree format; for
-[practical reasons](http://lisperator.net/blog/uglifyjs-why-not-switching-to-spidermonkey-ast/)
-we can't easily change to using the SpiderMonkey AST internally. However,
-UglifyJS now has a converter which can import a SpiderMonkey AST.
-
-For example [Acorn][acorn] is a super-fast parser that produces a
-SpiderMonkey AST. It has a small CLI utility that parses one file and dumps
-the AST in JSON on the standard output. To use UglifyJS to mangle and
-compress that:
+### The `unsafe` `compress` option
- acorn file.js | uglifyjs -p spidermonkey -m -c
+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:
-The `-p spidermonkey` option tells UglifyJS that all input files are not
-JavaScript, but JS code described in SpiderMonkey AST in JSON. Therefore we
-don't use our own parser in this case, but just transform that AST into our
-internal AST.
+- `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)
-### Use Acorn for parsing
+### Conditional compilation
-More for fun, I added the `-p acorn` option which will use Acorn to do all
-the parsing. If you pass this option, UglifyJS will `require("acorn")`.
+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");
+}
+```
-Acorn is really fast (e.g. 250ms instead of 380ms on some 650K code), but
-converting the SpiderMonkey tree that Acorn produces takes another 150ms so
-in total it's a bit more than just using UglifyJS's own parser.
+You can specify nested constants in the form of `--define env.DEBUG=false`.
-API Reference
--------------
+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.
-Assuming installation via NPM, you can load UglifyJS in your application
-like this:
+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
-var UglifyJS = require("uglify-js");
+const DEBUG = false;
+const PRODUCTION = true;
+// etc.
```
-There is a single toplevel function, `minify(files, options)`, which will
-performs all the steps in a configurable manner.
-Example:
-```javascript
-var result = UglifyJS.minify("var b = function() {};");
-console.log(result.code); // minified output
-console.log(result.error); // runtime error
-```
+and build your code like this:
-You can also compress multiple files:
-```javascript
-var result = UglifyJS.minify({
- "file1.js": "var a = function() {};",
- "file2.js": "var b = function() {};"
-});
-console.log(result.code);
-```
+ uglifyjs build/defines.js js/foo.js js/bar.js... -c
-To generate a source map:
-```javascript
-var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
- sourceMap: {
- filename: "out.js",
- url: "out.js.map"
- }
-});
-console.log(result.code); // minified output
-console.log(result.map); // source map
-```
+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.
-Note that the source map is not saved in a file, it's just returned in
-`result.map`. The value passed for `sourceMap.url` is only used to set
-`//# sourceMappingURL=out.js.map` in `result.code`. The value of
-`filename` is only used to set `file` attribute (see [the spec][sm-spec])
-in source map file.
+### Conditional compilation API
-You can set option `sourceMap.url` to be `"inline"` and source map will
-be appended to code.
+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:
-You can also specify sourceRoot property to be included in source map:
-```javascript
-var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
- sourceMap: {
- root: "http://example.com/src",
- url: "out.js.map"
- }
+```js
+var result = uglifyJS.minify(fs.readFileSync("input.js", "utf8"), {
+ compress: {
+ dead_code: true,
+ global_defs: {
+ DEBUG: false
+ }
+ }
});
```
-If you're compressing compiled JavaScript and have a source map for it, you
-can use `sourceMap.content`:
-```javascript
-var result = UglifyJS.minify({"compiled.js": "compiled code"}, {
- sourceMap: {
- content: "content from compiled.js.map",
- url: "minified.js.map"
- }
-});
-// same as before, it returns `code` and `map`
+### Using native Uglify AST with `minify()`
```
+// example: parse only, produce native Uglify AST
+
+var result = UglifyJS.minify(code, {
+ parse: {},
+ compress: false,
+ mangle: false,
+ output: {
+ ast: true,
+ code: false // optional - faster if false
+ }
+});
-If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.url`.
-
-Other options:
-
-- `warnings` (default `false`) — pass `true` to display compressor warnings.
-
-- `mangle` (default `true`) — pass `false` to skip mangling names, or pass
- an object to specify mangling options (see below).
-
-- `mangleProperties` (default `false`) — pass an object to specify custom
- mangle property options.
-
-- `output` (default `null`) — pass an object if you wish to specify
- additional [output options](#beautifier-options). The defaults are optimized
- for best compression.
-
-- `compress` (default `{}`) — pass `false` to skip compressing entirely.
- Pass an object to specify custom [compressor options](#compressor-options).
-
-- `parse` (default {}) — pass an object if you wish to specify some
- additional [parser options](#the-parser).
-
-##### mangle
-
-- `reserved` - pass an array of identifiers that should be excluded from mangling
-
-- `toplevel` — mangle names declared in the toplevel scope (disabled by
-default).
+// result.ast contains native Uglify AST
+```
+```
+// example: accept native Uglify AST input and then compress and mangle
+// to produce both code and native AST.
+
+var result = UglifyJS.minify(ast, {
+ compress: {},
+ mangle: {},
+ output: {
+ ast: true,
+ code: true // optional - faster if false
+ }
+});
-- `eval` — mangle names visible in scopes where eval or with are used
-(disabled by default).
+// result.ast contains native Uglify AST
+// result.code contains the minified code in string form.
+```
-- `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](#compressor-options).
+### ESTree / SpiderMonkey AST
-Examples:
+UglifyJS has its own abstract syntax tree format; for
+[practical reasons](http://lisperator.net/blog/uglifyjs-why-not-switching-to-spidermonkey-ast/)
+we can't easily change to using the SpiderMonkey AST internally. However,
+UglifyJS now has a converter which can import a SpiderMonkey AST.
-```javascript
-// test.js
-var globalVar;
-function funcName(firstLongName, anotherLongName)
-{
- var myVariable = firstLongName + anotherLongName;
-}
-```
-```javascript
-var code = fs.readFileSync("test.js", "utf8");
+For example [Acorn][acorn] is a super-fast parser that produces a
+SpiderMonkey AST. It has a small CLI utility that parses one file and dumps
+the AST in JSON on the standard output. To use UglifyJS to mangle and
+compress that:
-UglifyJS.minify(code).code;
-// 'function funcName(a,n){}var globalVar;'
+ acorn file.js | uglifyjs -p spidermonkey -m -c
-UglifyJS.minify(code, { mangle: { reserved: ['firstLongName'] } }).code;
-// 'function funcName(firstLongName,a){}var globalVar;'
+The `-p spidermonkey` option tells UglifyJS that all input files are not
+JavaScript, but JS code described in SpiderMonkey AST in JSON. Therefore we
+don't use our own parser in this case, but just transform that AST into our
+internal AST.
-UglifyJS.minify(code, { mangle: { toplevel: true } }).code;
-// 'function n(n,a){}var a;'
-```
+### Use Acorn for parsing
-##### mangle.properties options
+More for fun, I added the `-p acorn` option which will use Acorn to do all
+the parsing. If you pass this option, UglifyJS will `require("acorn")`.
-- `regex` — Pass a RegExp to only mangle certain names
-- `keep_quoted` — Only mangle unquoted property names
-- `debug` — Mangle names with the original name still present. Defaults to `false`.
- Pass an empty string to enable, or a non-empty string to set the suffix.
+Acorn is really fast (e.g. 250ms instead of 380ms on some 650K code), but
+converting the SpiderMonkey tree that Acorn produces takes another 150ms so
+in total it's a bit more than just using UglifyJS's own parser.
[acorn]: https://github.com/ternjs/acorn
[sm-spec]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/uglifyjs.git
More information about the Pkg-javascript-commits
mailing list