README
Why Globalize compiler?
Use globalize-compiler (a) to extract your Globalize formatters and parsers statically from your source code and (b) to compile + to bundle them into a JavaScript file.
For information about Globalize, please read its documentation. More specifically, about Performance and Compilation and the Runtime modules.
Usage
CLI
Use the command line interface as a convenience over using the API directly. It's sufficient in most cases. It (a) extracts your formatters and parsers statically and (b) compiles + generates the bundle JavaScript. See their respective APIs .extract() and .compileExtracts() for constrains and other general information.
# Install
[sudo] npm install -g globalize-compiler
# globalize-compiler -l LOCALE [-c CLDR_FILE] [-m MESSAGES_FILE] -o DEST_FILE SRC_FILES...
globalize-compiler -l en \
-m messages/en.json \
-o my-compiled-formatters-and-parsers.js \
src/*.js
SRC_FILES Source JavaScript files to extract the formatters and parsers from.
-h, --help Print options and usage.
-v, --version Print the version number.
-l, --locale LOCALE Specify a LOCALE to use in compilation.
-c, --cldr CLDR_FILE Optional. All necessary CLDR data for given locale (JSON format).
-z, --tz TIME_ZONE_FILE Optional. All necessary time zone data (JSON format).
-m, --messages MESSAGES_FILE Optional. Translation messages for given locale (JSON format).
-o, --output DEST_FILE Destination JavaScript file, e.g., app-en.js.
API
Use the API directly in your Grunt or Gulp tasks.
npm install globalize-compiler --save-dev
globalize-compiler has three functions: .compile(), .compileExtracts(), and .extract().
var globalizeCompiler = require( "globalize-compiler" );
// > { compile: [Function: compiler],
// compileExtracts: [Function: compileExtracts],
// extract: [Function: extractor] }
.compile( formattersAndParsers, options )
formattersAndParsers is an Array or an Object containing formatters and/or parsers, e.g.:
// Array
[
formatter1,
formatter2,
...,
parser1,
parser2,
...
]
// Object
{
formatter1Key: formatter1,
formatter2Key: formatter2,
...,
parser1Key: parser1,
parser2Key: parser2,
...
}
options is an Object with the following properties:
template optional. A function that replaces the default template. The function will receive a single Object parameter with two properties:
code: string, the source of the compiled formatters and parsers.
dependencies: array, a list of globalize runtime modules that the compiled code depends on, e.g. globalize-runtime/number.
Returns a String with the generated JavaScript bundle (UMD wrapped) including the compiled formatters and parsers.
Example
fs.writeFileSync( "my-formatters-and-parsers.js", globalizeCompiler.compile([
formatter1,
formatter2,
...,
parser1,
parser2,
...
]));
// > "A very long String with the generate JavaScript bundle content..."
.extract( input )
input is a String with a filename, or a String with the file content, or an AST Object.
Returns an extract. An extract is a Function taking one argument: Globalize, the Globalize Object; and returning an Array with the formatters and parsers created using the passed Globalize.
Example
var extract = globalizeCompiler.extract( "src.js" );
// > [Function]
Extracting constrains
Global methods and its aliases are extracted, for example:
Globalize.numberFormatter( ... );
Globalize.formatNumber( ... );
Instance methods and its aliases are NOT extracted, for example:
// Currently, NOT extracted:
var globalize = new Globalize( locale );
globalize.numberFormatter( ... );
globalize.formatNumber( ... );
.compileExtracts( attributes )
attributes is an Object with the following properties:
extracts is an Array of extracts obtained by .extract().
defaultLocale is a locale to be used as Globalize.locale( defaultLocale ) when generating the extracted formatters and parsers.
cldr optional. It's an Object with CLDR data (in the JSON format) or a Function taking one argument: locale, a String; returning an Object with the CLDR data for the passed locale. Defaults to the entire supplemental data plus the entire main data for the defaultLocale.
timeZoneData optional. It's an Object with IANA time zone data (in the JSON format) or a Function returning an Object with the IANA time zone data. Defaults to the entire IANA time zone data from iana-tz-data package.
messages optional. It's an Object with messages data (in the JSON format) or a Function taking one argument: locale, a String; returning an Object with the messages data for the passed locale. Defaults to {}.
template optional. A function that replaces the default template. See .compile() for more details.
Returns a String with the generated JavaScript bundle as returned by the .compile() function.
Example
var extracts = [ "src/a.js", "src/b.js" ].map(function( input ) {
return GlobalizeCompiler.extract( input );
});
var bundle = GlobalizeCompiler.compileExtracts({
defaultLocale: "en",
extracts: extracts
});
// > "A very long String with the generate JavaScript bundle content..."
Important Read .extract() for more information about the extracting constrains.
Development
Tests
npm install
npm test