Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 154 lines (103 sloc) 4.618 kb
3c7cb79 James Burke start of project, still lots left to do.
authored
1 # require-hm
2
3 A simulation of some APIs that are proposed for ECMAScript Harmony for
4 JavaScript modules, but done as a loader plugin that works with
5 [RequireJS](http://requirejs.org), and other AMD loaders that support
6 the [loader plugin API](http://requirejs.org/docs/plugins.html) supported by
7 RequireJS.
8
9 The APIs are taken from here:
10
11 * [harmony:modules](http://wiki.ecmascript.org/doku.php?id=harmony:modules)
12 * [harmony:module_loaders](http://wiki.ecmascript.org/doku.php?id=harmony:module_loaders)
13 * [harmony:modules_examples](http://wiki.ecmascript.org/doku.php?id=harmony:modules_examples)
14
15 Not all the APIs are supported, see further below for more details.
16
17 ## Goals
18
19 The goal is to allow using harmony-like modules today, that work in today's
20 browsers and in Node. This allows playing with the APIs to make sure
21 they get some use and understanding before baking them into a standard.
22
23 It is also a way for me to experiment with the API and suggest changes in a way
24 that holds together in real code.
25
26 ## Limitations
27
254fcd8 James Burke Intermediate checkin for import, but not working
authored
28 The loader plugin cannot do the fancy compilation and linking that native
29 support can do, but it can simulate a lot of it.
3c7cb79 James Burke start of project, still lots left to do.
authored
30
31 This means some things that would be early errors in a native implementation are
254fcd8 James Burke Intermediate checkin for import, but not working
authored
32 not early errors with this approach.
3c7cb79 James Burke start of project, still lots left to do.
authored
33
254fcd8 James Burke Intermediate checkin for import, but not working
authored
34 ## Choices done outside the proposals
3c7cb79 James Burke start of project, still lots left to do.
authored
35
254fcd8 James Burke Intermediate checkin for import, but not working
authored
36 1) The harmony proposals do not define a way to translate dependency strings to
37 actual file paths, just mentions the ability to use URLs.
3c7cb79 James Burke start of project, still lots left to do.
authored
38
254fcd8 James Burke Intermediate checkin for import, but not working
authored
39 This plugin uses the AMD ID-to-path resolution for IDs.
40
41 2) .hm is used for the text files that are processed by this plugin, not .js
42 files. This is to help separate that these files are "special" and not regular
43 .js files.
44
45 ## Supported
46
47 export var foo = 'foo';
48 export function foo() {};
49 module Bar = 'Bar';
50
51 import y from Bar;
52 import {y} from Bar;
53 import { modProp: localProp } from Bar;
54 import * from Bar;
55
56 ## Unsupported
57
58 1) The following import variation is not supported, since the `module` form
59 is sufficient:
60
61 //Use `module Bar = 'Bar'` instead.
62 //This is not supported:
63 import "Bar.js" as Bar;
64
b98aece James Burke Now witness the firepower of this fully armed and operational battle sta...
authored
65 2) cyclical import * not supported.
66
67 Circular references that do import * on each other will not work.
68
7561347 James Burke Got example optimizer runs working
authored
69 3) import * does not work in build
70
71 Using r.js to optimize a set of hm modules to a concatenated list of AMD
72 modules works for everything except import *, since the build does not actually
73 run the * module as part of the build, since it may accesss environment-specific
74 information, like `window` or `navigator` which do not exist in Node.
75
76 4) Using identifiers for "inline modules" is not supported:
254fcd8 James Burke Intermediate checkin for import, but not working
authored
77
78 module Bar {}
79
80 What will be supported, but is not there yet, will be using string IDs,
81 since this matches better to `module Bar = 'Bar'` usage, particularly when
82 modules are combined in a build:
83
84 module 'Bar' {}
3c7cb79 James Burke start of project, still lots left to do.
authored
85
b98aece James Burke Now witness the firepower of this fully armed and operational battle sta...
authored
86 ## Installing
87
88 Grab the following files in this repo:
89
decedf3 James Burke Prep for 0.2.0 release
authored
90 * [hm.js](https://raw.github.com/jrburke/require-hm/latest/hm.js)
91 * [esprima.js](https://raw.github.com/jrburke/require-hm/latest/esprima.js)
92
9e1773f James Burke More notes for the readme install section
authored
93 and place them in the directory that is used as the baseUrl for your AMD-based
94 project.
95
decedf3 James Burke Prep for 0.2.0 release
authored
96 Or use [volo](https://github.com/volojs/volo):
97
98 volo add jrburke/require-hm
b98aece James Burke Now witness the firepower of this fully armed and operational battle sta...
authored
99
9e1773f James Burke More notes for the readme install section
authored
100 A special, modified version of esprima is used, so be sure to use the esprima.js
101 that is in this repo. A copy of esprima.js from the esprima project will not
102 work.
103
b98aece James Burke Now witness the firepower of this fully armed and operational battle sta...
authored
104 ## Configuration
105
106 You can pass the following configuration options to the loader plugin
107 via the requirejs
108 [the module config](http://requirejs.org/docs/api.html#config-moduleconfig):
109
110 ```javascript
111 requirejs.config({
112 config: {
113 hm: {
114 //Will log to console the before and
115 //after text.
116 logTransform: true
117 }
118 }
119 });
120
121 //Now start loading harmony modules
122 //This load main.hm, transpiles it to AMD
123 //then executes.
124 require(['hm!main'], function (main) {
125 console.log('main: ' + main);
126 });
127 ```
17ef472 James Burke Fix ups to allow running the tests in node
authored
128
7561347 James Burke Got example optimizer runs working
authored
129 ## Doing Builds
130
03e82d1 James Burke Small config/readme changes
authored
131 See `tests/build` for example build files (the *.build.js files).
7561347 James Burke Got example optimizer runs working
authored
132
133 The AMD version of the modules are placed in the built file, so the `hm` and
134 `esprima` modules do not need to be included in the build file.
135
136 See the build files for more details.
137
138 If any .hm files will be loaded dynamically after a build, then the source
139 versions of `hm` and `esprima` should stay in the build.
140
17ef472 James Burke Fix ups to allow running the tests in node
authored
141 ## Running Tests
142
143 ### In Browser
144
145 Open `tests/index.html` in a browser. Serve the tests from a web site,
146 since XMLHttpRequest (XHR) is used to fetch .hm, and some browsers have security
147 restrictions when using XHR from file:// URLs.
148
149 ### In Node
150
151 From within the `tests` directory:
152
153 node ../tools/r.js all-node.js
Something went wrong with that request. Please try again.