Commit 19e96314 authored by Georges Khaznadar's avatar Georges Khaznadar

Import Upstream version 0.3.1+dfsg

parents
.DS_Store
tests
*.sh
language: node_js
node_js: 0.10
before_script:
- node tests/server.js &
- sleep 1
script: phantomjs tests/runner.js
after_script:
- kill -9 `cat tests/pid.txt`
- rm tests/pid.txt
almond is released under two licenses: new BSD, and MIT. You may pick the
license that best suits your development needs. The text of both licenses are
provided below.
The "New" BSD License:
----------------------
Copyright (c) 2010-2011, The Dojo Foundation
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the Dojo Foundation nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
MIT License
-----------
Copyright (c) 2010-2011, The Dojo Foundation
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
#almond
A replacement [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) loader for
[RequireJS](http://requirejs.org). It provides a minimal AMD API footprint that includes [loader plugin](http://requirejs.org/docs/plugins.html) support. Only useful for built/bundled AMD modules, does not do dynamic loading.
## Why
Some developers like to use the AMD API to code modular JavaScript, but after doing an optimized build,
they do not want to include a full AMD loader like RequireJS, since they do not need all that functionality.
Some use cases, like mobile, are very sensitive to file sizes.
By including almond in the built file, there is no need for RequireJS.
almond is around **1 kilobyte** when minified with Closure Compiler and gzipped.
Since it can support certain types of loader plugin-optimized resources, it is a great
fit for a library that wants to use [text templates](http://requirejs.org/docs/api.html#text)
or [CoffeeScript](https://github.com/jrburke/require-cs) as part of
their project, but get a tiny download in one file after using the
[RequireJS Optimizer](http://requirejs.org/docs/optimization.html).
If you are building a library, the wrap=true support in the RequireJS optimizer
will wrap the optimized file in a closure, so the define/require AMD API does not
escape the file. Users of your optimized file will only see the global API you decide
to export, not the AMD API. See the usage section below for more details.
So, you get great code cleanliness with AMD and the use of powerful loader plugins
in a tiny wrapper that makes it easy for others to use your code even if they do not use AMD.
If you want a single file build output but without the module APIs included, you might want to consider [AMDclean](https://github.com/gfranko/amdclean).
## Restrictions
It is best used for libraries or apps that use AMD and:
* optimize all the modules into one file -- no dynamic code loading.
* all modules have IDs and dependency arrays in their define() calls -- the RequireJS optimizer will take care of this for you.
* only have **one** requirejs.config() or require.config() call.
* the requirejs.config/require.config call needs to be included in the build output. This is particularly important for making sure any [map config](http://requirejs.org/docs/api.html#config-map) use still works.
* do not use the `var require = {};` style of [passing config](http://requirejs.org/docs/api.html#config).
* do not use [RequireJS multiversion support/contexts](http://requirejs.org/docs/api.html#multiversion).
* do not use require.toUrl() or require.nameToUrl().
* do not use [packages/packagePaths config](http://requirejs.org/docs/api.html#packages). If you need to use packages that have a main property, [volo](https://github.com/volojs/volo) can create an adapter module so that it can work without this config. Use the `amdify add` command to add the dependency to your project.
What is supported:
* dependencies with relative IDs.
* define('id', {}) definitions.
* define(), require() and requirejs() calls.
* loader plugins that can inline their resources into optimized files, and
can access those inlined resources synchronously after the optimization pass.
The [text](http://requirejs.org/docs/api.html#text) and
[CoffeeScript](https://github.com/jrburke/require-cs) plugins are two such plugins.
## Download
[Latest release](https://github.com/jrburke/almond/raw/latest/almond.js)
## Usage
[Download the RequireJS optimizer](http://requirejs.org/docs/download.html#rjs).
[Download the current release of almond.js](https://github.com/jrburke/almond/raw/latest/almond.js).
Run the optimizer using [Node](http://nodejs.org) (also [works in Java](https://github.com/jrburke/r.js/blob/master/README.md)):
node r.js -o baseUrl=. name=path/to/almond include=main out=main-built.js wrap=true
This assumes your project's top-level script file is called main.js and the command
above is run from the directory containing main.js. If you prefer to use a build.js build profile instead of command line arguments, [this RequireJS optimization section](http://requirejs.org/docs/optimization.html#pitfalls) has info on how to do that.
wrap=true will add this wrapper around the main-built.js contents (which will be minified by UglifyJS:
(function () {
//almond will be here
//main and its nested dependencies will be here
}());
If you do not want that wrapper, leave off the wrap=true argument.
These optimizer arguments can also be used in a build config object, so it can be used
in [runtime-generated server builds](https://github.com/jrburke/r.js/blob/master/build/tests/http/httpBuild.js).
## Triggering module execution <a name="execution"></a>
As of RequireJS 2.0 and almond 0.1, modules are only executed if they are
called by a top level require call. The data-main attribute on a script tag
for require.js counts as a top level require call.
However with almond, it does not look for a data-main attribute, and if your
main JS module does not use a top level require() or requirejs() call to
trigger module loading/execution, after a build, it may appear that the code
broke -- no modules execute.
The 2.0 RequireJS optimizer has a build config, option **insertRequire** that you
can use to specify that a require([]) call is inserted at the end of the built
file to trigger module loading. Example:
node r.js -o baseUrl=. name=path/to/almond.js include=main insertRequire=main out=main-built.js wrap=true
or, if using a build config file:
```javascript
{
baseUrl: '.',
name: 'path/to/almond',
include: ['main'],
insertRequire: ['main'],
out: 'main-built.js',
wrap: true
}
```
This will result with `require(["main"]);` at the bottom of main-built.js.
## Exporting a public API
If you are making a library that is made up of AMD modules in source form, but will be built with almond into one file, and you want to export a small public
API for that library, you can use the `wrap` build config to do so. Build
config:
```javascript
{
baseUrl: '.',
name: 'path/to/almond',
include: ['main'],
out: 'lib-built.js',
wrap: {
startFile: 'path/to/start.frag',
endFile: 'path/to/end.frag'
}
}
```
Where start.frag could look like this:
```javascript
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
//Allow using this built library as an AMD module
//in another project. That other project will only
//see this AMD call, not the internal modules in
//the closure below.
define([], factory);
} else {
//Browser globals case. Just assign the
//result to a property on the global.
root.libGlobalName = factory();
}
}(this, function () {
//almond, and your modules will be inlined here
```
and end.frag is like this:
```javascript
//The modules for your project will be inlined above
//this snippet. Ask almond to synchronously require the
//module value for 'main' here and return it as the
//value to use for the public API for the built file.
return require('main');
}));
```
After the build, then the built file should be structured like so:
* start.frag
* almond.js
* modules for your lib, including 'main'
* end.frag
## Common errors
Explanations of common errors:
### incorrect module build, no module name
In almond 3.0.0 and earlier, this would show up as "deps is undefined", where
this line is mentioned:
if (!deps.splice) {
In 3.0.1+ the error is explicitly: "incorrect module build, no module name".
This means that there is a define()'d module, but it is missing a name,
something that looks like this:
define(function () {});
//or
define([], function () {});
when it should look like:
define('someName', function () {});
//or
define('someName', [], function () {});
This is usually a sign that the tool you used to combine all the modules
together did not properly name an anonymous AMD module.
Multiple modules built into a single file **must** have names in the define calls.
Otherwise almond has no way to assign the module to a name key for use in the code.
The fix is to use a build tool that understand AMD modules and inserts the module
IDs in the build. The
[requirejs optimizer](http://requirejs.org/docs/optimization.html) is a build tool
that can do this correctly.
### x missing y
It means that module 'x' asked for module 'y', but module 'y' was not available.
This usually means that 'y' was not included in the built file that includes almond.
almond can only handle modules built in with it, it cannot dynamically load
modules from the network.
### No y
It means that a `require('y')` call was done but y was not available.
This usually means that 'y' was not included in the built file that includes almond.
almond can only handle modules built in with it, it cannot dynamically load
modules from the network.
## How to get help
* Contact the [requirejs list](https://groups.google.com/group/requirejs).
* Open issues in the [issue tracker](https://github.com/jrburke/almond/issues).
## Contributing
Almond follows the
[same contribution model as requirejs](http://requirejs.org/docs/contributing.html)
and is considered a sub-project of requirejs.
\ No newline at end of file
This diff is collapsed.
{
"name": "almond",
"version": "0.3.1",
"main": "almond.js",
"ignore": [
"tests",
"shrinktest.sh"
]
}
{
"name": "almond",
"description": "A minimal AMD API implementation for use in optimized browser builds.",
"version": "0.3.1",
"homepage": "http://github.com/jrburke/almond",
"author": "James Burke <jrburke@gmail.com> (http://github.com/jrburke)",
"repository": {
"type": "git",
"url": "git://github.com/jrburke/almond.git"
},
"licenses": [
{
"type": "BSD",
"url": "https://github.com/jrburke/almond/blob/master/LICENSE"
},
{
"type": "MIT",
"url": "https://github.com/jrburke/almond/blob/master/LICENSE"
}
],
"main": "almond.js",
"engines": {
"node": ">=0.4.0"
},
"devDependencies": {
"connect": "^3.3.4",
"serve-static": "^1.9.1"
}
}
#!/bin/sh
rm almond.min.js.gz
uglifyjs -c -m -o almond.min.js almond.js
gzip almond.min.js
ls -la almond.min.js.gz
doh.registerUrl("simple", "../simple.html");
doh.registerUrl("defineDouble", "../defineDouble/defineDouble.html");
doh.registerUrl("moduleConfig", "../moduleConfig/moduleConfig.html");
doh.registerUrl("mapConfig", "../mapConfig/mapConfig.html");
doh.registerUrl("mapConfigStar", "../mapConfig/mapConfigStar.html");
doh.registerUrl("mapConfigStarAdapter", "../mapConfig/mapConfigStarAdapter.html");
doh.registerUrl("mapConfigSpecificity", "../mapConfig/mapConfigSpecificity.html");
doh.registerUrl("mapConfigPlugin", "../mapConfig/mapConfigPlugin.html");
doh.registerUrl("plugins", "../plugins/plugins.html");
doh.registerUrl("pluginsMapSameName", "../plugins/pluginMapSameName/pluginMapSameName.html");
doh.registerUrl("orderPlugin", "../plugins/order/order.html");
doh.registerUrl("text", "../plugins/text.html");
doh.registerUrl("coffee", "../plugins/coffee.html");
doh.registerUrl("shim", "../shim/shim.html");
doh.registerUrl("unorderedSeparate", "../unordered/separate.html");
doh.registerUrl("emptyFactory", "../emptyFactory/emptyFactory.html");
doh.registerUrl("missing", "../missing/missing.html");
doh.registerUrl("insertRequire", "../insertRequire/insertRequire.html", 4000);
doh.registerUrl("circular", "../circular/circular.html");
doh.registerUrl("circular414", "../circular/414/414.html");
doh.registerUrl("circularTranspiler", "../circular/transpiler/transpiler.html");
doh.registerUrl("relativePaths", "../relativePaths/relativePaths.html");
doh.registerUrl("errback", "../errback/errback.html");
doh.registerUrl("specialDeps", "../specialDeps/specialDeps.html");
doh.registerUrl("hasOwnPropertyTests", "../hasOwnProperty/hasOwnProperty.html");
doh.registerUrl("firstDefine", "../firstDefine/firstDefine.html");
doh.registerUrl("topRelativeRequire", "../topRelativeRequire/topRelativeRequire.html");
doh.registerUrl("configDeps", "../configDeps/configDeps.html");
doh.registerUrl("defineNoCallback", "../defineNoCallback/defineNoCallback.html");
doh.registerUrl("packagesNode", "../packagesNode/packagesNode.html");
doh.registerUrl("requireInDefine", "../requireInDefine/requireInDefine.html");
doh.registerUrl("badAnonDefine", "../badAnonDefine/badAnonDefine.html");
<!DOCTYPE html>
<html>
<head>
<title>almond: Bad anonymous define Test</title>
<script type="text/javascript" src="../doh/runner.js"></script>
<script type="text/javascript" src="../doh/_browserRunner.js"></script>
<script type="text/javascript" src="../../almond.js"></script>
<script type="text/javascript" src="badAnonDefine.js"></script>
</head>
<body>
<h1>almond: Unordered, Separate Test</h1>
<p>Modules are unordered, and loaded separate from almond.js</p>
<p>Check console for messages</p>
</body>
</html>
var throwCount = 0;
try {
define(['a'], function(a) {
return a;
});
} catch (e) {
throwCount += 1;
}
try {
define(function(require) {
return require('b');
});
} catch (e) {
throwCount += 1;
}
doh.register(
'badAnonDefine',
[
function badAnonDefine(t){
t.is(2, throwCount);
}
]
);
doh.run();
<!DOCTYPE html>
<html>
<head>
<title>almond: requirejs#414: Multi-cycle Bundle Test</title>
<script type="text/javascript" src="../../doh/runner.js"></script>
<script type="text/javascript" src="../../doh/_browserRunner.js"></script>
<script src="../../../almond.js"></script>
<script type="text/javascript" src="414.js"></script>
</head>
<body>
<h1>almond: requirejs#414: Multi-cycle Bundle Test</h1>
<p>A set of modules have multiple cycles in them, but the require() that
uses the top module in that bundle should get a fully constructed
module set.<a href="https://github.com/jrburke/requirejs/issues/414">More info</a>.</p>
<p>Check console for messages</p>
</body>
</html>
define('C',
[
"exports",
"./MyClass",
"./A",
"./B"
],
function (exports, MyClass, A, B) {
exports.name = "C";
exports.say = function(){
return [MyClass.name, A.name, B.name, exports.name].join(',');
};
}
);
define('B',
[
"exports",
"./MyClass",
"./A",
"./C"
],
function (exports, MyClass, A, C) {
exports.name = "B";
exports.say = function(){
return [MyClass.name, A.name, exports.name, C.name].join(',');
};
}
);
define('A',
[
"exports",
"./MyClass",
"./B",
"./C"
],
function (exports, MyClass, B, C) {
exports.name = "A";
exports.say = function(){
return [MyClass.name, exports.name, B.name, C.name].join(',');
};
}
);
define('MyClass',
[
"exports",
"./A",
"./B",
"./C"
],
function (exports, A, B, C) {
exports.name = "MyClass";
exports.sayAll = function(){
return [
exports.say(),
A.say(),
B.say(),
C.say()
].join(':');
};
exports.say = function(){
return [exports.name, A.name, B.name, C.name].join(',');
};
return exports;
}
);
require({
baseUrl: requirejs.isBrowser ? './' : './circular/414'
},
["MyClass"],
function(MyClass) {
doh.register(
"circular414",
[
function circularComplexPlugin(t) {
t.is("MyClass,A,B,C:MyClass,A,B,C:MyClass,A,B,C:MyClass,A,B,C", MyClass.sayAll());
}
]
);
doh.run();
}
);
define("414-tests", function(){});
<!DOCTYPE html>
<html>
<head>
<title>almond: circular Test</title>
<script type="text/javascript" src="../doh/runner.js"></script>
<script type="text/javascript" src="../doh/_browserRunner.js"></script>
<script type="text/javascript" src="../../almond.js"></script>
<script type="text/javascript">
define('a', ['b', 'require'], function (b, require) {
return {
name: 'a',
getB: function () {
return require('b');
}
}
});
define('b', ['a', 'require'], function (a, require) {
return {
name: 'b',
getA: function () {
return require('a');
}
}
});
define('c', ['require', 'exports'], function (require, exports) {
exports.name = 'c',
exports.d = require('d');
});
define('d', ['require', 'exports'], function (require, exports) {
exports.name = 'd',
exports.c = require('c');
});
require(['a', 'c', 'd'], function (a, c, d) {
doh.register(
'circular',
[
function circular(t){
b = a.getB();
t.is('a', a.name);
t.is('b', b.name);
t.is('a', b.getA().name);
t.is('c', c.name);
t.is('d', c.d.name);
t.is('d', d.name);
t.is('c', d.c.name);
}
]
);
doh.run();
});
</script>
</head>
<body>
<h1>almond: circular Test</h1>
<p>Test circular dependencies with almond. More info:
<a href="https://github.com/jrburke/almond/issues/17">17</a>.</p>
<p>Check console for messages</p>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
<title>almond: Circular Transpiler Plugin Test</title>
<script type="text/javascript" src="../../doh/runner.js"></script>
<script type="text/javascript" src="../../doh/_browserRunner.js"></script>
<script src="../../../almond.js"></script>
<script type="text/javascript" src="transpiler.js"></script>
</head>
<body>
<h1>almond: Circular Transpiler Plugin Test</h1>
<p>Test support for transpiled modules with cycles in them More info:
<a href="https://github.com/jrburke/requirejs/issues/356">356</a>.</p>
<p>Check console for messages</p>
</body>
</html>
/*jslint strict: false, plusplus: false */
/*global define: false, require: false, XMLHttpRequest: false, ActiveXObject: false,
window: false, Packages: false, java: false, process: false */
(function () {
//Load the text plugin, so that the XHR calls can be made.
var buildMap = {}, fetchText, fs,
progIds = ['Msxml2.XMLHTTP', 'Microsoft.XMLHTTP', 'Msxml2.XMLHTTP.4.0'];
function createXhr() {
//Would love to dump the ActiveX crap in here. Need IE 6 to die first.
var xhr, i, progId;
if (typeof XMLHttpRequest !== "undefined") {
return new XMLHttpRequest();
} else {
for (i = 0; i < 3; i++) {
progId = progIds[i];
try {
xhr = new ActiveXObject(progId);
} catch (e) {}
if (xhr) {
progIds = [progId]; // so faster next time
break;
}
}
}
if (!xhr) {
throw new Error("require.getXhr(): XMLHttpRequest not available");
}
return xhr;
}
if (typeof window !== "undefined" && window.navigator && window.document) {
fetchText = function (url, callback) {
var xhr = createXhr();
xhr.open('GET', url, true);
xhr.onreadystatechange = function (evt) {
//Do not explicitly handle errors, those should be
//visible via console output in the browser.
if (xhr.readyState === 4) {
callback(xhr.responseText);
}
};
xhr.send(null);
};
} else if (typeof process !== "undefined" &&