<commit_before>curl (Cujo Resource Loader)
=====================

version 0.3.1

TODO:

* i18n plugin
* finish core extensions (debug, commonjs, etc)
* commonjs extension: Modules 1.1 and packages

----------------------------------------

What is curl.js?
================

curl.js is a small, but very fast AMD-compliant asynchronous loader.
Current size: 4.5KB (2.1KB gzipped) using Google's Closure Compiler.

If you'd like to use curl.js for non-AMD modules (ordinary javascript files), you'll want to  use the
version with the js! plugin built in.  You may also want to build-in the
domReady module.  The combined curl+js+domReady loader is still only
6.1KB (2.7KB gzipped).

What the heck is cujo?  cujo.js is a web app dvelopment platform.  See the bottom of this file for more info.

What's new?
----------
* The API has changed a bit since 0.2. The .ready() and .domReady() methods are gone,
  replaced by the domReady module.  See the "API at a glance" section.
* The domReady module now returns a promise. This makes the API a bit cleaner.
* The js! plugin has been moved out into it's own file and now supports
  the !wait suffix which will load, but not execute, the file until
  all previous non-AMD files are executed.

If you're already familiar with CommonJS AMD loaders, skip down to the section
"**How do I use curl.js?**"

----------------------------------------

Features at a glance:
=====================

* Loads CommonJS AMD-formatted javascript modules in parallel (fast!)
* Loads non-AMD javascript files in parallel, too (fast! via js! plugin)
* Loads CSS files and text files in parallel (fast! via plugins)
* Waits for dependencies (js, css, text, etc) before executing javascript
* Waits for domReady, if/when desired
* Allows for virtually limitless combinations of files and dependencies
* Tested with Chrome, FF3+, Safari 3.2+, IE6-8, Opera 9.5+

Oh, did we mention?  It's fast!

----------------------------------------

API at a glance
===============

**"curl" and "require" are synonyms. You may use them interchangeably.**

	curl(['dep1', 'dep2', 'dep3' /* etc */], callback);
	require(['dep1', 'dep2', 'dep3' /* etc */], callback);

Loads dependencies and the executes callback.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources. This is where you'd typically start up your app.

---------
	curl(['dep1', 'dep2', 'dep3' /* etc */])
		.then(callback, errorback);
	require(['dep1', 'dep2', 'dep3' /* etc */])
		.then(callback, errorback);

Promises-based API for executing callbacks.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources
* errorback: Function to call if an exception occurred while loading

---------
	curl(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);
	require(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);

Specify configuration options, load dependencies, and execute callback.

* config: Object containing curl configuration options (paths, etc.)
* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources

---------
	curl(['domReady', 'dep2', 'dep3' /* etc */])
		.then(
			callback,
			errorback
		);
	curl(['dep1', 'dep2', 'domReady' /* etc */], function (dep1, dep2) {
		// do something here
	});

Executes the callback when the dom is ready for manipulation AND
all dependencies have loaded.

* callback: No parameters except the domReady object
* errorback: Function to call if an exception occurred while loading

---------
	curl(['domReady', 'js!nonAMD.js', 'js!another.js!wait']), function (domReady) {
		/* do something cool here */
	});

Executes the function when the non-AMD javascript files are loaded and
the dom is ready. The another.js file will wait for the nonAMD.js file
before executing.

---------
	curl(['js!nonAMD.js'])
		.next(['dep1', 'dep2', 'dep3'], function (dep1, dep2, dep3) {
			// do something before the dom is ready
		})
		.next(['domReady'])
		.then(
			function () {
				// do something after the dom is ready
			},
			function (ex) {
				// show an error to the user
			}
		);

Executes callbacks is stages using `.next(deps, callback)`.

---------

	curl = {
		baseUrl: '/path/to/my/js',
		paths: {
			curl: 'curl/src/curl',
			cssx: 'cssx/src/cssx'
			my: '../../my-lib/'
		}
	};

If called before the `<script>` that loads curl.js, configures curl.js.

---------
	define(['dep1', 'dep2', 'dep3' /* etc */], definition);
	define(['dep1', 'dep2', 'dep3' /* etc */], module);
	define(['dep1', 'dep2', 'dep3' /* etc */], promise);
	define(module);
	define(promise);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], definition);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], module);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], promise);
	define(name, module);
	define(name, promise);

Defines a module per the CommonJS AMD proposed specification.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* definition: Function called to define the module
* module: Any javascript object, function, constructor, or primitive
* promise: Object compatible with CommonJS Promises/A. Useful for further
deferring resolution of the module.
* name: String used to name a module (not necessary nor recommended)

----------------------------------------

Very Simple Example
===================

	<script>
<commit_msg>Updated TODO items and added more info about configuration paramaters<commit_after>curl (Cujo Resource Loader)
=====================

version 0.3.1

TODO:

* CommonJS Modules 1.1 (testing now!)
* i18n plugin (by 2011-04-11)
* CommonJs Packages
* async=false in the js! plugin
* More tests!

----------------------------------------

What is curl.js?
================

curl.js is a small, but very fast AMD-compliant asynchronous loader.
Current size: 4.5KB (2.1KB gzipped) using Google's Closure Compiler.

If you'd like to use curl.js for non-AMD modules (ordinary javascript files), you'll want to  use the
version with the js! plugin built in.  You may also want to build-in the domReady module.  The 
combined curl+js+domReady loader is still only 6.1KB (2.7KB gzipped).

What the heck is cujo?  cujo.js is a web app dvelopment platform.  See the bottom of this file for more info.

What's new?
----------
* The API has changed a bit since 0.2. The .ready() and .domReady() methods are gone,
  replaced by the domReady module.  See the "API at a glance" section.
* The domReady module now returns a promise. This makes the API a bit cleaner.
* The js! plugin has been moved out into it's own file and now supports
  the !wait suffix which will load, but not execute, the file until
  all previous non-AMD files are executed.

If you're already familiar with CommonJS AMD loaders, skip down to the section
"**How do I use curl.js?**"

----------------------------------------

Features at a glance:
=====================

* Loads CommonJS AMD-formatted javascript modules in parallel (fast!)
* Loads non-AMD javascript files in parallel, too (fast! via js! plugin)
* Loads CSS files and text files in parallel (fast! via plugins)
* Waits for dependencies (js, css, text, etc) before executing javascript
* Waits for domReady, if/when desired
* Allows for virtually limitless combinations of files and dependencies
* Tested with Chrome, FF3+, Safari 3.2+, IE6-8, Opera 9.5+

Oh, did we mention?  It's fast!

----------------------------------------

API at a glance
===============

**Note: "curl" and "require" are synonyms. You may use them interchangeably.**

	curl(['dep1', 'dep2', 'dep3' /* etc */], callback);
	require(['dep1', 'dep2', 'dep3' /* etc */], callback);

Loads dependencies and the executes callback.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources. This is where you'd typically start up your app.

---------
	curl(['dep1', 'dep2', 'dep3' /* etc */])
		.then(callback, errorback);
	require(['dep1', 'dep2', 'dep3' /* etc */])
		.then(callback, errorback);

Promises-based API for executing callbacks.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources
* errorback: Function to call if an exception occurred while loading

---------
	curl(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);
	require(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);

Specify configuration options, load dependencies, and execute callback.

* config: Object containing curl configuration options (paths, etc.)
* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* callback: Function to receive modules or resources

---------
	curl(['domReady', 'dep2', 'dep3' /* etc */])
		.then(
			callback,
			errorback
		);
	curl(['dep1', 'dep2', 'domReady' /* etc */], function (dep1, dep2) {
		// do something here
	});

Executes the callback when the dom is ready for manipulation AND
all dependencies have loaded.

* callback: No parameters except the domReady object
* errorback: Function to call if an exception occurred while loading

---------
	curl(['domReady', 'js!nonAMD.js', 'js!another.js!wait']), function (domReady) {
		/* do something cool here */
	});

Executes the function when the non-AMD javascript files are loaded and
the dom is ready. The another.js file will wait for the nonAMD.js file
before executing.

---------
	curl(['js!nonAMD.js'])
		.next(['dep1', 'dep2', 'dep3'], function (dep1, dep2, dep3) {
			// do something before the dom is ready
		})
		.next(['domReady'])
		.then(
			function () {
				// do something after the dom is ready
			},
			function (ex) {
				// show an error to the user
			}
		);

Executes callbacks is stages using `.next(deps, callback)`.

---------

	curl = {
		baseUrl: '/path/to/my/js',
		pluginPath: 'for/some/reason/plugins/r/here',
		paths: {
			curl: 'curl/src/curl',
			cssx: 'cssx/src/cssx'
			my: '../../my-lib/'
		},
		apiName: 'someOtherName'
	};

If called before the `<script>` that loads curl.js, configures curl.js.  All of the 
configuration parameters are optional. curl.js tries to do something sensible
in their absence. :)

* baseUrl: the root folder to find all modules, default is the document's folder
* paths: a mapping of module paths to relative paths (from baseUrl)
* pluginPath: the place to find plugins when they are specified without a path
(e.g. "css!myCssFile" vs. "cssx/css!myCssFile") and there is no paths
mapping that applies.
* apiName: an alternate name to `curl` and `require` for curl.js's global variable

---------
	define(['dep1', 'dep2', 'dep3' /* etc */], definition);
	define(['dep1', 'dep2', 'dep3' /* etc */], module);
	define(['dep1', 'dep2', 'dep3' /* etc */], promise);
	define(module);
	define(promise);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], definition);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], module);
	define(name, ['dep1', 'dep2', 'dep3' /* etc */], promise);
	define(name, module);
	define(name, promise);

Defines a module per the CommonJS AMD proposed specification.

* ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
* definition: Function called to define the module
* module: Any javascript object, function, constructor, or primitive
* promise: Object compatible with CommonJS Promises/A. Useful for further
deferring resolution of the module.
* name: String used to name a module (not necessary nor recommended)

----------------------------------------

Very Simple Example
===================

	<script>

{'fraction_non_alphanumeric': 0.17523203850120317, 'fraction_numerical': 0.015125472671020969, 'mean_word_length': 3.3797515995483627, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2155318', 'n_tokens_mistral': 3679, 'n_tokens_neox': 3422, 'n_words': 1415}