Skip to content
Newer
Older
100644 325 lines (254 sloc) 12.1 KB
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
1
a45a2be @paulbaumgart Added GitHub-only notice to indicate that the Documentation links in …
paulbaumgart authored
2 <script>
3 function addEvent(obj, evType, fn) {
4 if (obj.addEventListener){
5 obj.addEventListener(evType, fn, false);
6 return true;
7 } else if (obj.attachEvent){
8 var r = obj.attachEvent("on"+evType, fn);
9 return r;
10 } else {
11 return false;
12 }
13 }
14
15 addEvent(window, 'load',
16 function() {
17 document.getElementById('github_notice').style.display='none';
18 }
19 );
20 </script>
21
bbcd1b1 Minor docs updates
tlrobinson authored
22 Narwhal
23 =======
24
25 A general purpose JavaScript platform
26 -------------------------------------
fae12c6 Update README
tlrobinson authored
27
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
28 Narwhal is a cross-platform, multi-interpreter, general purpose JavaScript
29 platform. It aims to provide a solid foundation for building JavaScript
30 applications, primarily outside the web browser. Narwhal includes a package
31 manager, module system, and standard library for multiple JavaScript
32 interpreters. Currently Narwhal's [Rhino](http://www.mozilla.org/rhino/)
33 support is the most complete, but [other engines](engines.html) are available
34 too.
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
35
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
36 Narwhal's standard library conforms to the [CommonJS
37 standard](http://wiki.commonjs.org). It is designed to work with multiple
38 JavaScript interpreters, and to be easy to add support for new interpreters.
39 Wherever possible, it is implemented in pure JavaScript to maximize reuse of
40 code among engines.
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
41
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
42 Combined with [Jack](http://jackjs.org/), a
43 [Rack](http://rack.rubyforge.org/)-like
44 [JSGI](http://jackjs.org/jsgi-spec.html) compatible library, Narwhal provides a
45 platform for creating server-side JavaScript web applications and frameworks
46 such as [Nitro](http://www.nitrojs.org/).
fae12c6 Update README
tlrobinson authored
47
605cdfb @kriskowal Added some documentation and guides for narwhal, tusk, sea, and modul…
kriskowal authored
48
9a26adb Updated README to include links, irc, etc
tlrobinson authored
49 ### Homepage:
50
51 * [http://narwhaljs.org/](http://narwhaljs.org/)
52
53 ### Source & Download:
54
55 * [http://github.com/tlrobinson/narwhal/](http://github.com/tlrobinson/narwhal/)
56
57 ### Mailing list:
58
59 * [http://groups.google.com/group/narwhaljs](http://groups.google.com/group/narwhaljs)
60
61 ### IRC:
62
579f97c Improve Narwhal description, link to Freenode IRC web client
tlrobinson authored
63 * [\#narwhal on irc.freenode.net](http://webchat.freenode.net/?channels=narwhal)
9a26adb Updated README to include links, irc, etc
tlrobinson authored
64
65
65b494d @kriskowal Refactored README and docs.
kriskowal authored
66 Documentation
67 -------------
fae12c6 Update README
tlrobinson authored
68
a45a2be @paulbaumgart Added GitHub-only notice to indicate that the Documentation links in …
paulbaumgart authored
69 <div id="github_notice">
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
70 <strong>Note:</strong> If you are viewing this on GitHub, the links below will
71 not work. Find the pages listed below in the <strong>docs/</strong> directory
72 of this repository.
a45a2be @paulbaumgart Added GitHub-only notice to indicate that the Documentation links in …
paulbaumgart authored
73 </div>
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
74
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
75 * [Quick Start](quick-start.html)
76 * [Packages](packages.html)
77 * [How to Install Packages](packages.html)
78 * [How to Build Packages](packages-howto.html)
79 * [Modules](modules.html)
80 * [Virtual Environments / Seas](sea.html)
a18eaf5 @kriskowal s/platform/engine/gi
kriskowal authored
81 * [How to Build Engines](engines.html)
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
82 * [How Narwhal Works](narwhal.html)
a1ae6b4 @kriskowal Updated instructions for creating new platforms for Narwhal, with mor…
kriskowal authored
83
8f24e60 @kriskowal Expanded README.md to include some of the more important documentatio…
kriskowal authored
84 ### Quick Start
85
86 Download Narwhal.
87
88 * download and extract the
89 [zip](http://github.com/280north/narwhal/zipball/0.2) or
90 [tar](http://github.com/tlrobinson/narwhal/tarball/0.2) archive, or
91 * `git clone git://github.com/280north/narwhal.git`
92
93 Put Narwhal on your `PATH` environment variable.
94
95 * `export PATH=$PATH:~/narwhal/bin`, or
96 * `source narwhal/bin/activate`
97
98 Run `narwhal` or `js` (they are equivalent).
99
100 * `js narwhal/examples/hello`
101
102 Look at the options for Narwhal.
103
104 * `js --help`
105
106 And for Tusk, the package manager and virtual environment tool.
107
108 * `tusk help`
109
110 ### My First Web Server
111
112 Create a project "hello-web".
113
114 tusk init hello-web
115 cd hello-web
116
117 Enter your project as a "virtual environment" using `activate` or `sea` so that
118 its libraries, binaries, and packages get automatically installed when you run
119 Narwhal.
120
121 source bin/activate
122
123 or
124
125 bin/sea
126
127 Install some packages you will need, like Jack, the JSGI standard library for
128 interoperable web services.
129
130 tusk install jack
131
132 Tusk gets downloaded and installed at "hello-web/packages/jack".
133
134 Create your `jackconfig.js`.
135
136 exports.app = function(env) {
137 var text = "Hello, Web!";
138 return {
139 status : 200,
140 headers : {
141 "Content-Type" : "text/plain",
142 "Content-Length" : String(text.length)
143 },
144 body : [text]
145 };
146 };
147
148 Run it!
149
150 jackup
151
152 `jackup` looks for a file called `jackconfig.js` in the current directory, or
153 you can specify a path to a Jack application.
154
155 Open [http://localhost:8080/](http://localhost:8080/) in your web browser.
156
157 ### Module System Basics
158
159 Narwhal "scripts" are [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1)
160 compatible modules, much like Python or Ruby modules. You do not have to use
161 module pattern boilerplate; every module has its own local scope. You can get
162 the exports object of another module by calling `require`.
163
164 var FS = require("file");
165 FS.isFile("foo.txt");
166
167 Module identifiers for `require` come in three flavors: "top-level",
168 "relative", and "absolute". In the above case, `file` is a "top-level"
169 identifier, so it will load any module called `file.js` in the `lib` directory
170 of whichever package comes first in the load path. Relative identifiers have
171 `.` or `..` as their first term, and terms are delimited with `/`. So, in the
172 `foo/bar` module, `require('./baz')` will load `foo/baz`. Absolute module
173 identifiers should not be used directly, but are produced when you execute a
174 program module outside the module path. The module is identified by its
175 fully-qualified path, starting with `/`.
176
177 You can export an object by assigning it to `exports`.
178
179 exports.foo = function () {
180 return "Hello";
181 };
182
183 In a module, you also get a `module` object that has `module.id` and
184 `module.path` properties so you can inspect your own top-level module
185 identifier, and the path of your own module file. You also get a
186 `require.main` property that tells you the top-level module identifier of the
187 module that started the program.
188
189 if (require.main == module)
190 main();
191
192 var settings = require(require.main);
193
194 var FS = require("file");
195 var path = FS.path(module.path);
196 var indexHtml = path.resolve("./template/index.html").read();
197
198 Beyond the CommonJS specification, you also get the `print` function and the
199 `system` module object for free. The `print` function accepts variadic
200 arguments and writes a single line containing the arguments delimited by spaces
201 to standard output and flushes. The `system` module can be explicitly required
202 with `require("system")` as is encouraged since it is necessary for CommonJS
203 compliance. Do not use `print` or `system` in standard libraries.
204
205
206 ### Summary of Included Modules
207
208 * `system`: `args`, `env`, `stdin`, `stdout`, `stderr`
209 * `io`: `ByteIO` (`read`, `write`, `toByteString`, `toString`), `StringIO`
210 (`read`, `write`, `copy`, `flush`, `iterator`, `forEach`, `readLine`,
211 `readLines`, `next`, `print`, `toString`, `substring`, `slice`, `substr`), `IO`
212 (`read`, `write`, `copy`, `flush`, `close`, `isatty`), `TextInputStream`
213 (`raw`, `readLine`, `next`, `iterator`, `forEach`, `close`), `TextOutputStream`
214 (`write`, `writeLine`, `writeLines`, `print`, `flush`, `close`)
215 * `file`: `open`, `read`, `write`, `copy`, `link`, `symlink`, `rename`,
216 `move`, `remove`, `mkdir`, `mkdirs`, `rmdir`, `rmtree`, `touch`, `chmod`,
217 `chown`, `list`, `listTree`, `listDirectoryTree`, `copyTree`, `isAbsolute`,
218 `isRelative`, `isDrive`, `isReadable`, `isWritable`, `glob`, `globPaths`,
219 `fnmatch`, `match`, `cwd`, `cwdPath`, `join`, `split`, `resolve`,
220 `relative`, `absolute`, `normal`, `canonical`, `root`, `dirname`,
221 `basename`, `extension`, `path`, `new Path` (`to`, `from`, ...)
222 * `os`: `exit`, `sleep`, `popen` (`wait`, `stdin`, `stdout`, `stderr`,
223 `communicate` (`status`, `stdin`, `stdout`, `stderr`)), `system`, `command`,
224 `status`, `enquote`
225 * `binary`: `Binary` (`toArray`, `toByteArray`, `toByteString`, `indexOf`,
226 `lastIndexOf`, `valueOf`), `ByteString` (`length`, `toString`, `split`,
227 `slice`, `substr`, `substring`, `toSource`), `ByteArray` (`toString`, `pop`,
228 `push`, `extendRight`, `unshift`, `extendLeft`, `reverse`, `slice`,
229 `splice`, `split`, `forEach`, `every`, `some`, `map`, `reduce`,
230 `reduceRight`, `displace`, `toSource`)
231 * `assert`: `AssertionError`, `fail`, `ok`, `equal`, `notEqual`, `deepEqual`,
232 `notDeepEqual`, `strictEqual`, `notStrictEqual`, `throws`, `Assert` (`pass`,
233 `error`, `section`)
234 * `test`: `run`, `Log` (`flush`, `pass`, `fail`, `error`, `begin`, `end`,
235 `report`, `print`, `section`, `Assert`), `Section` (`print`)
236 * `util`: `operator`, `no`, `object`, `array`, `string`, `apply`, `copy`,
237 `deepCopy`, `repr`, `keys`, `values`, `items`, `len`, `has`, `get`, `set`,
238 `getset`, `cut`, `put`, `first`, `last`, `update`, `deepUpdate`, `complete`,
239 `deepComplete`, `remove`, `range`, `forEach`, `forEachApply`, `map`,
240 `mapApply`, `every`, `some`, `all`, `any`, `reduce`, `reduceRight`, `zip`,
241 `transpose`, `enumerate`, `is`, `eq`, `ne`, `lt`, `gt`, `le`, `ge`, `mul`,
242 `by`, `compare`, `sort`, `sorted`, `reverse`, `reversed`, `hash`, `unique`,
243 `escape`, `enquote`, `expand`, `trim`, `trimBegin`, `trimEnd`, `padBegin`,
244 `padEnd`, `splitName`, `joinName`, `lower`, `upper`, `camel`, `title`
245 * `http`: `open`, `read`
246 * `sha`, `sha256`, `md5`, `md4`, `crc32`: `hash`
247 * `utf8`, `base64`, `base16`: `encode`, `decode`
248 * `jsmin`: `encode`
249 * `jsonpath`: `resolve`
250 * `logger`: `Logger` (`add`, `format`)
251 * `args`: `Parser` (`parse`, `option`, (`_`, `__`, `name`, `displayName`,
252 `getName`, `getDisplayName`, `action`, `set`, `push`, `inc`, `dec`,
253 `choices`, `def`, `validate`, `input`, `output`, `number`, `oct`, `hex`,
254 `integer`, `natural`, `whole`, `bool`, `todo`, `inverse`, `help`, `halt`,
255 `hidden`), `group` (`option`), `def`, `reset`, `command`, `arg`, `args`,
256 `act`, `action`, `helpful`, `usage`, `help`, `printHelp`, `printUsage`,
257 `printCommands`, `printOption`, `printOptions`, `error`, `exit`, `print`,
258 `check`), `UsageError`, `ConfigurationError`
259 * `term`: `Stream` (`enable`, `disable`, `writeCode`, `print`, `printError`,
260 `write`, `update`, `moveTo`, `moveBy`, `home`, `clear`, `clearUp`,
261 `clearDown`, `clearLine`, `clearRight`, `error` (`print`, `write`)),
262 `colors`, `stream`
263 * `uuid`: `uuid`
264 * `mime`: `bestMatch`, `parseMimeType`, `parseMediaRange`,
265 `fitnessAndQualityParsed`, `qualityParsed`, `quality`
266 * `html`: `escapeHTML`, `stripTags`
267 * `ref-send`, `promise`, `events`: `when`, `defer` (`resolve`, `reject`,
268 `promise`),
269 * `event-loop`: `enqueue`
270 * `printf`: `printf`, `fprintf`, `sprintf`
271 * `querystring`: `unescape`, `escape`, `stringify`, `parseQuery`
272 * `sandbox`: `Sandbox`
273 * `loader`: `Loader` (`resolve`, `resolvePkg`, `find`, `fetch`, `load`,
274 `reload`, `isLoaded`, `hasChanged`, `paths`, `extensions`), `resolve`,
275 `resolvePkg`
276 * `packages`: `order`, `catalog`
277 * `interpreter`: `Context` (`eval`, `importScript`, `importScripts`, `Module`,
278 `Function`)
279 * `zip`: `unzip`, `Unzip` (`iterator`, `forEach`, `close`), `Entry`
280 (`getName`, `isDirectory`, `open`, `read`, `copy`)
fae12c6 Update README
tlrobinson authored
281
282 Contributors
283 ------------
284
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
285 * [Tom Robinson](http://tlrobinson.net/)
286 * [Kris Kowal](http://askawizard.blogspot.com/)
2066341 Added htmlparser and normal-template to catalog.
tlrobinson authored
287 * [George Moschovitis](http://www.gmosx.com/)
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
288 * [Kevin Dangoor](http://www.blueskyonmars.com/)
cba211a Updated README contributor list
tlrobinson authored
289 * Hannes Wallnöfer
d02bc6d @kriskowal More documentation updates, credits in particular.
kriskowal authored
290 * Sébastien Pierre
291 * Irakli Gozalishvili
5e4a606 Christoph link
Tom Robinson authored
292 * [Christoph Dorn](http://www.christophdorn.com/)
d02bc6d @kriskowal More documentation updates, credits in particular.
kriskowal authored
293 * Zach Carter
bbcd1b1 Minor docs updates
tlrobinson authored
294 * Nathan L. Smith
e98dae6 Merge README.md with doc/index.md, and update with new description/co…
tlrobinson authored
295 * Jan Varwig
296 * Mark Porter
10a60b1 @kriskowal Updated credits.
kriskowal authored
297 * [Isaac Z. Schlueter](http://blog.izs.me/)
20ebcef @kriszyp Update my URL in the credits
kriszyp authored
298 * [Kris Zyp](http://www.sitepen.com/blog/author/kzyp/)
c51ab41 @kriskowal Updated credits.
kriskowal authored
299 * [Nathan Stott](http://nathan.whiteboard-it.com/)
3cd41d7 @kriskowal Credited Toby Ho for his bug fix.
kriskowal authored
300 * [Toby Ho](http://tobyho.com)
fae12c6 Update README
tlrobinson authored
301
302
303 License
304 -------
305
7524d20 Update sources, catalog, README
Tom Robinson authored
306 Copyright (c) 2009, 280 North Inc. <[280north.com](http://280north.com/)\>
fae12c6 Update README
tlrobinson authored
307
308 Permission is hereby granted, free of charge, to any person obtaining a copy
309 of this software and associated documentation files (the "Software"), to
310 deal in the Software without restriction, including without limitation the
311 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
312 sell copies of the Software, and to permit persons to whom the Software is
313 furnished to do so, subject to the following conditions:
314
315 The above copyright notice and this permission notice shall be included in
316 all copies or substantial portions of the Software.
317
318 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
319 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
320 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
321 THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
322 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
323 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
d02bc6d @kriskowal More documentation updates, credits in particular.
kriskowal authored
324
Something went wrong with that request. Please try again.