├── AMD.md
├── CommonConfig.md
├── LoaderPlugins.md
├── README.md
└── require.md


/AMD.md:
--------------------------------------------------------------------------------
  1 | # AMD
  2 | 
  3 | The Asynchronous Module Definition (**AMD**) API specifies a mechanism for defining modules such that the module and its dependencies can be asynchronously loaded. This is particularly well suited for the browser environment where synchronous loading of modules incurs performance, usability, debugging, and cross-domain access problems.
  4 | 
  5 | It is unrelated to the technology company [AMD](http://en.wikipedia.org/wiki/Advanced_Micro_Devices) and the processors it makes.
  6 | 
  7 | * [Tests](https://github.com/amdjs/amdjs-tests)
  8 | * [Discussion](https://groups.google.com/group/amd-implement)
  9 | 
 10 | # API Specification
 11 | 
 12 | ## define() function <a name="define"></a>
 13 | 
 14 | The specification defines a single function "define" that is available as a free variable or a global variable. The signature of the function:
 15 | 
 16 | ```javascript
 17 |     define(id?, dependencies?, factory);
 18 | ```
 19 | 
 20 | ### id <a name="define-id"></a>
 21 | 
 22 | The first argument, id, is a string literal. It specifies the id of the module being defined. This argument is optional, and if it is not present, the module id should default to the id of the module that the loader was requesting for the given response script. When present, the module id MUST be a "top-level" or absolute id (relative ids are not allowed).
 23 | 
 24 | #### module id format <a name="define-id-notes"></a>
 25 | 
 26 | Module ids can be used to identify the module being defined, and they are also used in the dependency array argument. Module ids in AMD are a superset of what is allowed in [CommonJS Module Identifiers](http://wiki.commonjs.org/wiki/Modules/1.1.1#Module_Identifiers). Quoting from that page:
 27 | 
 28 | * A module identifier is a String of "terms" delimited by forward slashes.
 29 | * A term must be a camelCase identifier, ".", or "..".
 30 | * Module identifiers may not have file-name extensions like ".js".
 31 | * Module identifiers may be "relative" or "top-level". A module identifier is "relative" if the first term is "." or "..".
 32 | * Top-level identifiers are resolved off the conceptual module name space root.
 33 | * Relative identifiers are resolved relative to the identifier of the module in which "require" is written and called.
 34 | 
 35 | The CommonJS module id properties quoted above are normally used for JavaScript modules.
 36 | 
 37 | Relative module ID resolution examples:
 38 | 
 39 | * if module `"a/b/c"` asks for `"../d"`, that resolves to `"a/d"`
 40 | * if module `"a/b/c"` asks for `"./e"`, that resolves to `"a/b/e"`
 41 | 
 42 | If [Loader Plugins](https://github.com/amdjs/amdjs-api/blob/master/LoaderPlugins.md) are supported in the AMD implementation, then "!" is used to separate the loader plugin's module id from the plugin's resource id. Since plugin resource ids can be extremely free-form, most characters should be allowed for plugin resource ids.
 43 | 
 44 | ### dependencies <a name="define-dependencies"></a>
 45 | 
 46 | The second argument, dependencies, is an array literal of the module ids that are dependencies required by the module that is being defined. The dependencies must be resolved prior to the execution of the module factory function, and the resolved values should be passed as arguments to the factory function with argument positions corresponding to indexes in the dependencies array.
 47 | 
 48 | The dependencies ids may be relative ids, and should be resolved relative to the module being defined. In other words, relative ids are resolved relative to the module's id, and not the path used to find the module's id.
 49 | 
 50 | This specification defines three special dependency names that have a distinct resolution. If the value of "require", "exports", or "module" appear in the dependency list, the argument should be resolved to the corresponding free variable as defined by the CommonJS modules specification.
 51 | 
 52 | The dependencies argument is optional. If omitted, it should default to ["require", "exports", "module"]. However, if the factory function's arity (length property) is less than 3, then the loader may choose to only call the factory with the number of arguments corresponding to the function's arity or length.
 53 | 
 54 | ### factory <a name="define-factory"></a>
 55 | 
 56 | The third argument, factory, is a function that should be executed to instantiate the module or an object. If the factory is a function it should only be executed once. If the factory argument is an object, that object should be assigned as the exported value of the module.
 57 | 
 58 | If the factory function returns a value (an object, function, or any value that coerces to true), then that value should be assigned as the exported value for the module.
 59 | 
 60 | #### Simplified CommonJS wrapping <a name="commonjs-wrap"></a>
 61 | 
 62 | If the dependencies argument is omitted, the module loader MAY choose to scan the factory function for dependencies in the form of require statements (literally in the form of require("module-id")). The first argument must literally be named require for this to work.
 63 | 
 64 | In some situations module loaders may choose not to scan for dependencies due to code size limitations or lack of toString support on functions (Opera Mobile is known to lack toString support for functions).
 65 | 
 66 | If the dependencies argument is present, the module loader SHOULD NOT scan for dependencies within the factory function.
 67 | 
 68 | ## define.amd property <a name="defineAmd"></a>
 69 | 
 70 | To allow a clear indicator that a global define function (as needed for script src browser loading) conforms to the AMD API, any global define function SHOULD have a property called "amd" whose value is an object. This helps avoid conflict with any other existing JavaScript code that could have defined a define() function that does not conform to the AMD API.
 71 | 
 72 | The properties inside the define.amd object are not specified at this time. It can be used by implementers who want to inform of other capabilities beyond the basic API that the implementation supports.
 73 | 
 74 | Existence of the define.amd property with an object value indicates conformance with this API. If there is another version of the API, it will likely define another property, like define.amd2, to indicate implementations that conform to that version of the API.
 75 | 
 76 | An example of how it may be defined for an implementation that allows loading more than one version of a module in an environment:
 77 | 
 78 | ```javascript
 79 |     define.amd = {
 80 |       multiversion: true
 81 |     };
 82 | ```
 83 | The minimum definition:
 84 | 
 85 | ```javascript
 86 |     define.amd = {};
 87 | ```
 88 | 
 89 | ## Transporting more than one module at a time <a name="transporting"></a>
 90 | 
 91 | Multiple define calls can be made within a single script. The order of the define calls SHOULD NOT be significant. Earlier module definitions may specify dependencies that are defined later in the same script. It is the responsibility of the module loader to defer loading unresolved dependencies until the entire script is loaded to prevent unnecessary requests.
 92 | 
 93 | # Examples <a name="examples"></a>
 94 | 
 95 | ## Using require and exports
 96 | 
 97 | Sets up the module with ID of "alpha", that uses require, exports and the module with ID of "beta":
 98 | 
 99 | ```javascript
100 |    define("alpha", ["require", "exports", "beta"], function (require, exports, beta) {
101 |        exports.verb = function() {
102 |            return beta.verb();
103 |            //Or:
104 |            return require("beta").verb();
105 |        }
106 |    });
107 | ```
108 | 
109 | An anonymous module that returns an object literal:
110 | 
111 | ```javascript
112 |    define(["alpha"], function (alpha) {
113 |        return {
114 |          verb: function(){
115 |            return alpha.verb() + 2;
116 |          }
117 |        };
118 |    });
119 | ```
120 | 
121 | A dependency-free module can define a direct object literal:
122 | 
123 | ```javascript
124 |    define({
125 |      add: function(x, y){
126 |        return x + y;
127 |      }
128 |    });
129 | ```
130 | 
131 | A module defined using the simplified CommonJS wrapping:
132 | 
133 | ```javascript
134 |    define(function (require, exports, module) {
135 |      var a = require('a'),
136 |          b = require('b');
137 | 
138 |      exports.action = function () {};
139 |    });
140 | ```
141 | 
142 | # Global Variables <a name="global"></a>
143 | 
144 | This specification reserves the global variable "define" for use in implementing this specification, the package metadata asynchronous definition API and is reserved for other future CommonJS APIs. Module loaders SHOULD not add additional methods or properties to this function.
145 | 
146 | This specification reserves the global variable "require" for use by module loaders. Module loaders are free to use this global variable as they see fit. They may use the variable and add any properties or functions to it as desired for module loader specific functionality. They can also choose not to use "require" as well.
147 | 
148 | # Usage notes <a name="usage"></a>
149 | 
150 | It is recommended that define calls be in the literal form of 'define(...)' in order to work properly with static analysis tools (like build tools).
151 | 
152 | # Relation to CommonJS <a name="commonjs-relation"></a>
153 | 
154 | A version of this API started on the CommonJS wiki as a transport format, as Modules Transport/C, but it changed over time to also include a module definition API. Consensus was not reached on the CommonJS list about recommending this API as a module definition API. The API was transferred over to its own wiki and discussion group.
155 | 
156 | AMD can be used as a transport format for CommonJS modules as long as the CommonJS module does not use computed, synchronous require('') calls. CommonJS code that use computed synchronous require('') code can be converted to use the callback-style [require](https://github.com/amdjs/amdjs-api/blob/master/require.md) supported in most AMD loaders.
157 | 


--------------------------------------------------------------------------------
/CommonConfig.md:
--------------------------------------------------------------------------------
  1 | # Common Config
  2 | 
  3 | ## DRAFT, Not completed yet
  4 | 
  5 | An AMD loader is not **required** to implement all of these configuration values, but if it does provide a capability that is satisfied by these configuration values, it should use these configuration names, structures and behavior.
  6 | 
  7 | Some common terms:
  8 | 
  9 | * **module ID prefix**: means part of a module ID that starts from the beginning of a string, and stop on any of the slash delimiters, up to and including the full name. So, for the complete module ID `some/very/long/name`, these are all module ID prefixes:
 10 |     * `some`
 11 |     * `some/very`
 12 |     * `some/very/long`
 13 |     * `some/very/long/name`
 14 | * **first segment of a module ID prefix**: the part of a module ID up to the first slash, or the whole name if there are no slashes in the module ID. For the example above, `some` is the first segment.
 15 | 
 16 | ## baseUrl <a name="baseUrl"></a>
 17 | 
 18 | String: Indicates the root used for ID-to-path resolutions. Relative paths are
 19 | relative to the current working directory. In web browsers, the current working
 20 | directory is the directory containing the web page running the script.
 21 | 
 22 | Example:
 23 | 
 24 | ```javascript
 25 | {
 26 |     baseUrl: './foo/bar'
 27 | }
 28 | ```
 29 | 
 30 | ## paths <a name="paths"></a>
 31 | 
 32 | Object. For specifying a path for a the given module ID prefix.
 33 | 
 34 | A property in the `paths` object is an absolute module ID prefix, and the value
 35 | can either be:
 36 | 
 37 | * String: a path value to use for the module ID prefix.  If it is a relative path, it is relative to baseUrl. It can be an absolute path, like `/top/level/dir` or `//top/level/dir` or `http://some.domain.com/top/level/dir`.
 38 | * Array: Optional. If the module loader provides a failover capability, the loader can allow an Array of String path values. If the loader cannot load the module at the first path in the Array, it can try the next path in the Array, and so on.
 39 | 
 40 | ## packages <a name="packages"></a>
 41 | 
 42 | Array of package configuration (packageConfig) objects. Package configuration
 43 | is for traditional CommonJS packages, which has different path lookup rules
 44 | than the default ID-to-path lookup rules used by an AMD loader.
 45 | 
 46 | **Default lookup rules** are ,`baseUrl +
 47 | 'module/id' + .js`, where **paths** config can be used to map part of
 48 | `'module/id'` to another path.
 49 | 
 50 | **Package lookup rules** use a special lookup rule when 'packageName' is used.
 51 | For the "main module" of a package, instead of it being
 52 | `baseUrl + 'packageName' + '.js'`, it is:
 53 | 
 54 |     baseUrl + (packageConfig.location || 'packageName') + '/' + (packageConfig.main || 'main') + '.js'
 55 | 
 56 | For 'packageName/otherId', the rule is similar to paths, but packageConfig is
 57 | used instead:
 58 | 
 59 |     baseUrl + (packageConfig.location || 'packageName') + '/' + 'otherId' + '.js'
 60 | 
 61 | The package configuration object can either be:
 62 | 
 63 | * String: The first segment of an absolute module ID prefix, which indicates the package name. So, for a module ID of `some/thing/here`, the first segment of the module ID is `some`. In that example `some` is the package name, and the value used for this config value.
 64 | * Object: a configuration object that can have the following properties:
 65 |     * **name**: String. first segment of an absolute module ID (see String section immediately above).
 66 |     * **location**: String. Optional.
 67 |     * **main**: String. Optional. Default value is "main". The module ID to use inside the package for the "main module". The value may have a ".js" at the end of it. In that case, the ".js" should be ignored by the loader. This is done to accommodate a package config style in use by some node packages.
 68 | 
 69 | ```javascript
 70 |     packages: [
 71 |         {
 72 |             name: 'dojo',
 73 |             location: 'dojo/1.7.1',
 74 |             main:'main'
 75 |         }
 76 |     ]
 77 | ```
 78 | 
 79 | ## map <a name="map"></a>
 80 | 
 81 | Object. Specifies for a given module ID prefix, what module ID prefix to use in place of another module ID prefix. For example, how to express "when 'bar' asks for module ID 'foo', actually use module ID 'foo1.2'".
 82 | 
 83 | This sort of capability is important for larger projects which may have two sets of modules that need to use two different versions of 'foo', but they still need to cooperate with each other.
 84 | 
 85 | This is different from `paths` config. `paths` is only for setting up root paths for module IDs, not for mapping one module ID to another one.
 86 | 
 87 | ```javascript
 88 | {
 89 |     map: {
 90 |         'some/newmodule': {
 91 |             'foo': 'foo1.2'
 92 |         },
 93 |         'some/oldmodule': {
 94 |             'foo': 'foo1.0'
 95 |         }
 96 |     }
 97 | }
 98 | ```
 99 | 
100 | If the modules are laid out on disk like this:
101 | 
102 | * foo1.0.js
103 | * foo1.2.js
104 | * some/
105 |     * newmodule.js
106 |     * oldmodule.js
107 | 
108 | When 'some/newmodule' asks for 'foo' it will get the 'foo1.2' module from foo1.2.js, and when 'some/oldmodule' asks for 'foo' it will get the 'foo1.0' module from foo1.0.js file.
109 | 
110 | This feature only works well for scripts that are real AMD modules that call define() and register as anonymous modules. If named modules are being used, it will not work.
111 | 
112 | Any module ID prefix can be used for the map properties, and the mappings can map to any other module ID prefix. The more specific module ID prefixes are chosen when resolving which map value to use.
113 | 
114 | Example:
115 | 
116 | ```javascript
117 | {
118 |     map: {
119 |         'some/newmodule': {
120 |             'foo': 'foo2',
121 |             'foo/bar': 'foo1.2/bar3'
122 |         },
123 |         'some/oldmodule': {
124 |             'foo/bar/baz': 'foo1.0/bar/baz2'
125 |         }
126 |     }
127 | }
128 | ```
129 | 
130 | If 'some/module/sub' asks for 'foo' it gets 'foo2'. If 'some/module/sub' asks for 'foo/bar' it gets 'foo1.2/bar3'.
131 | 
132 | There is a "*" map value which means "for all modules loaded, use this map config". If there is a more specific map config, that one will take precedence over the star config.
133 | 
134 | Example:
135 | 
136 | ```javascript
137 | {
138 |     map: {
139 |         '*': {
140 |             'foo': 'foo1.2'
141 |         },
142 |         'some/oldmodule': {
143 |             'foo': 'foo1.0'
144 |         }
145 |     }
146 | }
147 | ```
148 | 
149 | In this example if 'some/oldmodule' asks for 'foo', it will get 'foo1.0', where if any other module who asks for 'foo' will get 'foo1.2'.
150 | 
151 | ## config <a name="config"></a>
152 | 
153 | A configuration object available to modules that match the absolute module ID listed in the config object. Modules with a matching module ID can access the configuration object via `module.config`, which is an Object value. The Object value is mutable, and an Object value is always returned. If there is no explicit config set, calling `module.config()` will return an empty object, and not undefined.
154 | 
155 | Example:
156 | 
157 | ```javascript
158 | {
159 |     config: {
160 |         'some/module/id': {
161 |             limit: 40
162 |         }
163 |     }
164 | }
165 | ```
166 | 
167 | For the module that resolves to the absolute module ID of 'some/module/id', `module.config.limit === 40`.
168 | 
169 | Modules can access this config by asking for `module.config()` when using the special `module` dependency:
170 | 
171 | ```javascript
172 | //sugared CommonJS form
173 | define(function (require, exports, module) {
174 |     module.config();
175 | });
176 | 
177 | //or
178 | define(['module'], function (module) {
179 |     module.config();
180 | });
181 | ```
182 | 
183 | ## shim <a name="shim"></a>
184 | 
185 | shim config allows the use of non-AMD, browser-globals scripts by specifying the dependencies and the global value to use as the exports object. It also allows running an "init" function whose result will be used as the export value for that module ID.
186 | 
187 | Example for the module ID 'some/thing' that depends on an 'a' and 'b' and the global value at 'some.thing' with the string 'another' appended should be used as the module's export value:
188 | 
189 | ```javascript
190 | {
191 |     shim: {
192 |         'some/thing': {
193 |             deps: ['a', 'b'],
194 |             exports: 'some.thing',
195 |             init: function (a, b) {
196 |                 return some.thing + 'another';
197 |             }
198 |         }
199 |     }
200 | }
201 | ```
202 | 
203 | * **deps**: Array of string module IDs. Optional. The dependencies that need to be executed before the script for 'some/thing' is executed.
204 | * **exports**: String. Optional. Represents the global property to use for the exports value for the shimmed script. Dot values are supported. So, a value of `"some.thing"` means "use the value at global.some.thing".
205 | * **init**: Function. Optional. Called after the shimmed script has executed. It is passed any module values for the dependencies specified in "deps". If the return value of this function is not `undefined`, then the value is used as the export, and takes precedence over any specified `"exports"` value.
206 | 
207 | If "exports" and "init" are not needed for the script (common for plugins for other libraries, like jQuery plugins), then the shim config can just be the array that corresponds to the "deps" setting:
208 | 
209 | ```javascript
210 | {
211 |     shim: {
212 |         'another/thing': ['c', 'd']
213 |     }
214 | }
215 | ```
216 | 
217 | On builds:
218 | 
219 | While not required to be conformant with this API, it is suggested that a define() wrapper is **not** placed around the shimmed script in a build/concatenation scenario. Many shimmed scripts declare their globals via a simple `var globalValue = {}` in the script, and wrapping that code in a define() wrapper will result in that value not being global. If this shimmed script is used in combination with other shimmed scripts that depend on that global being there, there will likely be problems.
220 | 
221 | So if a define() wrapper is not used around the shimmed script, the "deps" for the shimmed script should be placed in the built file before the shimmed script.
222 | 
223 | Notes about the module ID used in the shim config ('some/thing' in the example):
224 | 
225 | * other config, like baseUrl and paths, can be used in resolving the value for 'some/thing'.
226 | * It is a full, absolute module ID, not a module ID prefix.
227 | 
228 | Example of shim config for two commonly used libraries, Backbone and underscore, and a jQuery plugin in a file named 'jquery.rotator.js':
229 | 
230 | ```javascript
231 | {
232 |     shim: {
233 |         //This version just specifies the
234 |         //dependency for the jQuery plugin.
235 |         //Some implementations may be able to do
236 |         //better error correction in older IE if
237 |         //you specify the exports string value,
238 |         //which in this case would be
239 |         //exports: 'jQuery.fn.rotator'
240 |         'jquery.rotator': ['jquery'],
241 | 
242 |         underscore: {
243 |             exports: '_'
244 |         },
245 | 
246 |         backbone: {
247 |             deps: ['jquery', 'underscore'],
248 |             exports: 'Backbone'
249 |         }
250 |     }
251 | }
252 | ```
253 | 


--------------------------------------------------------------------------------
/LoaderPlugins.md:
--------------------------------------------------------------------------------
  1 | # Loader Plugins
  2 | 
  3 | ## DRAFT, Not completed yet
  4 | 
  5 | Loader plugins extend an [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) implementation by allowing loading of resources that are not traditional JavaScript dependencies.
  6 | 
  7 | The API is designed to allow running a loader plugin as part of an optimization tool so that some kinds of plugin resources to be inlined if it makes sense for that type of loader plugin to do so. Because of this capability, a loader plugin should be coded to be able to run in many kinds of JavaScript environments, like the browser, Node and/or Rhino.
  8 | 
  9 | * [Tests](https://github.com/amdjs/amdjs-tests)
 10 | * [Discussion](https://groups.google.com/group/amd-implement)
 11 | 
 12 | ## Terms <a name="terms"></a>
 13 | 
 14 | A **plugin dependency** is a dependency expressed in AMD that is intended to be loaded by a loader plugin. It has the form:
 15 | 
 16 |     [Plugin Module ID]![resource ID]
 17 | 
 18 | where **plugin module ID** is a normal AMD module ID that indicates the JavaScript module that implements the loader plugin API, and **resource ID** is a plugin-specific string that the loader plugins knows how to parse to load the resource.
 19 | 
 20 | ## Examples of a plugin dependencies <a name="dependencyExamples"></a>
 21 | 
 22 | Here is one that uses a **text** loader plugin to load an HTML template.
 23 | 
 24 | ```javascript
 25 |     define(['text!../templates/start.html'], function (template) {
 26 |         //do something with the template text string.
 27 |     });
 28 | ```
 29 | 
 30 | Here is another one that has a more complex resource ID structure. It is a bit of a contrived example. It just chooses the module name that is part of the resource ID that matches to the array index given by the first number in the resource ID. So the impl below would be the module represented by './b':
 31 | 
 32 | ```javascript
 33 |     define(function (require) {
 34 |         var impl = require('index!1:./a:./b:./c');
 35 |     });
 36 | ```
 37 | 
 38 | # API Specification
 39 | 
 40 | ## load: function (resourceId, require, load, config) <a name="load"></a>
 41 | 
 42 | A function that is called to load a resource. This is the only mandatory API method that needs to be implemented for the plugin to be useful, assuming the resource IDs do not need special ID normalization (see the [normalize() method](#wiki-normalize) below for more details.
 43 | 
 44 | * **resourceId**: String. The resource ID that the plugin should load. This ID MUST be [normalized](#wiki-normalize).
 45 | * **require**: Function. A local **require** function to use to load other modules. This require function has some utilities on it:
 46 |     * **require.toUrl("moduleId+extension")**. See the [require.toUrl API notes](https://github.com/amdjs/amdjs-api/wiki/require#wiki-toUrl) for more information.
 47 | * **load**: Function. A function to call once the value of the resource ID has been determined. This tells the loader that the plugin is done loading the resource.
 48 | * **config**: Object, optional. A configuration object. This is a way for the optimizer and the web app to pass configuration information to the plugin. An optimization tool may set an isBuild property in the config to true if this plugin (or pluginBuilder (TODOC)) is being called as part of an optimizer build.
 49 | 
 50 | An example plugin that does not do anything interesting, just does a normal require to load a JS module:
 51 | 
 52 | ```javascript
 53 |     define({
 54 |         load: function (name, req, load, config) {
 55 |             //req has the same API as require().
 56 |             req([name], function (value) {
 57 |                 load(value);
 58 |             });
 59 |         }
 60 |     });
 61 | ```
 62 | 
 63 | ## normalize: function (resourceId, normalize) <a name="normalize"></a>
 64 | 
 65 | A function to normalize the passed-in resource ID. Normalization of an module ID normally means converting relative paths, like './some/path' or '../another/path' to be non-relative, absolute IDs. This is useful in providing optimal caching and optimization, but it only needs to be implemented if:
 66 | 
 67 | * the resource IDs have complex normalization
 68 | * only needed if the resource name is not a module name.
 69 | 
 70 | If the plugin does not implement **normalize** then the loader will assume it is something like a regular module ID and try to normalize it.
 71 | 
 72 | The arguments passed to normalize:
 73 | 
 74 | * **resourceId**: String. The resource ID to normalize.
 75 | * **normalize**: Function. A normalization function that accepts a string ID to normalize using the standard relative module normalization rules using the loader's current configuration.
 76 | 
 77 | An example: suppose there is an index! plugin that will load a module name given an index. This is a contrived example, just to illustrate the concept. A module may reference an index! dependency like so:
 78 | 
 79 | ```javascript
 80 |     define(['index!2?./a:./b:./c'], function (indexResource) {
 81 |         //indexResource will be the module that corresponds to './c'.
 82 |     });
 83 | ```
 84 | In this case, the normalized IDs for './a', './b', and './c' will be determined relative to the module asking for this resource. Since the loader does not know how to inspect 'index!2?./a:./b:./c' to normalize the IDs for './a', './b', and './c', it needs to ask the plugin. This is the purpose of the normalize call.
 85 | 
 86 | By properly normalizing the resource name, it allows the loader to cache the value effectively, and to properly build an optimized build layer in the optimizer. It is also required so that the loader can pass always pass a normalized ID to the plugin's [load](#wiki-load) method.
 87 | 
 88 | The index! plugin could be written like so:
 89 | 
 90 | ```javascript
 91 |     (function () {
 92 | 
 93 |         //Helper function to parse the 'N?value:value:value'
 94 |         //format used in the resource name.
 95 |         function parse(name) {
 96 |             var parts = name.split('?'),
 97 |                 index = parseInt(parts[0], 10),
 98 |                 choices = parts[1].split(':'),
 99 |                 choice = choices[index];
100 | 
101 |             return {
102 |                 index: index,
103 |                 choices: choices,
104 |                 choice: choice
105 |             };
106 |         }
107 | 
108 |         //Main module definition.
109 |         define({
110 |             normalize: function (name, normalize) {
111 |                 var parsed = parse(name),
112 |                     choices = parsed.choices;
113 | 
114 |                 //Normalize each path choice.
115 |                 for (i = 0; i < choices.length; i++) {
116 |                     //Call the normalize() method passed in
117 |                     //to this function to normalize each
118 |                     //module ID.
119 |                     choices[i] = normalize(choices[i]);
120 |                 }
121 | 
122 |                 return parsed.index + '?' + choices.join(':');
123 |             },
124 | 
125 |             load: function (name, require, load, config) {
126 |                 require([parse(name).choice], function (value) {
127 |                     load(value);
128 |                 });
129 |             }
130 |         });
131 | 
132 |     }());
133 | ```
134 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | This repo holds the API specifications for AMD and some APIs that are strongly related to AMD.
 2 | 
 3 | * [AMD](https://github.com/amdjs/amdjs-api/blob/master/AMD.md): The Asynchronous Module Definition. The primary building block for referencing and defining modular JS code.
 4 | * [require](https://github.com/amdjs/amdjs-api/blob/master/require.md): An API for the require() function that allows dynamic, asynchronous loading of modules, and for resolving some module ID-based strings to file paths.
 5 | * [Loader Plugins](https://github.com/amdjs/amdjs-api/blob/master/LoaderPlugins.md): Loader plugins extend an AMD implementation by allowing loading of resources that are not traditional JavaScript dependencies.
 6 | * [Common-Config](https://github.com/amdjs/amdjs-api/blob/master/CommonConfig.md): Optional common configuration. If a loader supports functionality that matches capabilities specified in these configuration values, these structures should be used to allow easier interop with other loaders.
 7 | 
 8 | If you are implementing an AMD loader, the [amd-implement list](https://groups.google.com/group/amd-implement) is for discussions that do not fit into smaller items that can be tracked by issue tickets.
 9 | 
10 | Some documents on the wiki that are not actual APIs but information related to AMD use:
11 | 
12 | * [jQuery-and-AMD](https://github.com/amdjs/amdjs-api/wiki/jQuery-and-AMD): Describes jQuery 1.7+ support for registering as an AMD module, but only if define.amd.jQuery is set to true.
13 | 
14 | Documents related to AMD and its use in other libraries:
15 | 
16 | * [AMD Forks](https://github.com/amdjs/amdjs-api/wiki/AMD-Forks): A listing of forks for libraries that have AMD registration built in.
17 | 
18 | The [wiki](https://github.com/amdjs/amdjs-api/wiki) for this project also contains copies of the information in this repo. Those pages are kept for historical reasons/links, but the contents of this repo are considered the definitive source.
19 | 
20 | ---
21 | 
22 | <p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
23 |   <a rel="license"
24 |      href="http://creativecommons.org/publicdomain/zero/1.0/">
25 |     <img src="http://i.creativecommons.org/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0" />
26 |   </a>
27 |   <br />
28 |   To the extent possible under law,
29 |   <a rel="dct:publisher"
30 |      href="https://github.com/amdjs">
31 |     <span property="dct:title">the amdjs organization</span></a>
32 |   has waived all copyright and related or neighboring rights to
33 |   <span property="dct:title">AMD specifications</span>.
34 | This work is published from:
35 | <span property="vcard:Country" datatype="dct:ISO3166"
36 |       content="US" about="https://github.com/amdjs">
37 |   United States</span>.
38 | </p>


--------------------------------------------------------------------------------
/require.md:
--------------------------------------------------------------------------------
 1 | # require
 2 | 
 3 | The **require** function in an [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) implementation differs from the traditional [CommonJS require](http://wiki.commonjs.org/wiki/Modules/1.1.1#Require). There is a strong need for a callback-based require, since dynamically computed dependencies may load asynchronously.
 4 | 
 5 | * [Tests](https://github.com/amdjs/amdjs-tests)
 6 | * [Discussion](https://groups.google.com/group/amd-implement)
 7 | 
 8 | # API Specification
 9 | 
10 | ## Local vs Global require <a name="localGlobal"></a>
11 | 
12 | The **local** require is the require function passed to an [AMD define factory function](https://github.com/amdjs/amdjs-api/wiki/AMD#wiki-define). Examples:
13 | 
14 | ```javascript
15 |     define(['require'], function (require) {
16 |         //the require in here is a local require.
17 |     });
18 | 
19 |     define(function (require, exports, module) {
20 |         //the require in here is a local require.
21 |     });
22 | ```
23 | The local require MAY support other APIs specific to the implementation.
24 | 
25 | A global require() function is one that is available in the global scope, like define(). An implementation is not required to implement a global require, but if it does, the behavior of global require is similar to the behavior of the local require() function, with the following qualifications:
26 | 
27 | * module IDs are treated as absolute instead of being resolved relatively to another module's ID.
28 | * only the async, callback-style of require is expected to work for interoperation, since it may not be possible to synchronously load a module via require(String) from the top level.
29 | 
30 | There is often an implementation-dependent API that will kick off module loading; if interoperability with several loaders is needed, the global require() should be used to load the top level modules instead.
31 | 
32 | ## require(String) <a name="requireString"></a>
33 | 
34 | Synchronously returns the module export for the module ID represented by the String argument. Based on the [CommonJS Modules 1.1.1 require](http://wiki.commonjs.org/wiki/Modules/1.1.1#Require).
35 | 
36 | It MUST throw an error if the module has not already been loaded and evaluated. In particular, the synchronous call to require MUST NOT try to dynamically fetch the module if it is not already loaded, but throw an error instead.
37 | 
38 | Dependencies can be found in an AMD module when this form of define() is used:
39 | 
40 | ```javascript
41 |     define(function (require) {
42 |         var a = require('a');
43 |     });
44 | ```
45 | 
46 | The define factory function can be parsed for require('') calls (for instance by using a language parser or using Function.prototype.toString() and regexps) to find dependencies, load and execute the dependencies, then run the code above. In that manner, the require('a') call can return the module value.
47 | 
48 | ## require(Array, Function) <a name="requireArray"></a>
49 | 
50 | The Array is an array of String module IDs. The modules that are represented by the module IDs should be retrieved and once all the modules for those module IDs are available, the Function callback is called, passing the modules in the same order as the their IDs in the Array argument.
51 | 
52 | Example:
53 | 
54 | ```javascript
55 |     define(function (require) {
56 |         require(['a', 'b'], function (a, b) {
57 |             //modules a and b are now available for use.
58 |         });
59 |     });
60 | ```
61 | 
62 | ## require.toUrl(String) <a name="toUrl"></a>
63 | 
64 | Converts a String that is of the form **[module ID] + '.extension'** to an URL path. require.toUrl resolves the module ID part of the string using its normal module ID-to-path resolution rules, except it does not resolve to a path with a ".js" extension. Then, the '.extension' part is then added to that resolved path. Example:
65 | 
66 | ```javascript
67 |     //cart.js contents:
68 |     define (function(require) {
69 |         //module ID part is './templates/a'
70 |         //'.extension is '.html'
71 |         //templatePath may end up to be something like
72 |         //'modules/cart/templates/a.html'
73 |         var templatePath = require.toUrl('./templates/a.html');
74 | 
75 |     });
76 | ```
77 | 


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