Doc updates for a 0.0.1 release.

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.

README.md

@@ -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.

amdefine.js

@@ -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];
         }

package.json

@@ -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"
+    }
+}

tests/all.js

@@ -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