Permalink
Browse files

Doc updates for a 0.0.1 release.

  • Loading branch information...
1 parent a0e85b7 commit 94dde70776a7aad46cca2a67c1a5cdcc675e818c @jrburke committed Dec 9, 2011
Showing with 198 additions and 6 deletions.
  1. +58 −0 LICENSE
  2. +89 −3 README.md
  3. +27 −3 amdefine.js
  4. +21 −0 package.json
  5. +3 −0 tests/all.js
View
58 LICENSE
@@ -0,0 +1,58 @@
+amdefine 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) 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) 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.
View
@@ -1,16 +1,102 @@
# amdefine
-A module that can be used to implement AMD's define() in Node.
+A module that can be used to implement AMD's define() in Node. This allows you
+to code to the AMD API and have the module work in node programs without
+requiring those other programs to use AMD.
-More explanation here...
+## Usage
-Run sync, except require([], function() {}) where callback is triggered on nextTick
+**1)** Update your package.json to indicate amdefine as a dependency:
+```javascript
+ "dependencies": {
+ "amdefine": ">=0.0.1"
+ }
+```
+Then run `npm install` to get amdefine into your project.
+**2)** At the top of each module that uses define(), place this code:
+
+```javascript
+ if (typeof define !== 'function') { var define = (require('amdefine'))(module); }
+```
+
+**Only use this snippet** for loading amdefine. If you preserve the basic structure,
+with the braces, it will be stripped out when using the [RequireJS optimizer](#optimizer).
+
+You can add spaces, line breaks and even require amdefine with a local path, but
+keep the rest of the structure to get the stripping behavior.
+
+If you want to deliver amdefine.js with your code but not use the npm/node_modules-installed
+option, then just download the latest release and refer to it using a relative path:
+
+[Version 0.0.1](https://github.com/jrburke/amdefine/raw/0.0.1/amdefine.js)
+
+## define() usage
+
+It is best if you use the anonymous forms of define() in your module:
+
+```javascript
+ define(function (require) {
+ var dependency = require('dependency');
+ });
+```
+
+or
+
+```javascript
+ define(['dependency'], function (dependency) {
+
+ });
+```
+
+## RequireJS optimizer integration. <a name="optimizer"></name>
+
+Version 1.0.3 of the [RequireJS optimizer](http://requirejs.org/docs/optimization.html)
+will have support for stripping the `if (typeof define !== 'function')` check
+mentioned above, so you can include this snippet for code that runs in the
+browser, but avoid taking the cost of the if() statement once the code is
+optimized for deployment.
+
+## Limitations
+
+### Synchronous vs Asynchronous
+
+amdefine creates a define() function that is callable by your code. It will
+execute and trace dependencies and call the factory function *synchronously*,
+to keep the behavior in line with Node's synchronous dependency tracing.
+
+The exception: calling AMD's callback-style require() from inside a factory
+function. The require callback is called on process.nextTick():
+
+```javascript
+ define(function (require) {
+ require(['a'], function(a) {
+ //'a' is loaded synchronously, but
+ //this callback is called on process.nextTick().
+ });
+ });
+```
+
+### Loader Plugins
+
+Loader plugins are supported as long as they call their load() callbacks
+synchronously. So ones that do network requests will not work. However plugins
+like [text](http://requirejs.org/docs/api.html#text) can load text files locally.
+
+The plugin API's `load.fromText()` is **not supported** in amdefine, so this means
+transpiler plugins like the [CoffeeScript loader plugin](https://github.com/jrburke/require-cs)
+will not work. This may be fixable, but it is a bit complex, and I do not have
+enough node-fu to figure it out yet. See the source for amdefine.js if you want
+to get an idea of the issues involved.
## Tests
To run the tests, cd to **tests** and run:
node all.js
+
+## License
+
+New BSD and MIT. Check the LICENSE file for all the details.
View
@@ -1,3 +1,8 @@
+/** vim: et:ts=4:sw=4:sts=4
+ * @license amdefine 0.0.1 Copyright (c) 2011, The Dojo Foundation All Rights Reserved.
+ * Available via the MIT or new BSD license.
+ * see: http://github.com/jrburke/amdefine for details
+ */
/*jslint strict: false, nomen: false, plusplus: false */
/*global module, process, require: true */
@@ -22,12 +27,33 @@ function normalize(name, baseName) {
return path.normalize(path.join(baseName, name));
}
+/**
+ * Create the normalize() function passed to a loader plugin's
+ * normalize method.
+ */
function makeNormalize(relName) {
return function (name) {
return normalize(name, relName);
};
}
+function makeLoad(id) {
+ function load(value) {
+ loaderCache[id] = value;
+ }
+
+ load.fromText = function (id, text) {
+ //This one is difficult because the text can/probably uses
+ //define, and any relative paths and requires should be relative
+ //to that id was it would be found on disk. But this would require
+ //bootstrapping a module/require fairly deeply from node core.
+ //Not sure how best to go about that yet.
+ throw new Error('amdefine does not implement load.fromText');
+ };
+
+ return load;
+}
+
function stringRequire(module, id) {
//Split the ID by a ! so that
var index = id.indexOf('!'),
@@ -63,9 +89,7 @@ function stringRequire(module, id) {
if (loaderCache[id]) {
return loaderCache[id];
} else {
- plugin.load(id, makeRequire(module), function (value) {
- loaderCache[id] = value;
- }, {});
+ plugin.load(id, makeRequire(module), makeLoad(id), {});
return loaderCache[id];
}
View
@@ -0,0 +1,21 @@
+{
+ "name": "amdefine",
+ "description": "Provide AMD's define() API for declaring modules in the AMD format",
+ "version": "0.0.1",
+ "homepage": "http://github.com/jrburke/amdefine.js",
+ "author": "James Burke <jrburke@gmail.com> (http://github.com/jrburke)",
+ "licenses": [
+ {
+ "type": "BSD",
+ "url": "https://github.com/jrburke/amdefine/blob/master/LICENSE"
+ },
+ {
+ "type": "MIT",
+ "url": "https://github.com/jrburke/amdefine/blob/master/LICENSE"
+ }
+ ],
+ "main": "./amdefine.js",
+ "engines": {
+ "node": ">=0.6.0"
+ }
+}
View
@@ -27,7 +27,10 @@ load('doh/_' + env + 'Runner.js');
require("./basic/basic-tests");
require("./plugins/relative/relative-tests");
+
+//Cannot handle load.fromText for plugins yet, so commented out.
//require("./plugins/coffeescript/coffeescript-tests");
+
require("./require/require-tests");
//Print out the final report

0 comments on commit 94dde70

Please sign in to comment.