Command-Line Usage

Modified on 2009/12/14 17:22 by Stephen Walther — Categorized as: Uncategorized

Command-Line Usage

Simply running AjaxMin without any parameters, or with the -? or /? switches, will display the command line usage. The bare minimum needed to minify a source file is the input file name:

ajaxmin inputfile.js

The type of minification (JS or CSS) will be switched depending on the file extension of the source file. Alternatively, either the –JS or –CSS switch can be used to explicitly put the tool in one of the two modes. If the combination of switched or input file extensions leads to an ambiguous JS or CSS state, an error will be thrown.

Not specifying an output file will send the minified code to the standard output stream. If you want to save the output directly to a file, use the –OUT option:

ajaxmin inputfile.js –out outputfile.js

By default, if the output file already exists, an error will be thrown and the file will not be over-written. To always write the output file, regardless of whether or not it already exists, use the –CLOBBER switch:

ajaxmin inputfile.js –out outputfile.js –clobber

By default, the tool will rename all local variables and function. If you do not wish to rename any local variables or functions, use the –RENAME option with the “none” value:

ajaxmin –rename:none inputfile.js –out outputfile.js

Another option has to do with a practice here at Microsoft that goes back many years and is supported by localization tools. In this practice, variables that contain strings and other data that need to be localized for different markets and languages have their names prefaced with “L_”. For example, if a message is displayed in an alert box, the code might be written like this:

var L_hello_text = "Hello there! ";
alert(L_hello_text);

Tools can then be employed to search the code for variables that start with “L_”, show them to the localizer (who typically is not a programmer and does not understand JavaScript code), who then translates the string and the tool replaces it in the code. Sites that use this scheme need to keep L_-variable names intact so they can be localized. To keep only those variable names unchanged, specify the “localization” value to the -RENAME parameter:

ajaxmin –rename:localization inputfile.js –out outputfile.js

To generate analysis output on your code in order to find possible bugs earlier in the development process, use the –ANALYZE option. The –GLOBAL option is for specifying known global entities, which is useful when analyzing your code with the –ANALYZE switch: ajaxmin –analyze –global:Msn,jQuery inputfile.js –out outputfile.js

The warning level determines what levels of warnings are displayed when minifying your code. The default warning level is zero, meaning only serious errors are displayed. The -ANALYZE option by default shows all warning levels. The cutoff can be specified manually with the –WARN option. For example, if you wish to analyze your code but don’t want to see the “suggestion” level of warnings (level 4), specify a warning level of 3: ajaxmin inputfile.js –analyze –warn:3 The other options are less used. The -SILENT option is useful only when saving to a file without analyzing and you don’t want any output sent to the standard output stream. The encoding option (-ENC) is for specifying an encoding scheme for input (-ENC:IN) and output (-ENC:OUT) files other than the default of UTF-8 for input and ASCII for output. This mainly affects the way string literals are encoded. With the ASCII encoding scheme, extended characters are encoded such that all browsers can read them. A UNICODE encoding scheme, for example UTF8, would insert actual UNICODE characters directly in the strings.

The –TERM option adds a semicolon to the end of the minified stream. This can be useful if you need to later append multiple minified files together into a single file using a separate process.

The –DEBUG option is for specifying how to handle debug-related statements. By default, AjaxMin will remove debug-related statements: debugger, for instance. Statements constituting calls to the debug namespaces of a couple well-known libraries will also be culled. These namespaces are Web.Debug, Msn.Debug, Debug and $Debug. Calls to the WAssert function will also be stripped. If the calls are part of a constructor, the constructor will be replaced with an Object constructor. For example, this code:

debugger;
Web.Debug.Output("foo");
$Debug.Track("bar");
Debug.fail("debug fail");
WAssert(condition,message);
var wnd = new $Debug.DebugWindow();
Will be reduced to this:
var wnd={};

Notice that the debugger statement and the calls into the debug libraries have been totally removed, and the constructor call replaced with an empty object literal.

In order to mark a block of arbitrary code as debug-only, enclose it in comments of a special format:

///#DEBUG
Code between these two comments will be removed in normal mode,
and only shown when in debug mode
///#ENDDEBUG

The comments are three slashes (/), a pound-sign (#), followed by the word “DEBUG” or “ENDDEBUG” (respectively), with no whitespace between any of them.

To keep the debug statements, specify a Boolean value indicating true (true, t, yes, y, on, or 1) after the –DEBUG switch: ajaxmin –debug:true inputfile.js –out outputfile.js

It is also possible to minify JavaScript sent in from the standard input stream. Microsoft Ajax Minifier will display the usage message if there are no parameters at all, so if you wish to minify from the standard input, at least one optional parameter must be specified.