ajaxmin Wiki Rss Feed

Updated Wiki: EncoderFallbacks

ronlo — Sat, 18 May 2013 01:04:30 GMT

Writing Files with the Encoder Fallbacks

If you are using the DLL version of the Microsoft Ajax Minifier, you might have noticed that it does not include any file input or output functionality. The DLL only works with in-memory strings. Your application will have to handle reading from or writing to the hard drive. You don’t really need to do anything special to read JavaScript or CSS files. Simply use the .NET StreamReader class (System.IO namespace) or any other existing file-reading methodology, although you may have to provide the appropriate Encoding object if it’s not readily determined by the file content itself. Writing files, however may or may not be a little more complicated. If your JavaScript doesn’t contain anything outside of the normal ASCII range, then you don’t really need to do anything special. Or if you are writing files in the UTF-8 or UTF-16 character encodings, you also don’t really need to do anything special. The complication arises if you want to write in a different encoding, and if your code contains characters that can’t be represented in that encoding.

Take, for example, this JavaScript snippet:

alert("你好！")

It’s simple, but it contains UNICODE Chinese characters. The string representation of this code is twelve characters long, and the code points are:

0061

006c

0065

0072

0074

0028

0022

4f60

597d

ff01

0022

0029

If you write an overly-simple block of code to utilize the StreamWriter class to write this string (in the minifiedCode variable) like so, you will create a file encoded as UTF-8 (the default encoding for StreamWriter):

using (var writer = new StreamWriter(@"c:\test.js"))
{
    writer.Write(minifiedCode);
}

If you open the file up in a binary editor, you will see the characters have been written in eighteen bytes:

e4 bd a0

e5 a5 bd

ef bc 81

The Chinese characters have each been encoded into three-byte UTF-8 sequences. The beauty of this is that UTF-8 can represent any character in the UNICODE character set, which is essentially every character you will really want to use on a computer. Nothing special needs to be done with this file, because browsers and any other tools that might want to read it back (like AjaxMin) will correctly read and decode the UTF-8 characters. Loading this file up in Internet Explorer, for example, will get you the original text:

alert("你好！")

That’s all fine and dandy, but what if you want to save your files in another text encoding, say, ASCII or Big-5? Well, let’s assume we want to write this JavaScript code as an ASCII file. Obviously the ASCII character set does not include the Chinese characters in our code snippet. If we do the wrong thing, and simply pass in the default ASCII encoder to the StreamWriter constructor, you will lose your Chinese characters:

using (var writer = new StreamWriter(@"c:\test.js", false, Encoding.ASCII))
{
    writer.Write(minifiedCode);
}

That code produces a file with twelve bytes, and the three Chinese characters will all be changed into question-marks (0x3F). Probably not what you want. To handle characters outside the encoding scheme, you need to use an EncoderFallback class. To make a long story short, an Encoder Fallback is called whenever a text encoding object is asked to write a character that isn’t in the destination encoding. The default fallback is to simply write a question mark (hence the lost Chinese characters). Microsoft Ajax Minifier provides two Encoder Fallback classes for use in your code: JSEncoderFallback for JavaScript and CssEncoderFallback for CSS. All they do is take the character that cannot be displayed in whatever output encoding you are using, and escape it as appropriate for the particular language. For instance, characters in JavaScript are encoded with the UNICODE escape sequence: \uXXXX if the character is in the standard 16-bit UNICODE range, and as the surrogate pair \uUUUU\uLLLL if the character is in the extended UNICODE range (all digits in hexadecimal). For CSS code, the escape sequence is \XXXXXX, consisting of up to six hexadecimal digits; if less than six digits are needed, a space character is appended to signify the end of the escape sequence.

Now, back to our example. If we want to write the file in the ASCII encoding, we need to clone the default ASCII encoding object and set the EncoderFallback property to an instance of our JSEncodeFallback class. We have to clone the default ASCII encoder because it will throw an exception if you try to set the EncoderFallback property on the default ASCII encoder object proper.

var encoding = (Encoding)Encoding.ASCII.Clone();
encoding.EncoderFallback = new JSEncoderFallback();
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

Now when we write our sample code, we will get the following ASCII text:

alert("\u4f60\u597d\uff01")

Loading that code in a browser that executes the code will get you the desired alert box:

There are only a handful of default encoders that you can clone. If you want to encode your output in a different encoding, then I would suggest using the Encoding.GetEncoding method, passing in the name of the desired encoding:

var encoding = Encoding.GetEncoding(
    "iso-8859-1",
    JSEncoderFallback(),
    new DecoderReplacementFallback("?"));
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

The encoding names you can use are defined in the Info.Name column of the data table on this MSDN page. For example, if you want to encode your output in the Big-5 encoding scheme, pass “big5” to the GetEncoding method.

Generally speaking it’s always a good idea to use an encoding object with the appropriate AjaxMin-provided EncoderFalback object whenever writing JS or CSS code, regardless of what encoding scheme you are using or whether or not your code contains special characters. Using the provided EncoderFallback objects will always generate the proper JavaScript or CSS code.

What If I Just Want A JS-Encoded Encoded String?

That is also easily handled, but it will take a little more work. What we need to do is write the minified code (internally stored by .NET as a UNICODE string) to an array of ASCII-encoded bytes using an instance of JSFallbackEncoder, and then read those bytes back into a .NET string using a StreamReader. For instance, you could define a function like this:

private static string GetAsciiEncodedOutput(string minified)
{
    var encoder = (Encoding)Encoding.ASCII.Clone();
    encoder.EncoderFallback = new Microsoft.Ajax.Utilities.JSEncoderFallback();
    var encodedBytes = encoder.GetBytes(minified);

    using (var memoryStream = new MemoryStream(encodedBytes))
    {
        using (var reader = new StreamReader(memoryStream))
        {
            return reader.ReadToEnd();
        }
    }
}

Updated Wiki: EncoderFallbacks

ronlo — Sat, 18 May 2013 01:03:34 GMT

Writing Files with the Encoder Fallbacks

Take, for example, this JavaScript snippet:

alert("你好！")

It’s simple, but it contains UNICODE Chinese characters. The string representation of this code is twelve characters long, and the code points are:

0061

006c

0065

0072

0074

0028

0022

4f60

597d

ff01

0022

0029

using (var writer = new StreamWriter(@"c:\test.js"))
{
    writer.Write(minifiedCode);
}

If you open the file up in a binary editor, you will see the characters have been written in eighteen bytes:

e4 bd a0

e5 a5 bd

ef bc 81

alert("你好！")

using (var writer = new StreamWriter(@"c:\test.js", false, Encoding.ASCII))
{
    writer.Write(minifiedCode);
}

var encoding = (Encoding)Encoding.ASCII.Clone();
encoding.EncoderFallback = new JSEncoderFallback();
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

Now when we write our sample code, we will get the following ASCII text:

alert("\u4f60\u597d\uff01")

Loading that code in a browser that executes the code will get you the desired alert box:

var encoding = Encoding.GetEncoding(
    "iso-8859-1",
    JSEncoderFallback(),
    new DecoderReplacementFallback("?"));
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

What If I Just Want A JS-Encoded Encoded String?

private static string GetAsciiEncodedOutput(string minified)
{
    var encoder = (Encoding)Encoding.ASCII.Clone();
    encoder.EncoderFallback = new Microsoft.Ajax.Utilities.JSEncoderFallback();
    var encodedBytes = encoder.GetBytes(minified);

    using (var memoryStream = new MemoryStream(encodedBytes))
    {
        using (var reader = new StreamReader(memoryStream))
        {
            return reader.ReadToEnd();
        }
    }
}

Updated Wiki: EncoderFallbacks

ronlo — Sat, 18 May 2013 01:03:03 GMT

Writing Files with the Encoder Fallbacks

Take, for example, this JavaScript snippet:

alert("你好！")

It’s simple, but it contains UNICODE Chinese characters. The string representation of this code is twelve characters long, and the code points are:

0061

006c

0065

0072

0074

0028

0022

4f60

597d

ff01

0022

0029

using (var writer = new StreamWriter(@"c:\test.js"))
{
    writer.Write(minifiedCode);
}

If you open the file up in a binary editor, you will see the characters have been written in eighteen bytes:

e4 bd a0

e5 a5 bd

ef bc 81

alert("你好！")

using (var writer = new StreamWriter(@"c:\test.js", false, Encoding.ASCII))
{
    writer.Write(minifiedCode);
}

var encoding = (Encoding)Encoding.ASCII.Clone();
encoding.EncoderFallback = new JSEncoderFallback();
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

Now when we write our sample code, we will get the following ASCII text:

alert("\u4f60\u597d\uff01")

Loading that code in a browser that executes the code will get you the desired alert box:

var encoding = Encoding.GetEncoding(
    "iso-8859-1",
    JSEncoderFallback(),
    new DecoderReplacementFallback("?"));
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

What If I Just Want A JS-Encoded Encoded String?

private static string GetAsciiEncodedOutput(string minified)
{
    var encoder = (Encoding)Encoding.ASCII.Clone();
    encoder.EncoderFallback = new Microsoft.Ajax.Utilities.JSEncoderFallback();
    var encodedBytes = encoder.GetBytes(minified);

    using (var memoryStream = new MemoryStream(encodedBytes))
    {
        using (var reader = new StreamReader(memoryStream))
        {
            return reader.ReadToEnd();
        }
    }
}

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:19:10 GMT

Overview

There are two types of XML files that can be used as input to the command-line version of the Microsoft Ajax Minifier. The first specifies input and output files and is called a manifest file; the second specified rules for renaming variable, properties, and functions.

Technically, both sets of information can be specified in the same file. The root element is ignored and can use any element name at all (although there has to be a single root element for the file to be valid XML). The “input” functionality simply looks for all descendent elements of type <output> and operates on them. The “naming” functionality simply looks for descendent elements of type <rename> and <norename>. All three of these elements can exist under the root elements, and the same XML file can be specified in both the –rename and –xml switches.

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

The simplest version of a manifest file has a root element that contains one or more <output> elements. Each <output> element may contain one or more <input> elements. The <output> element specifies an output file (the OFILE in the mandatory “path” attribute), and the containing <input> elements specify the source file(s) (the IFILE in the mandatory “path” attribute) to use to create the output.

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

But the manifest file can do even more. For example, the root element may contain an <arguments> element, which has a string value of switches that is parsed to create the default settings to use when generating each <output> file. Each <output> element can also contain an <arguments> element to specify settings that are laid on top of the default settings specified at the root.

<arguments> Elements

There are no required attributes for the <arguments> element, and it only contains a single text string that is parsed as command-line switches for either the entire set (if a child of the root element) or the specific output file (if a child of an <output> element).

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

The .targets file supplied with Microsoft Ajax Minifier passes the build configuration to the build task. If the <arguments> element includes a “config” attribute, only the arguments that match the current build configuration will be used. In this way, separate Debug and Release options can be specified in your manifest file:

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

The <output> elements have a required “path” attribute (as previously mentioned), but can also specify the output encoding via an optional “enc” attribute with a value consistent with the –enc switch. The type of the output file (JavaScript or StyleSheet") can either be determined by the extensions of the input files, or if they are inconclusive or non-standard, the <output> element can have a “type” attribute with a value of “JS” or “CSS.”

Inside the <output> element are one or more required <input> elements, as previously mentioned. But it can also contain an <arguments> element, any number of <rename> elements, any number of <norename> elements, an optional <symbolMap> element, and any number of <resource> elements.

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

The <input> elements must have a required “path” attribute that points to the input file. It can also have an optional “enc” attribute that can specify one of the supported .NET text encoding names to use to read that input file. It can also have an “optional” attribute. If no “optional” attribute is specified, the file is considered required and an error will be thrown if it doesn’t exist. But if the value of the “optional” attribute is “true,” no error will be thrown if the input files doesn’t exist.

<input path="inputfile.js" enc="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

External files will be minified independently, by themselves, and internal or project files will be minified after concatenating adjacent non-external files. The results will all be concatenated together into the resulting output file in the given <input> element order. External files therefore must be valid syntax on their own; individual project files may be partial syntax, as long as result of concatenating the adjacent non-project files is valid syntax.

<rename> Elements

The <rename> element contains two required attributes: “from” and “to.” What this element does is create a renaming pair – any variables with a name equal to the “from” attribute value will be renamed to the value of the “to” variable (assuming they are both valid JavaScript identifier names).

<rename from="fromName" to="toName" />

<norename> Elements

The <norename> element contains a single required attribute, “name”. This element specifies that any variables with a name equal to the “name” attribute value will not be automatically renamed. The attribute “id” may be substituted for “name.”

<norename name="$" />

<symbolMap> Elements

The <symbolMap> element will cause a symbol map to be created for the containing output file. The element contains a single required attribute, “path,” which specifies the output of the symbol map file. By default, the XML source map file format is generated. If the V3 JSON source map format is desired, the “name” attribute should also be specified, with the value “V3”. The only two allowed values for the name are “v3” or “xml” (case-insensitive).

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

An <output> element may also contain zero or more <resource> elements that specify .RESX or .RESOURCES files (the RFILE in the mandatory “path” attribute) from which localized strings can be pulled. The object to look for in the sources is specified by the optional “name” attribute, and must be a valid JavaScript identifier (IDENT); if the “name” attribute is not specified, the identifier “Strings” is assumed. For example, given the element:

<resource path="MYLOC.RESX" name="MyLoc" />

Then whenever the member lookup MyLoc.Foo is encountered in the sources, the string in the file MYLOC.RESX with the name “Foo” is looked up, and MyLoc.IDENT is replaced with that string literal. If there is no string in MYLOC.RESX with the name “Foo”, then the member lookup is replaced with an empty string literal.

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

This file can be used with the –rename switch of the EXE program. The root element can contain zero or more <rename> elements, and zero or more <norename> elements. The <rename> element specifies identifier names in the source (the IDENT in the mandatory “from” attribute) that should be renamed (to the IDENT in the mandatory “to” attribute). The <norename> element specifies certain identifiers (the IDENT in the mandatory “id” attribute) which should not be automatically renamed. IDENT is always a valid case-sensitive JavaScript identifier.

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:16:48 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<input path="jquery-2.0.0.min.js" origin="external" />

External files will be minified by themselves, and internal or project files will be minified after concatenating adjacent non-external files. The results will all be concatenated together into the resulting output file in the given <input> element order.

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:16:28 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:15:49 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:15:27 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:14:37 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:14:12 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:13:57 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:12:42 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: XML File Formats

ronlo — Wed, 08 May 2013 00:10:51 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>

Updated Wiki: CSS3Support

ronlo — Tue, 07 May 2013 23:45:38 GMT

AjaxMin CSS3 Support

CSS3 is an evolving standard. As such, AjaxMin does not claim to have 100% support for CSS3 syntax. However, as I read the CSS3 specifications on http://w3.org, many of the new CSS3 syntax is merely the definition of new properties and values using standard CSS syntax. As such, AjaxMin will support the majority of common CSS3 code. The questionable area is when the new CSS3 rules create new syntax – mostly in the area around new at-keywords. Whenever there is a new at-keyword (for example, @top-margin or @keyframes), AjaxMin need to adjust its parser to understand the new syntax. By default, AjaxMin may output new at-keywords just fine, except for a warning message if the warning level is turned up high enough. If you are using a CSS3 at-keyword (or any other syntax for that matter) that is not supported by AjaxMin, please file an Issue on this site and I’ll address it as soon as possible.

Given that, there are a number of specifications that I believe are fully supported, and a couple that are either partially supported, or are in a state such that I think they may be supported by AjaxMin, but not entirely sure.

Supported CSS3 Specifications

CSS3 Syntax: http://www.w3.org/TR/css3-syntax/
Selectors Level 3: http://www.w3.org/TR/selectors/
Media Queries: http://www.w3.org/TR/css3-mediaqueries/
CSS Animations Module Level 3: http://www.w3.org/TR/css3-animations/
Color Module Level 3: http://www.w3.org/TR/css3-color/
CSS Namespaces Module: http://www.w3.org/TR/css3-namespace/

Partially-Supported CSS3 Specifications

CSS3 Paged Media: http://www.w3.org/TR/css3-page/
CSS Values and Units Module Level 3: http://www.w3.org/TR/css3-values/
CSS Fonts Module Level 3: http://www.w3.org/TR/css3-fonts/

If any of the above specifications are not fully supported by AjaxMin and you wish to use those unsupported constructs in your code, please feel free to let us know.

Updated Wiki: EncoderFallbacks

ronlo — Tue, 07 May 2013 23:45:28 GMT

Writing Files with the Encoder Fallbacks

Take, for example, this JavaScript snippet:

alert("你好！")

It’s simple, but it contains UNICODE Chinese characters. The string representation of this code is twelve characters long, and the code points are:

0061

006c

0065

0072

0074

0028

0022

4f60

597d

ff01

0022

0029

using (var writer = new StreamWriter(@"c:\test.js"))
{
    writer.Write(minifiedCode);
}

If you open the file up in a binary editor, you will see the characters have been written in eighteen bytes:

e4 bd a0

e5 a5 bd

ef bc 81

alert("你好！")

using (var writer = new StreamWriter(@"c:\test.js", false, Encoding.ASCII))
{
    writer.Write(minifiedCode);
}

var encoding = (Encoding)Encoding.ASCII.Clone();
encoding.EncoderFallback = new JSEncoderFallback();
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

Now when we write our sample code, we will get the following ASCII text:

alert("\u4f60\u597d\uff01")

Loading that code in a browser that executes the code will get you the desired alert box:

var encoding = Encoding.GetEncoding(
    "iso-8859-1",
    JSEncoderFallback(),
    new DecoderReplacementFallback("?"));
using (var writer = new StreamWriter(@"c:\test.js", false, encoding))
{
    writer.Write(minifiedCode);
}

Updated Wiki: ConditionalCompilation

ronlo — Tue, 07 May 2013 23:45:16 GMT

Conditional Compilation Comments

JScript implementations in Internet Explorer 4.0 and higher include a preprocessor-style language syntax called conditional compilation comments. No other browsers support conditional compilation comments, so anything you do with this is pretty much restricted to IE-only. The syntax is pretty simple:

/*@ multiLine @*/
//@ singleLine

There are only three conditional compilation statements: @cc_on, @if, and @set. These statements don’t have to be within conditional-compilation comments, but if you have them outside the comments, you guarantee that your code will throw script errors in non-IE browsers. It is very important to note that conditional compilation comments are ignored until conditional compilation is first turned on. The best way to turn it on is with the @cc_on statement:

//@cc_on

It’s a good idea to put that near the top of your code if you’re going to use a lot of conditional compilation comments later. The other way to turn this feature on is to have an @if or @set statement outside of comments; but again, that makes your code unusable in non-IE browsers so I don’t recommend it.

The @if statement has more in common with certain other languages than it does JavaScript. The bare minimum is the @if keyword, a parenthesized condition, a block of statements to execute if the condition clause is true, and an @end statement to close it all out. There can be zero or more optional @elif clauses (each with their own parenthesized conditions), and an optional @else clause.

/*@if (condition)
    // true statements
@elif(condition)
    // else-if statements
@else@*/
    // else statements
/*@end@*/

Notice how I closed the conditional comment after the @else keyword and started it up and closed it around the @end? That is a common pattern that allows the @if and @elif clauses to execute in IE for the appropriate conditions while being ignored by other browsers (because they think it’s all a big comment), but still leaves the @else block for non-IE browsers (and any IE browsers that don’t meet any of the previous conditions).

There are a bunch of useful pre-defined conditional compilation variables you can use in your conditions, but you can also set your own variables using the @set statement:

//@set @myvar = 42

Custom conditional compilation variables have limited usefulness: they can only have numeric or Boolean values (no strings) and they are pretty much only good within other conditional compilation comments. Another thing to keep in mind is that if you assign an expression to the variable, it needs to be placed inside parentheses:

//@set @othervar = (@_jscript_build * 1000)

However, this isn’t going to be a tutorial on how to write great code using conditional compilation on IE. Please go to MSDN if you want to learn more, or just Bing it.

Using Conditional Compilation with Ajax Minifier

In general, AjaxMin only supports statement-level conditional compilation comments. That means the conditional compilation comment needs to be at the start of a new statement, and can contain only whole statements. For instance:

var a = 10;
/*@cc_on@if(@_jscript_version > 5.6)
    alert("IE7 or higher");
@else@*/
    alert("non-IE [or IE6 or earlier]");
//@end
alert(a);

Stick to that pattern and you should be just fine. If any conditional compilation comments are encountered in situations that are not explicitly noted here, they will be ignored. This is important! AjaxMin will throw a warning whenever it encounters a conditional compilation comment that it ignores, but the severity will be sufficiently low to not show up by default unless you bump the warning level (or use the –analyze switch). When developing your application, I strongly urge you to use the –analyze switch to catch errors in your code.

Special-Case Exceptions

In all honesty, I’m a bit of a JavaScript purist and don’t particularly care for JScript conditional-compilation. However, it can be useful sometimes as a super-easy and 100% effective way of determining if you are running in Internet Explorer, since it is the only browser that supports this syntax. Relying on things like document.all or [heaven forbid] user-agent sniffing can sometimes give you the wrong answer. As such, there are a couple nifty ways to use conditional compilation that are special-cased within AjaxMin.

First off, inside a var-statement, you can use conditional compilation around the assignment operator and the initializing expression. For example:

var isIE/*@cc_on=1@*/;

After this statement is executed, the variable “isIE” will be 1 (true-equivalent) for Internet Explorer browsers, and undefined (false-equivalent) if not. You can then do something like the following:

var isIE/*@cc_on=1@*/;
if (isIE)
{
    // ie-specific code
}
else
{
    // non-ie code
}

As of version 4.29, AjaxMin also special-cases the !-operator (logical not) if – and only if – it is the only thing within the conditional comment (other than an optional initial @cc_on statement). You could therefore write something like this:

if (/*@cc_on!@*/0)
{
    // ie-specific code
}
else
{
    // non-ie code
}

Other than those instances, sticking to statement-level conditional-compilation statements is the way to go, if you absolutely need to use them.

Updated Wiki: Problems with Evals

ronlo — Tue, 07 May 2013 23:45:05 GMT

Problems with Evals

Eval-statements provide a special kind of problem for script minifiers. For the most part, there are very few things you can do with an eval-statement that you can’t do some other, safer way. Two examples are:

generating a JS object from a JSON string in older browsers that don’t support the JSON object, and
wrapping modern syntax not supported on older browsers you have still to support with your code.

For an example of the latter, if you need to support WebTV (for example) and you need to use a try/catch statement in your code, you’re pretty much out of luck because the try/catch statement itself isn’t supported on that older platform and will throw a script error when your code is parsed. Instead, you’ll have to carefully wrap your code in an eval-statement so it will parse, and try to make sure it doesn’t actually get called for WebTV clients.

Other than those two examples, there really aren’t a lot of good reasons to use eval-statements. As Douglas Crockford has said: “eval is evil.” But people do use them sometimes. AjaxMin by default, does not treat eval-statements any differently than any other code. That may seem like a dangerous stand to take, but I totally agree with Crockford and think eval-statements should be avoided if at all possible. By taking this stand I am hoping to force developers to realize their code has eval-statements in it and consider them more closely and conscientiously. If you don’t use any eval-statements, or use an eval-statement only for something like JSON evaluation, you should not have any problems with AjaxMin. If you use eval-statements for any other purpose and reference local variables and/or function names within the evaluated string, then your minified code may break and you will need to either change your code to not use an eval-statement, or fall back to using a different eval-mode using the –evals command-line switch (or the CodeSettings.EvalTreatment property if you are using the DLL version).

The primary reason I don’t like eval-statements is simple run-time performance. Whenever an eval-statement is executed, a JavaScript parser needs to get spun up and parse the source string before it can be executed. That is not a free exercise. If you want your code to operate efficiently and quickly, parsing and reparsing is not going to help you out.

And don’t forget that there are more ways to execute an “eval” than just calling the eval function. The Function object constructor is an implicit eval – it has to parse and execute the strings passed to it in order to create the function object. Passing strings to setTimeout and setInterval also perform an implicit eval – every time the timer fires, the strings have to be reparsed before they can be executed. Try to avoid these situations if possible; there usually is a much cleaner way to do the same thing.

There are a few common eval-statement patterns I see in JavaScript that always make me cry when I read them. I have only come across a tiny handful of situations where an eval-statement seems like a good idea; the vast majority of times it’s just bad coding. For instance, I see things like this a lot (and I’m pretty sure puppies somewhere die whenever code like this is released to the web):

function foo(obj, prop)
{
    return eval("obj." + prop);
}

For the love of Pete, please don’t ever do that. JavaScript properties can be accessed multiple ways, and if you don’t know the name of the property at compile-time, use the []-operator:

function foo(obj, prop)
{
    return obj[prop];
}

I also frequently see people using string arguments to setTimeout when they want to pass parameters to the function that gets called when the timeout fires. As with most other cases of eval-statement usages, there is a better way. If you don’t understand JavaScript closures very well, I strongly suggest you Bing “JavaScript closures” right now and do a little reading. They are what make JavaScript a powerful programming language, and a thorough understanding of how they work will save you a lot of time and many headaches. Anyhow, let’s get to an example. Instead of:

function foo(n, v)
{
    alert(n + ": " + v);
}
var name, val;
// set name and val somehow
window.setTimeout("foo('" + name + "', '" + val + "')", 2000);

code it like:

function foo(n, v)
{
    alert(n + ": " + v);
}
var name, val;
// set name and val somehow
window.setTimeout(function(){foo(name, val)}, 2000);

I won’t get into the details of how closures work in this article, but calling setTimeout this way will call your function with the proper parameters when the timeout fires without having to fire up the JavaScript parser again -- and you won’t have to worry about any syntax errors should the name or value variables point to a string that contains single-quotes! Of course, this sample is a little contrived; it might be better to just inline the target function altogether. It all really depends upon your situation. The point being the use of closures in situations like this will greatly help your application.

What To Do?

Okay, so let’s say you need to use eval-statements in your code, but when you minify it with AjaxMin, your application breaks. What do you do? You need to specify a different “Eval Treatment” mode. There are three values you can specify with the –evals switch:

-evals:ignore
-evals:immediate
-evals:safeall

The first is the default: ignore them and treat them like any other statement and hope for the best. The second one will make sure that variables and functions within the same scope as the eval-statement are not renamed, so if the eval-statement doesn’t reference anything in a parent scope, it shouldn’t run into any problems. The last one is the nuclear-option: no variables or function will be renamed or removed not only in the current scope, but also all parent scopes up the chain to the global scope. Use this option only if you need it, because it could result in a minified result much larger than it needs to be. But it should always work.

Of course, I’ll say it again: the best option is to not use eval-statements at all.

Updated Wiki: AjaxMinTask

ronlo — Tue, 07 May 2013 23:44:35 GMT

Using the Supplied AjaxMinTask.dll In Your Project

Part of the Microsoft Ajax Minifier install package is an MSBuild task that can imported and used in your Visual Studio projects to automatically minify your JS and CSS files. The files you need are installed into the <PROGRAMFILES>\MSBuild\Microsoft\MicrosoftAjax folder via the MSI installer. You can either work from scratch and edit your .csproj file to work with wildcard .JS and/or .CSS files as described below, or you can use an Ajax Minifier Manifest File and the associated Manifest Build Task. These instructions assume that the Microsoft Ajax Minifier has been installed via the MSI download from the CodePlex website.

To automatically minify your JS and CSS, right-click on your project in the Solution Explorer and select “Unload Project” from the context menu. Right-click on it again, and select the “Edit” option from the context menu; this will open your project file in an XML editor. Scroll down to the bottom of the file and add the following XML:

    <Import Project="$(MSBuildExtensionsPath)\Microsoft\MicrosoftAjax\AjaxMin.tasks" />

    <Target Name="AfterBuild">

        <ItemGroup>

            <JS Include="**\*.js" Exclude="**\*.min.js;Scripts\*.js" />

        </ItemGroup>

        <ItemGroup>

            <CSS Include="**\*.css" Exclude="**\*.min.css" />

        </ItemGroup>

        <AjaxMin

            JsSourceFiles="@(JS)"  JsSourceExtensionPattern="\.js$" JsTargetExtension=".min.js"

            CssSourceFiles="@(CSS)" CssSourceExtensionPattern="\.css$" CssTargetExtension=".min.css"  />

    </Target>

You can also check the AjaxMinTask.dll into your project and use the <UsingTask> element instead of the <Import> element. For example, if you create a “Build” folder under your project and check the AjaxMinTask.dll into that folder, you can add this element instead of the <Import> element above:

<UsingTask TaskName="AjaxMin" AssemblyFile="$(MSBuildProjectDirectory)\Build\AjaxMinTask.dll" />

Many of the code settings that can be set using the CodeSettings object can also be set in your project file tasks. For example, to specify a set of known global identifiers (similar to the –global switch or the KnownGlobalNamesList property), use the JsKnownGlobalNames attribute on the <AjaxMin> element:

<AjaxMin JsKnownGlobalNames="jQuery,$" JsEvalTreatment="MakeImmediateSafe"

    JsSourceFiles="@(JS)"  JsSourceExtensionPattern="\.js$" JsTargetExtension=".min.js"

    CssSourceFiles="@(CSS)" CssSourceExtensionPattern="\.css$" CssTargetExtension=".min.css"  />

Once you have imported the task, there are many ways to set up your build system to do what you want to do with your CSS and JS files. Alexander Turlov posted an interesting article on how he integrated Ajax Minifier to his project to copy the sources to an output folder and minify them in-place.

An even easier method of specifying AjaxMin switches in your build task is to use a command-line string in the Switches parameter. Not all command-line switches are supported in the build task, however. One notable example is the –xml switch. The following example would be the equivalent to the previous example:

<AjaxMin Switches="-global:jQuery,$ –evals:immediate"

    JsSourceFiles="@(JS)"  JsSourceExtensionPattern="\.js$" JsTargetExtension=".min.js"

    CssSourceFiles="@(CSS)" CssSourceExtensionPattern="\.css$" CssTargetExtension=".min.css"  />

Another option for the task is to combine all the JS source files into a single minified file. Instead of specifying the JsSourceExtensionPattern/JsTargetExtension pair, specify the JsCombinedFileName attribute and all the source files will be concatenated together, minified, and written to the file named by the JsCombinedFileName attribute. Same goes for the CssSourceExtensionPatter/CssTargetExtension pair and the new CssCombinedFileName attribute:

  <AjaxMin Switches="-global:jQuery,$"
      JsSourceFiles="@(JS)"  JsCombinedFileName="Combined.min.js"
      CssSourceFiles="@(CSS)" CssCombinedFileName="Combined.min.css"  />

Updated Wiki: AjaxMin DLL

ronlo — Tue, 07 May 2013 23:44:25 GMT

AjaxMin.DLL

The Microsoft Ajax Minifier also provides a DLL that can be used in your own applications. Classes are defined in the Microsoft.Ajax.Utilities namespace. There are two main ways to access the functionality.

Minifier Class

Instantiate the Minifier class and call either the MinifyJavaScript or MinifyStyleSheet methods, passing in the source to be minified as a string value. The return value from both those functions is the minified code as a string value. If there were any errors or warnings minifying your code, they will be in the ErrorList property, which is an ICollection<ContextError>. This is the simplest way to minify your sources using the DLL.

using System;

using System.IO;

using Microsoft.Ajax.Utilities;

namespace AjaxMinSample

{

    class Program

    {

        static void Main(string[] args)

        {

            if (args.Length == 1)

            {

                string source;

                using (var inputFile = new StreamReader(args[0]))

                {

                    source = inputFile.ReadToEnd();

                }

                var minifier = new Minifier();

                Console.WriteLine(minifier.MinifyJavaScript(source));

                foreach (var error in minifier.ErrorList)

                {

                    Console.Error.WriteLine(error.ToString());

                }

            }

        }

    }

}

CssSettings

The MinifyStylesheet method can optionally take a CssSettings object to specify various CSS minification settings. There are two ways to generate one: manually, by creating a default CssSettings object and then setting all properties you wish to change from the default settings, or by creating an instance of the SwitchParser object, parsing a command-line switch by calling the Parse method on that object, and then passing the generated CssSettings property as the second parameter to the MinifyStylesheet method.

var switchParser = new SwitchParser();
switchParser.Parse("-css:decls -colors:hex");
var minifier = new Minifier();
var minifiedStyle = minifier.MinifyStyleSheet(styleAttrValue, switchParser.CssSettings);

CodeSettings

The MinifyJavaScript method can optionally take a CodeSettings object to specify various JavaScript minification settings. The JSParser object’s Parse method must be passed a CodeSettings object. There are two ways to generate one: manually, by creating a default CodeSettings object and then setting all properties you wish to change from the default settings, or by creating an instance of the SwitchParser object, parsing a command-line switch by calling the Parse method on the object, and then passing the generated JSSettings property as the second parameter to the MinifyJavaScript method, or as the only parameter to the Parse method on the JSParser object.

JSParser Classes

If you wish to take advantage of the JavaScript parser and examine and/or manipulate the resulting abstract syntax tree (AST), you can instantiate an object of the type JSParser, and utilize its methods and properties directly. The main advantage here is that the parser returns an object of type Block that represents the top-level set of statements for the input script. It is then possible to traverse the tree, delete nodes, add nodes, move them around, rename variables – anything is possible once you have the AST. And once you are done, simply call the ToCode method on the Block object returned from the parser to get the resulting JavaScript code.

using System;

using System.IO;

using Microsoft.Ajax.Utilities;

namespace AjaxMinSample

{

    class Program

    {

        static void Main(string[] args)

        {

            if (args.Length == 1)

            {

                string source;

                using (var inputFile = new StreamReader(args[0]))

                {

                    source = inputFile.ReadToEnd();

                }

                JSParser parser = new JSParser(source);

                parser.CompilerError += ErrorHandler;

                CodeSettings settings = new CodeSettings();

                Block block = parser.Parse(settings);

                Console.WriteLine(block.ToCode());

            }

        }

        static void ErrorHandler(object source, JScriptExceptionEventArgs ea)

        {

            Console.Error.WriteLine(ea.Error.ToString());

        }

    }

}

AST Traversal

If you would like to traverse the entire tree from root to leaf, you could start with the Block object and simply iterate over all the nodes in the Children collection recursively:

        static void IterateChildren(AstNode node)

        {

            foreach (var child in node.Children)

            {

                IterateChildren(child);

            }

        }

Or you can use a Visitor pattern. Define a new class derived from the Microsoft.Ajax.Utilities.TreeVisitor class. There are a number of virtual methods on TreeVisitor – one for each concrete AST node type – that can be overridden. The base TreeVisitor class methods simply iterates over the node’s children nodes. For example, if the desire it to iterate over all the nodes in the tree and print out the name of all variables defined in var statements, a visitor can be define like this:

    class MyVisitor : TreeVisitor

    {

        public MyVisitor() { }

        public override void Visit(VariableDeclaration node)

        {

            base.Visit(node);

            Console.WriteLine(node.Identifier);

        }

    }

To execute the visitor, instantiate an object and pass the Block node to the Visit method:

        var myVisitor = new MyVisitor();

        myVisitor.Visit(block);

Nodes in the AST tree can be created, inserted, replaced, deleted, and modified. Internally Ajax Minifier uses a number of visitor classes to modify the tree for maximum minification.

Unfortunately, currently only JavaScript is parsed into an AST that can be traversed. The CSS syntax tree is not available at this time.

Updated Wiki: XML File Formats

ronlo — Tue, 07 May 2013 23:43:45 GMT

Overview

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

<arguments> Elements

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

<output path="outputfile.js" type="js" enc="utf-16" >
    …
</output>

<input> Elements

<input path="inputfile.js" enc="big5" optional="true" />

<rename> Elements

<rename from="fromName" to="toName" />

<norename> Elements

<norename name="$" />

<symbolMap> Elements

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

<resource path="MYLOC.RESX" name="MyLoc" />

XML Naming File

<root>

    <rename from="IDENT" to="IDENT" />

    <norename id="IDENT" />

</root>