Add README syntax highlighting

This commit is contained in:
Uli Köhler
2013-05-01 15:56:20 +02:00
parent 8e6266136d
commit a54b6703c0

174
README.md
View File

@@ -222,10 +222,11 @@ You can use the `--define` (`-d`) switch in order to declare global
variables that UglifyJS will assume to be constants (unless defined in variables that UglifyJS will assume to be constants (unless defined in
scope). For example if you pass `--define DEBUG=false` then, coupled with scope). For example if you pass `--define DEBUG=false` then, coupled with
dead code removal UglifyJS will discard the following from the output: dead code removal UglifyJS will discard the following from the output:
```javascript
if (DEBUG) { if (DEBUG) {
console.log("debug stuff"); console.log("debug stuff");
} }
```
UglifyJS will warn about the condition being always false and about dropping 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 unreachable code; for now there is no option to turn off only this specific
@@ -234,10 +235,11 @@ 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 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 separate file and include it into the build. For example you can have a
`build/defines.js` file with the following: `build/defines.js` file with the following:
```javascript
const DEBUG = false; const DEBUG = false;
const PRODUCTION = true; const PRODUCTION = true;
// etc. // etc.
```
and build your code like this: and build your code like this:
@@ -296,14 +298,15 @@ keep only comments that match this regexp. For example `--comments
Note, however, that there might be situations where comments are lost. For Note, however, that there might be situations where comments are lost. For
example: example:
```javascript
function f() { function f() {
/** @preserve Foo Bar */ /** @preserve Foo Bar */
function g() { function g() {
// this function is never called // this function is never called
} }
return something(); return something();
} }
```
Even though it has "@preserve", the comment will be lost because the inner Even though it has "@preserve", the comment will be lost because the inner
function `g` (which is the AST node to which the comment is attached to) is function `g` (which is the AST node to which the comment is attached to) is
@@ -345,8 +348,9 @@ API Reference
Assuming installation via NPM, you can load UglifyJS in your application Assuming installation via NPM, you can load UglifyJS in your application
like this: like this:
```javascript
var UglifyJS = require("uglify-js"); var UglifyJS = require("uglify-js");
```
It exports a lot of names, but I'll discuss here the basics that are needed 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) for parsing, mangling and compressing a piece of code. The sequence is (1)
@@ -357,45 +361,49 @@ parse, (2) compress, (3) mangle, (4) generate output code.
There's a single toplevel function which combines all the steps. If you 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`. don't need additional customization, you might want to go with `minify`.
Example: Example:
```javascript
var result = UglifyJS.minify("/path/to/file.js"); var result = UglifyJS.minify("/path/to/file.js");
console.log(result.code); // minified output console.log(result.code); // minified output
// if you need to pass code instead of file name // if you need to pass code instead of file name
var result = UglifyJS.minify("var b = function () {};", {fromString: true}); var result = UglifyJS.minify("var b = function () {};", {fromString: true});
```
You can also compress multiple files: You can also compress multiple files:
```javascript
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ]); var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ]);
console.log(result.code); console.log(result.code);
```
To generate a source map: To generate a source map:
```javascript
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], { var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], {
outSourceMap: "out.js.map" outSourceMap: "out.js.map"
}); });
console.log(result.code); // minified output console.log(result.code); // minified output
console.log(result.map); console.log(result.map);
```
Note that the source map is not saved in a file, it's just returned in Note that the source map is not saved in a file, it's just returned in
`result.map`. The value passed for `outSourceMap` is only used to set the `result.map`. The value passed for `outSourceMap` is only used to set the
`file` attribute in the source map (see [the spec][sm-spec]). `file` attribute in the source map (see [the spec][sm-spec]).
You can also specify sourceRoot property to be included in source map: You can also specify sourceRoot property to be included in source map:
```javascript
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], { var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], {
outSourceMap: "out.js.map", outSourceMap: "out.js.map",
sourceRoot: "http://example.com/src" sourceRoot: "http://example.com/src"
}); });
```
If you're compressing compiled JavaScript and have a source map for it, you If you're compressing compiled JavaScript and have a source map for it, you
can use the `inSourceMap` argument: can use the `inSourceMap` argument:
```javascript
var result = UglifyJS.minify("compiled.js", { var result = UglifyJS.minify("compiled.js", {
inSourceMap: "compiled.js.map", inSourceMap: "compiled.js.map",
outSourceMap: "minified.js.map" outSourceMap: "minified.js.map"
}); });
// same as before, it returns `code` and `map` // same as before, it returns `code` and `map`
```
The `inSourceMap` is only used if you also request `outSourceMap` (it makes The `inSourceMap` is only used if you also request `outSourceMap` (it makes
no sense otherwise). no sense otherwise).
@@ -425,8 +433,9 @@ Following there's more detailed API info, in case the `minify` function is
too simple for your needs. too simple for your needs.
#### The parser #### The parser
```javascript
var toplevel_ast = UglifyJS.parse(code, options); var toplevel_ast = UglifyJS.parse(code, options);
```
`options` is optional and if present it must be an object. The following `options` is optional and if present it must be an object. The following
properties are available: properties are available:
@@ -440,15 +449,16 @@ properties are available:
The last two options are useful when you'd like to minify multiple files and 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 get a single file as the output and a proper source map. Our CLI tool does
something like this: something like this:
```javascript
var toplevel = null; var toplevel = null;
files.forEach(function(file){ files.forEach(function(file){
var code = fs.readFileSync(file); var code = fs.readFileSync(file);
toplevel = UglifyJS.parse(code, { toplevel = UglifyJS.parse(code, {
filename: file, filename: file,
toplevel: toplevel toplevel: toplevel
}); });
}); });
```
After this, we have in `toplevel` a big AST containing all our files, with After this, we have in `toplevel` a big AST containing all our files, with
each token having proper information about where it came from. each token having proper information about where it came from.
@@ -462,15 +472,17 @@ 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 `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 important to know is that you need to call the following before doing
anything with the tree: anything with the tree:
```javascript
toplevel.figure_out_scope() toplevel.figure_out_scope()
```
#### Compression #### Compression
Like this: Like this:
```javascript
var compressor = UglifyJS.Compressor(options); var compressor = UglifyJS.Compressor(options);
var compressed_ast = toplevel.transform(compressor); var compressed_ast = toplevel.transform(compressor);
```
The `options` can be missing. Available options are discussed above in The `options` can be missing. Available options are discussed above in
“Compressor options”. Defaults should lead to best compression in most “Compressor options”. Defaults should lead to best compression in most
@@ -486,23 +498,26 @@ the compressor might drop unused variables / unreachable code and this might
change the number of identifiers or their position). Optionally, you can change the number of identifiers or their position). Optionally, you can
call a trick that helps after Gzip (counting character frequency in call a trick that helps after Gzip (counting character frequency in
non-mangleable words). Example: non-mangleable words). Example:
```javascript
compressed_ast.figure_out_scope(); compressed_ast.figure_out_scope();
compressed_ast.compute_char_frequency(); compressed_ast.compute_char_frequency();
compressed_ast.mangle_names(); compressed_ast.mangle_names();
```
#### Generating output #### Generating output
AST nodes have a `print` method that takes an output stream. Essentially, AST nodes have a `print` method that takes an output stream. Essentially,
to generate code you do this: to generate code you do this:
```javascript
var stream = UglifyJS.OutputStream(options); var stream = UglifyJS.OutputStream(options);
compressed_ast.print(stream); compressed_ast.print(stream);
var code = stream.toString(); // this is your minified code var code = stream.toString(); // this is your minified code
```
or, for a shortcut you can do: or, for a shortcut you can do:
```javascript
var code = compressed_ast.print_to_string(options); var code = compressed_ast.print_to_string(options);
```
As usual, `options` is optional. The output stream accepts a lot of otions, As usual, `options` is optional. The output stream accepts a lot of otions,
most of them documented above in section “Beautifier options”. The two most of them documented above in section “Beautifier options”. The two
@@ -540,16 +555,17 @@ to be a `SourceMap` object (which is a thin wrapper on top of the
[source-map][source-map] library). [source-map][source-map] library).
Example: Example:
```javascript
var source_map = UglifyJS.SourceMap(source_map_options);
var stream = UglifyJS.OutputStream({
...
source_map: source_map
});
compressed_ast.print(stream);
var source_map = UglifyJS.SourceMap(source_map_options); var code = stream.toString();
var stream = UglifyJS.OutputStream({ var map = source_map.toString(); // json output for your source map
... ```
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: The `source_map_options` (optional) can contain the following properties: