818
Du
dustymarkdown / files
dustymarkdown / node_modules / uglify-js / README.org
17.9 KB
1#+TITLE: UglifyJS -- a JavaScript parser/compressor/beautifier 2#+KEYWORDS: javascript, js, parser, compiler, compressor, mangle, minify, minifier 3#+DESCRIPTION: a JavaScript parser/compressor/beautifier in JavaScript 4#+STYLE: <link rel="stylesheet" type="text/css" href="docstyle.css" /> 5#+AUTHOR: Mihai Bazon 6#+EMAIL: mihai.bazon@gmail.com 7 8* UglifyJS --- a JavaScript parser/compressor/beautifier 9 10This package implements a general-purpose JavaScript 11parser/compressor/beautifier toolkit. It is developed on [[http://nodejs.org/][NodeJS]], but it 12should work on any JavaScript platform supporting the CommonJS module system 13(and if your platform of choice doesn't support CommonJS, you can easily 14implement it, or discard the =exports.*= lines from UglifyJS sources). 15 16The tokenizer/parser generates an abstract syntax tree from JS code. You 17can then traverse the AST to learn more about the code, or do various 18manipulations on it. This part is implemented in [[../lib/parse-js.js][parse-js.js]] and it's a 19port to JavaScript of the excellent [[http://marijn.haverbeke.nl/parse-js/][parse-js]] Common Lisp library from [[http://marijn.haverbeke.nl/][Marijn 20Haverbeke]]. 21 22( See [[http://github.com/mishoo/cl-uglify-js][cl-uglify-js]] if you're looking for the Common Lisp version of 23UglifyJS. ) 24 25The second part of this package, implemented in [[../lib/process.js][process.js]], inspects and 26manipulates the AST generated by the parser to provide the following: 27 28- ability to re-generate JavaScript code from the AST. Optionally 29 indented---you can use this if you want to “beautify” a program that has 30 been compressed, so that you can inspect the source. But you can also run 31 our code generator to print out an AST without any whitespace, so you 32 achieve compression as well. 33 34- shorten variable names (usually to single characters). Our mangler will 35 analyze the code and generate proper variable names, depending on scope 36 and usage, and is smart enough to deal with globals defined elsewhere, or 37 with =eval()= calls or =with{}= statements. In short, if =eval()= or 38 =with{}= are used in some scope, then all variables in that scope and any 39 variables in the parent scopes will remain unmangled, and any references 40 to such variables remain unmangled as well. 41 42- various small optimizations that may lead to faster code but certainly 43 lead to smaller code. Where possible, we do the following: 44 45 - foo["bar"] ==> foo.bar 46 47 - remove block brackets ={}= 48 49 - join consecutive var declarations: 50 var a = 10; var b = 20; ==> var a=10,b=20; 51 52 - resolve simple constant expressions: 1 +2 * 3 ==> 7. We only do the 53 replacement if the result occupies less bytes; for example 1/3 would 54 translate to 0.333333333333, so in this case we don't replace it. 55 56 - consecutive statements in blocks are merged into a sequence; in many 57 cases, this leaves blocks with a single statement, so then we can remove 58 the block brackets. 59 60 - various optimizations for IF statements: 61 62 - if (foo) bar(); else baz(); ==> foo?bar():baz(); 63 - if (!foo) bar(); else baz(); ==> foo?baz():bar(); 64 - if (foo) bar(); ==> foo&&bar(); 65 - if (!foo) bar(); ==> foo||bar(); 66 - if (foo) return bar(); else return baz(); ==> return foo?bar():baz(); 67 - if (foo) return bar(); else something(); ==> {if(foo)return bar();something()} 68 69 - remove some unreachable code and warn about it (code that follows a 70 =return=, =throw=, =break= or =continue= statement, except 71 function/variable declarations). 72 73** <<Unsafe transformations>> 74 75UglifyJS tries its best to achieve great compression while leaving the 76semantics of the code intact. In general, if your code logic is broken by 77UglifyJS then it's a bug in UglifyJS and you should report it and I should 78fix it. :-) 79 80However, I opted to include the following potentially unsafe transformations 81as default behavior. Discussion is welcome, if you have ideas of how to 82handle this better, or any objections to these optimizations, please let me 83know. 84 85*** Calls involving the global Array constructor 86 87The following transformations occur: 88 89#+BEGIN_SRC js 90new Array(1, 2, 3, 4) => [1,2,3,4] 91Array(a, b, c) => [a,b,c] 92new Array(5) => Array(5) 93new Array(a) => Array(a) 94#+END_SRC 95 96These are all safe if the Array name isn't redefined. JavaScript does allow 97one to globally redefine Array (and pretty much everything, in fact) but I 98personally don't see why would anyone do that. 99 100UglifyJS does handle the case where Array is redefined locally, or even 101globally but with a =function= or =var= declaration. Therefore, in the 102following cases UglifyJS *doesn't touch* calls or instantiations of Array: 103 104#+BEGIN_SRC js 105// case 1. globally declared variable 106 var Array; 107 new Array(1, 2, 3); 108 Array(a, b); 109 110 // or (can be declared later) 111 new Array(1, 2, 3); 112 var Array; 113 114 // or (can be a function) 115 new Array(1, 2, 3); 116 function Array() { ... } 117 118// case 2. declared in a function 119 (function(){ 120 a = new Array(1, 2, 3); 121 b = Array(5, 6); 122 var Array; 123 })(); 124 125 // or 126 (function(Array){ 127 return Array(5, 6, 7); 128 })(); 129 130 // or 131 (function(){ 132 return new Array(1, 2, 3, 4); 133 function Array() { ... } 134 })(); 135 136 // etc. 137#+END_SRC 138 139** Install (NPM) 140 141UglifyJS is now available through NPM --- =npm install uglify-js= should do 142the job. 143 144** Install latest code from GitHub 145 146#+BEGIN_SRC sh 147## clone the repository 148mkdir -p /where/you/wanna/put/it 149cd /where/you/wanna/put/it 150git clone git://github.com/mishoo/UglifyJS.git 151 152## make the module available to Node 153mkdir -p ~/.node_libraries/ 154cd ~/.node_libraries/ 155ln -s /where/you/wanna/put/it/UglifyJS/uglify-js.js 156 157## and if you want the CLI script too: 158mkdir -p ~/bin 159cd ~/bin 160ln -s /where/you/wanna/put/it/UglifyJS/bin/uglifyjs 161 # (then add ~/bin to your $PATH if it's not there already) 162#+END_SRC 163 164** Usage 165 166There is a command-line tool that exposes the functionality of this library 167for your shell-scripting needs: 168 169#+BEGIN_SRC sh 170uglifyjs [ options... ] [ filename ] 171#+END_SRC 172 173=filename= should be the last argument and should name the file from which 174to read the JavaScript code. If you don't specify it, it will read code 175from STDIN. 176 177Supported options: 178 179- =-b= or =--beautify= --- output indented code; when passed, additional 180 options control the beautifier: 181 182 - =-i N= or =--indent N= --- indentation level (number of spaces) 183 184 - =-q= or =--quote-keys= --- quote keys in literal objects (by default, 185 only keys that cannot be identifier names will be quotes). 186 187- =--ascii= --- pass this argument to encode non-ASCII characters as 188 =\uXXXX= sequences. By default UglifyJS won't bother to do it and will 189 output Unicode characters instead. (the output is always encoded in UTF8, 190 but if you pass this option you'll only get ASCII). 191 192- =-nm= or =--no-mangle= --- don't mangle variable names 193 194- =-ns= or =--no-squeeze= --- don't call =ast_squeeze()= (which does various 195 optimizations that result in smaller, less readable code). 196 197- =-mt= or =--mangle-toplevel= --- mangle names in the toplevel scope too 198 (by default we don't do this). 199 200- =--no-seqs= --- when =ast_squeeze()= is called (thus, unless you pass 201 =--no-squeeze=) it will reduce consecutive statements in blocks into a 202 sequence. For example, "a = 10; b = 20; foo();" will be written as 203 "a=10,b=20,foo();". In various occasions, this allows us to discard the 204 block brackets (since the block becomes a single statement). This is ON 205 by default because it seems safe and saves a few hundred bytes on some 206 libs that I tested it on, but pass =--no-seqs= to disable it. 207 208- =--no-dead-code= --- by default, UglifyJS will remove code that is 209 obviously unreachable (code that follows a =return=, =throw=, =break= or 210 =continue= statement and is not a function/variable declaration). Pass 211 this option to disable this optimization. 212 213- =-nc= or =--no-copyright= --- by default, =uglifyjs= will keep the initial 214 comment tokens in the generated code (assumed to be copyright information 215 etc.). If you pass this it will discard it. 216 217- =-o filename= or =--output filename= --- put the result in =filename=. If 218 this isn't given, the result goes to standard output (or see next one). 219 220- =--overwrite= --- if the code is read from a file (not from STDIN) and you 221 pass =--overwrite= then the output will be written in the same file. 222 223- =--ast= --- pass this if you want to get the Abstract Syntax Tree instead 224 of JavaScript as output. Useful for debugging or learning more about the 225 internals. 226 227- =-v= or =--verbose= --- output some notes on STDERR (for now just how long 228 each operation takes). 229 230- =--extra= --- enable additional optimizations that have not yet been 231 extensively tested. These might, or might not, break your code. If you 232 find a bug using this option, please report a test case. 233 234- =--unsafe= --- enable other additional optimizations that are known to be 235 unsafe in some contrived situations, but could still be generally useful. 236 For now only this: 237 238 - foo.toString() ==> foo+"" 239 240- =--max-line-len= (default 32K characters) --- add a newline after around 241 32K characters. I've seen both FF and Chrome croak when all the code was 242 on a single line of around 670K. Pass --max-line-len 0 to disable this 243 safety feature. 244 245- =--reserved-names= --- some libraries rely on certain names to be used, as 246 pointed out in issue #92 and #81, so this option allow you to exclude such 247 names from the mangler. For example, to keep names =require= and =$super= 248 intact you'd specify --reserved-names "require,$super". 249 250*** API 251 252To use the library from JavaScript, you'd do the following (example for 253NodeJS): 254 255#+BEGIN_SRC js 256var jsp = require("uglify-js").parser; 257var pro = require("uglify-js").uglify; 258 259var orig_code = "... JS code here"; 260var ast = jsp.parse(orig_code); // parse code and get the initial AST 261ast = pro.ast_mangle(ast); // get a new AST with mangled names 262ast = pro.ast_squeeze(ast); // get an AST with compression optimizations 263var final_code = pro.gen_code(ast); // compressed code here 264#+END_SRC 265 266The above performs the full compression that is possible right now. As you 267can see, there are a sequence of steps which you can apply. For example if 268you want compressed output but for some reason you don't want to mangle 269variable names, you would simply skip the line that calls 270=pro.ast_mangle(ast)=. 271 272Some of these functions take optional arguments. Here's a description: 273 274- =jsp.parse(code, strict_semicolons)= -- parses JS code and returns an AST. 275 =strict_semicolons= is optional and defaults to =false=. If you pass 276 =true= then the parser will throw an error when it expects a semicolon and 277 it doesn't find it. For most JS code you don't want that, but it's useful 278 if you want to strictly sanitize your code. 279 280- =pro.ast_mangle(ast, options)= -- generates a new AST containing mangled 281 (compressed) variable and function names. It supports the following 282 options: 283 284 - =toplevel= -- mangle toplevel names (by default we don't touch them). 285 - =except= -- an array of names to exclude from compression. 286 287- =pro.ast_squeeze(ast, options)= -- employs further optimizations designed 288 to reduce the size of the code that =gen_code= would generate from the 289 AST. Returns a new AST. =options= can be a hash; the supported options 290 are: 291 292 - =make_seqs= (default true) which will cause consecutive statements in a 293 block to be merged using the "sequence" (comma) operator 294 295 - =dead_code= (default true) which will remove unreachable code. 296 297- =pro.gen_code(ast, options)= -- generates JS code from the AST. By 298 default it's minified, but using the =options= argument you can get nicely 299 formatted output. =options= is, well, optional :-) and if you pass it it 300 must be an object and supports the following properties (below you can see 301 the default values): 302 303 - =beautify: false= -- pass =true= if you want indented output 304 - =indent_start: 0= (only applies when =beautify= is =true=) -- initial 305 indentation in spaces 306 - =indent_level: 4= (only applies when =beautify= is =true=) -- 307 indentation level, in spaces (pass an even number) 308 - =quote_keys: false= -- if you pass =true= it will quote all keys in 309 literal objects 310 - =space_colon: false= (only applies when =beautify= is =true=) -- wether 311 to put a space before the colon in object literals 312 - =ascii_only: false= -- pass =true= if you want to encode non-ASCII 313 characters as =\uXXXX=. 314 315*** Beautifier shortcoming -- no more comments 316 317The beautifier can be used as a general purpose indentation tool. It's 318useful when you want to make a minified file readable. One limitation, 319though, is that it discards all comments, so you don't really want to use it 320to reformat your code, unless you don't have, or don't care about, comments. 321 322In fact it's not the beautifier who discards comments --- they are dumped at 323the parsing stage, when we build the initial AST. Comments don't really 324make sense in the AST, and while we could add nodes for them, it would be 325inconvenient because we'd have to add special rules to ignore them at all 326the processing stages. 327 328** Compression -- how good is it? 329 330(XXX: this is somewhat outdated. On the jQuery source code we beat Closure 331by 168 bytes (560 after gzip) and by many seconds.) 332 333There are a few popular JS minifiers nowadays -- the two most well known 334being the GoogleClosure (GCL) compiler and the YUI compressor. For some 335reason they are both written in Java. I didn't really hope to beat any of 336them, but finally I did -- UglifyJS compresses better than the YUI 337compressor, and safer than GoogleClosure. 338 339I tested it on two big libraries. [[http://www.dynarchlib.com/][DynarchLIB]] is my own, and it's big enough 340to contain probably all the JavaScript tricks known to mankind. [[http://jquery.com/][jQuery]] is 341definitely the most popular JavaScript library (to some people, it's a 342synonym to JavaScript itself). 343 344I cannot swear that there are no bugs in the generated codes, but they 345appear to work fine. 346 347Compression results: 348 349| Library | Orig. size | UglifyJS | YUI | GCL | 350|------------+------------+----------+----------------+------------------------| 351| DynarchLIB | 636896 | 241441 | 246452 (+5011) | 240439 (-1002) (buggy) | 352| jQuery | 163855 | 72006 | 79702 (+7696) | 71858 (-148) | 353 354UglifyJS is the fastest to run. On my laptop UglifyJS takes 1.35s for 355DynarchLIB, while YUI takes 2.7s and GCL takes 6.5s. 356 357GoogleClosure does a lot of smart ass optimizations. I had to strive really 358hard to get close to it. It should be possible to even beat it, but then 359again, GCL has a gazillion lines of code and runs terribly slow, so I'm not 360sure it worths spending the effort to save a few bytes. Also, GCL doesn't 361cope with =eval()= or =with{}= -- it just dumps a warning and proceeds to 362mangle names anyway; my DynarchLIB compiled with it is buggy because of 363this. 364 365UglifyJS consists of ~1100 lines of code for the tokenizer/parser, and ~1100 366lines for the compressor and code generator. That should make it very 367maintainable and easily extensible, so I would say it has a good place in 368this field and it's bound to become the de-facto standard JS minifier. And 369I shall rule the world. :-) Use it, and *spread the word*! 370 371** Bugs? 372 373Unfortunately, for the time being there is no automated test suite. But I 374ran the compressor manually on non-trivial code, and then I tested that the 375generated code works as expected. A few hundred times. 376 377DynarchLIB was started in times when there was no good JS minifier. 378Therefore I was quite religious about trying to write short code manually, 379and as such DL contains a lot of syntactic hacks[1] such as “foo == bar ? a 380= 10 : b = 20”, though the more readable version would clearly be to use 381“if/else”. 382 383Since the parser/compressor runs fine on DL and jQuery, I'm quite confident 384that it's solid enough for production use. If you can identify any bugs, 385I'd love to hear about them ([[http://groups.google.com/group/uglifyjs][use the Google Group]] or email me directly). 386 387[1] I even reported a few bugs and suggested some fixes in the original 388 [[http://marijn.haverbeke.nl/parse-js/][parse-js]] library, and Marijn pushed fixes literally in minutes. 389 390** Links 391 392- Project at GitHub: [[http://github.com/mishoo/UglifyJS][http://github.com/mishoo/UglifyJS]] 393- Google Group: [[http://groups.google.com/group/uglifyjs][http://groups.google.com/group/uglifyjs]] 394- Common Lisp JS parser: [[http://marijn.haverbeke.nl/parse-js/][http://marijn.haverbeke.nl/parse-js/]] 395- JS-to-Lisp compiler: [[http://github.com/marijnh/js][http://github.com/marijnh/js]] 396- Common Lisp JS uglifier: [[http://github.com/mishoo/cl-uglify-js][http://github.com/mishoo/cl-uglify-js]] 397 398** License 399 400UglifyJS is released under the BSD license: 401 402#+BEGIN_EXAMPLE 403Copyright 2010 (c) Mihai Bazon <mihai.bazon@gmail.com> 404Based on parse-js (http://marijn.haverbeke.nl/parse-js/). 405 406Redistribution and use in source and binary forms, with or without 407modification, are permitted provided that the following conditions 408are met: 409 410 * Redistributions of source code must retain the above 411 copyright notice, this list of conditions and the following 412 disclaimer. 413 414 * Redistributions in binary form must reproduce the above 415 copyright notice, this list of conditions and the following 416 disclaimer in the documentation and/or other materials 417 provided with the distribution. 418 419THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER “AS IS” AND ANY 420EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 421IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 422PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE 423LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 424OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 425PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 426PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 427THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 428TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 429THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 430SUCH DAMAGE. 431#+END_EXAMPLE