limit exposure of internal API
remove unsupported features from documentation
This commit is contained in:
alexlamsl
parent
663042d5aa
commit
a70e9b096c
169
README.md
169
README.md
|
|
@ -621,14 +621,8 @@ like this:
|
|||
var UglifyJS = require("uglify-js");
|
||||
```
|
||||
|
||||
It exports a lot of names, but I'll discuss here the basics that are needed
|
||||
for parsing, mangling and compressing a piece of code. The sequence is (1)
|
||||
parse, (2) compress, (3) mangle, (4) generate output code.
|
||||
|
||||
### The simple way
|
||||
|
||||
There's a single toplevel function which combines all the steps. If you
|
||||
don't need additional customization, you might want to go with `minify`.
|
||||
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() {};");
|
||||
|
|
@ -749,166 +743,7 @@ Other options:
|
|||
- `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.
|
||||
|
||||
We could add more options to `UglifyJS.minify` — if you need additional
|
||||
functionality please suggest!
|
||||
|
||||
### The hard way
|
||||
|
||||
Following there's more detailed API info, in case the `minify` function is
|
||||
too simple for your needs.
|
||||
|
||||
#### The parser
|
||||
```javascript
|
||||
var toplevel_ast = UglifyJS.parse(code, options);
|
||||
```
|
||||
|
||||
`options` is optional and if present it must be an object. The following
|
||||
properties are available:
|
||||
|
||||
- `strict` — disable automatic semicolon insertion and support for trailing
|
||||
comma in arrays and objects
|
||||
- `bare_returns` — Allow return outside of functions. (maps to the
|
||||
`--bare-returns` CLI arguments option and available to `minify` `parse`
|
||||
other options object)
|
||||
- `filename` — the name of the file where this code is coming from
|
||||
- `toplevel` — a `toplevel` node (as returned by a previous invocation of
|
||||
`parse`)
|
||||
|
||||
The last two options are useful when you'd like to minify multiple files and
|
||||
get a single file as the output and a proper source map. Our CLI tool does
|
||||
something like this:
|
||||
```javascript
|
||||
var toplevel = null;
|
||||
files.forEach(function(file){
|
||||
var code = fs.readFileSync(file, "utf8");
|
||||
toplevel = UglifyJS.parse(code, {
|
||||
filename: file,
|
||||
toplevel: toplevel
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
After this, we have in `toplevel` a big AST containing all our files, with
|
||||
each token having proper information about where it came from.
|
||||
|
||||
#### Scope information
|
||||
|
||||
UglifyJS contains a scope analyzer that you need to call manually before
|
||||
compressing or mangling. Basically it augments various nodes in the AST
|
||||
with information about where is a name defined, how many times is a name
|
||||
referenced, if it is a global or not, if a function is using `eval` or the
|
||||
`with` statement etc. I will discuss this some place else, for now what's
|
||||
important to know is that you need to call the following before doing
|
||||
anything with the tree:
|
||||
```javascript
|
||||
toplevel.figure_out_scope()
|
||||
```
|
||||
|
||||
#### Compression
|
||||
|
||||
Like this:
|
||||
```javascript
|
||||
var compressor = UglifyJS.Compressor(options);
|
||||
var compressed_ast = compressor.compress(toplevel);
|
||||
```
|
||||
|
||||
The `options` can be missing. Available options are discussed above in
|
||||
“Compressor options”. Defaults should lead to best compression in most
|
||||
scripts.
|
||||
|
||||
The compressor is destructive, so don't rely that `toplevel` remains the
|
||||
original tree.
|
||||
|
||||
#### Mangling
|
||||
|
||||
After compression it is a good idea to call again `figure_out_scope` (since
|
||||
the compressor might drop unused variables / unreachable code and this might
|
||||
change the number of identifiers or their position). Optionally, you can
|
||||
call a trick that helps after Gzip (counting character frequency in
|
||||
non-mangleable words). Example:
|
||||
```javascript
|
||||
compressed_ast.figure_out_scope();
|
||||
compressed_ast.compute_char_frequency();
|
||||
compressed_ast.mangle_names();
|
||||
```
|
||||
|
||||
#### Generating output
|
||||
|
||||
AST nodes have a `print` method that takes an output stream. Essentially,
|
||||
to generate code you do this:
|
||||
```javascript
|
||||
var stream = UglifyJS.OutputStream(options);
|
||||
compressed_ast.print(stream);
|
||||
var code = stream.toString(); // this is your minified code
|
||||
```
|
||||
|
||||
or, for a shortcut you can do:
|
||||
```javascript
|
||||
var code = compressed_ast.print_to_string(options);
|
||||
```
|
||||
|
||||
As usual, `options` is optional. The output stream accepts a lot of options,
|
||||
most of them documented above in section “Beautifier options”. The two
|
||||
which we care about here are `source_map` and `comments`.
|
||||
|
||||
#### Keeping comments in the output
|
||||
|
||||
In order to keep certain comments in the output you need to pass the
|
||||
`comments` option. Pass a RegExp (as string starting and closing with `/`
|
||||
or pass a RegExp object), a boolean or a function. Stringified options
|
||||
`all` and `some` can be passed too, where `some` behaves like it's CLI
|
||||
equivalent `--comments` without passing a value. If you pass a RegExp,
|
||||
only those comments whose body matches the RegExp will be kept. Note that body
|
||||
means without the initial `//` or `/*`. If you pass a function, it will be
|
||||
called for every comment in the tree and will receive two arguments: the
|
||||
node that the comment is attached to, and the comment token itself.
|
||||
|
||||
The comment token has these properties:
|
||||
|
||||
- `type`: "comment1" for single-line comments or "comment2" for multi-line
|
||||
comments
|
||||
- `value`: the comment body
|
||||
- `pos` and `endpos`: the start/end positions (zero-based indexes) in the
|
||||
original code where this comment appears
|
||||
- `line` and `col`: the line and column where this comment appears in the
|
||||
original code
|
||||
- `file` — the file name of the original file
|
||||
- `nlb` — true if there was a newline before this comment in the original
|
||||
code, or if this comment contains a newline.
|
||||
|
||||
Your function should return `true` to keep the comment, or a falsy value
|
||||
otherwise.
|
||||
|
||||
#### Generating a source mapping
|
||||
|
||||
You need to pass the `source_map` argument when calling `print`. It needs
|
||||
to be a `SourceMap` object (which is a thin wrapper on top of the
|
||||
[source-map][source-map] library).
|
||||
|
||||
Example:
|
||||
```javascript
|
||||
var source_map = UglifyJS.SourceMap(source_map_options);
|
||||
var stream = UglifyJS.OutputStream({
|
||||
...
|
||||
source_map: source_map
|
||||
});
|
||||
compressed_ast.print(stream);
|
||||
|
||||
var code = stream.toString();
|
||||
var map = source_map.toString(); // json output for your source map
|
||||
```
|
||||
|
||||
The `source_map_options` (optional) can contain the following properties:
|
||||
|
||||
- `file`: the name of the JavaScript output file that this mapping refers to
|
||||
- `root`: the `sourceRoot` property (see the [spec][sm-spec])
|
||||
- `orig`: the "original source map", handy when you compress generated JS
|
||||
and want to map the minified output back to the original code where it
|
||||
came from. It can be simply a string in JSON, or a JSON object containing
|
||||
the original source map.
|
||||
|
||||
[acorn]: https://github.com/ternjs/acorn
|
||||
[source-map]: https://github.com/mozilla/source-map
|
||||
[sm-spec]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k
|
||||
|
||||
#### Harmony
|
||||
|
|
|
|||
|
|
@ -1,20 +1,15 @@
|
|||
exports["Compressor"] = Compressor;
|
||||
exports["DefaultsError"] = DefaultsError;
|
||||
exports["Dictionary"] = Dictionary;
|
||||
exports["JS_Parse_Error"] = JS_Parse_Error;
|
||||
exports["MAP"] = MAP;
|
||||
exports["OutputStream"] = OutputStream;
|
||||
exports["SourceMap"] = SourceMap;
|
||||
exports["TreeTransformer"] = TreeTransformer;
|
||||
exports["TreeWalker"] = TreeWalker;
|
||||
exports["base54"] = base54;
|
||||
exports["defaults"] = defaults;
|
||||
exports["mangle_properties"] = mangle_properties;
|
||||
exports["merge"] = merge;
|
||||
exports["minify"] = minify;
|
||||
exports["parse"] = parse;
|
||||
exports["push_uniq"] = push_uniq;
|
||||
exports["string_template"] = string_template;
|
||||
exports["tokenizer"] = tokenizer;
|
||||
exports["is_identifier"] = is_identifier;
|
||||
exports["SymbolDef"] = SymbolDef;
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user