From a70e9b096cf9000d414b61002707c2ee8287c0cb Mon Sep 17 00:00:00 2001 From: alexlamsl Date: Sat, 15 Apr 2017 22:43:14 +0800 Subject: [PATCH] limit exposure of internal API remove unsupported features from documentation --- README.md | 169 +---------------------------------------------- tools/exports.js | 5 -- 2 files changed, 2 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index 8d07cfcd..42d2e87d 100644 --- a/README.md +++ b/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 diff --git a/tools/exports.js b/tools/exports.js index 499fc84c..fec003d7 100644 --- a/tools/exports.js +++ b/tools/exports.js @@ -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;