Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 272 lines (184 sloc) 7.669 kb
0bbeee9 @ariya Use markdown README.
ariya authored
1 HammerJS is a powerful JavaScript shell. It uses [V8](http://v8.googlecode.com), the fast JavaScript engine for Google Chrome, as the back-end.
f078b9b @ariya Long live HammerJS!
ariya authored
2
0bbeee9 @ariya Use markdown README.
ariya authored
3 HammerJS has a rich set of API to do file I/O, system access, and syntax parsing.
4
5 **Warning**: HammerJS is still in the development so the API is not final and might change at any time.
6
267f74f @ariya Clarify the build steps, per platform.
ariya authored
7 # Build instructions
0bbeee9 @ariya Use markdown README.
ariya authored
8
d9600fe @ariya Simplify the build instructions.
ariya authored
9 Building HammerJS is as easy as:
cbc41d4 @ariya Info on parallel make jobs.
ariya authored
10
d9600fe @ariya Simplify the build instructions.
ariya authored
11 ./configure
bcd7758 @ariya Adjust the build instructions, after the CMake change.
ariya authored
12 make
f078b9b @ariya Long live HammerJS!
ariya authored
13
d9600fe @ariya Simplify the build instructions.
ariya authored
14 To install the executable (with the target directory <code>/usr/local/bin</code>):
0a0f4bc @ariya Add Visual Studio/C++ build instructions.
ariya authored
15
d9600fe @ariya Simplify the build instructions.
ariya authored
16 make install
0a0f4bc @ariya Add Visual Studio/C++ build instructions.
ariya authored
17
d9600fe @ariya Simplify the build instructions.
ariya authored
18 Alternatively copy <code>hammerjs</code> executable to some directory in the PATH.
0a0f4bc @ariya Add Visual Studio/C++ build instructions.
ariya authored
19
d9600fe @ariya Simplify the build instructions.
ariya authored
20 For more detailed instructions, see the INSTALL file.
784caf6 @ariya Add the experimental build info for MinGW on Windows.
ariya authored
21
84e314b @ariya Emphasize build tips.
ariya authored
22 **Tips**:
23
24 * Runs <code>make -j4</code> to build in parallel, especially on multi-core machines.
25 * <code>strip hammerjs</code> reduces the executable file size (for deployment).
26
446f1fe @ariya Add a little bit info on using it.
ariya authored
27 # Quick Start
28
29 The typical usage is:
30
31 hammerjs script.js foo bar baz
32
33 where <code>script.js</code> will be executed by HammerJS. The three arguments (foo, bar, baz) will be available from the script.
34
35 Pretty much standard JavaScript code will run with HammerJS. Since it is pure JavaScript interpreter, obviously it does not have support for DOM objects.
36
37 Here is the simplest HammerJS script, <code>hello.js</code>:
38
39 system.print('Hello','world!');
40 system.exit();
41
42 which can be executed by running
43
44 hammerjs hello.js
45
46 For more examples, see the Examples section below.
47
0bbeee9 @ariya Use markdown README.
ariya authored
48 # API
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
49
50 There are few objects at the global scope: 'system', 'fs', and 'Reflect'.
51
0bbeee9 @ariya Use markdown README.
ariya authored
52 ## system
53
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
54 'system' object has the following functions:
55
56 * print(obj, ...) displays obj as a string to the console output.
e0f3e71 @ariya Document the Stream object.
ariya authored
57 It is possible to print several objects separated by comma,
58 the output will be separated by white space.
0bbeee9 @ariya Use markdown README.
ariya authored
59
60 Example:
61
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
62 system.print('Hello', 'world');
63
64 * exit(status) terminates the application and returns the status.
65 If status is not specified, 0 is returned instead.
0bbeee9 @ariya Use markdown README.
ariya authored
66
67 Example:
68
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
69 if (error)
70 system.exit(1);
71 else
72 system.exit(0);
73
74 * execute(cmd) pauses the application and runs the specified command
75 externally. This is useful to transfer the control to another
76 shell or utility.
77
83ce199 @ariya Implement system.sleep() function.
ariya authored
78 * sleep(sec) blocks the execution for the specified duration (in
79 seconds).
80
81 Example:
82
83 system.print('Pause for a moment...');
84 system.sleep(0.3);
85
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
86 'system' object has the following property:
87
88 * args, an array of string which contain all the arguments passed when
89 invoking the script. The first string, i.e. args[0], is always the
90 name of the script. See the example/args.js for details.
91
4c964f3 @ariya Fix wrong header position.
ariya authored
92 ## fs
93
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
94 'fs' object has the following functions:
95
96 * exists(path) returns true if the specified path exists, otherwise
97 returns false.
0bbeee9 @ariya Use markdown README.
ariya authored
98
99 Example:
100
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
101 if (fs.exists('/etc/passwd')) {
102 system.print('You have passwd file');
103 }
104
105 * isDirectory(path) returns true if the specified path is a directory
106 (not a file), otherwise returns false.
107
108 * isFile(path) returns true if the specified path is a file (not
109 a directory), otherwise returns false.
110
111 * makeDirectory(path) creates a new directory if the directory does not
112 exist yet.
113
114 * list(path) finds all the files and subdirectories in the specified
115 path and returns it as an array of string.
116
117 * open(fileName, mode) opens the specified file and returns a Stream
118 object which can be used to read or write to the file. The file
119 will be opened for read operation if mode is 'r' or write operation
120 if mode is 'w'. If the file can not be opened, an exception is thrown.
121
122 * workingDirectory() returns the current working directory.
123
bfd9bc6 @ariya Add read-only fs.pathSeparator.
ariya authored
124 'fs' object has the following property:
125
126 * pathSeparator (read-only), a single-character that denotes the separator
127 for the path name.
128
0bbeee9 @ariya Use markdown README.
ariya authored
129 ## Reflect
130
5525870 @ariya Document Reflect object.
ariya authored
131 'Reflect' object has the following functions:
132
133 * parse(code) returns JSON-formatted syntax tree corresponding to the code.
b304c0b @ariya Better hyperlink to the parser API reference.
ariya authored
134 See [SpiderMonkey Parser API](https://wiki.mozilla.org/JavaScript:SpiderMonkey:Parser_API) for the
5525870 @ariya Document Reflect object.
ariya authored
135 details of the syntax tree structure.
0bbeee9 @ariya Use markdown README.
ariya authored
136
137 Example:
138
aabd17a @ariya Give an example of Reflect.parse() output.
ariya authored
139 Reflect.parse("var answer = 42;");
140
0bbeee9 @ariya Use markdown README.
ariya authored
141 will give the following output:
142
aabd17a @ariya Give an example of Reflect.parse() output.
ariya authored
143 {
144 "type": "Program",
145 "body": [
146 {
147 "type": "VariableDeclaration",
148 "declarations": [
149 {
150 "type": "AssignmentExpression",
151 "operator": "=",
152 "left": {
153 "type": "Identifier",
154 "name": "answer"
155 },
156 "right": {
157 "type": "Literal",
158 "value": "42"
159 }
160 }
161 ]
162 }
163 ]
164 }
5525870 @ariya Document Reflect object.
ariya authored
165
0bbeee9 @ariya Use markdown README.
ariya authored
166 ## Stream
167
e0f3e71 @ariya Document the Stream object.
ariya authored
168 Stream is created using fs.open(path). It has the following functions:
169
170 * close() flushes pending buffer and closes the stream. Further operation
171 on a closed stream will throw an exception.
172
173 * flush() ensures that pending data to be written is flushed to the file
174 system.
175
176 * next() reads a line from the stream. If there is nothing more to read
177 (end of file), an exception is thrown.
178
179 * readLine() reads a line from the stream, including the '\n' suffix.
180 If there is nothing more to read (end of file), an empty string is
181 returned instead.
182
183 * writeLine() writes a string to the stream and then appends '\n'.
184
0bbeee9 @ariya Use markdown README.
ariya authored
185 # Examples
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
186
0bbeee9 @ariya Use markdown README.
ariya authored
187 All the example scripts below are available in the <code>examples/</code> directory.
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
188
0bbeee9 @ariya Use markdown README.
ariya authored
189 <code>hello.js</code>: Shows a simple text message.
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
190
191 system.print('Hello','world!');
192 system.exit();
193
0bbeee9 @ariya Use markdown README.
ariya authored
194 <code>args.js</code>: Displays all the arguments passed to the script.
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
195
196 if (system.args.length === 1) {
197 system.print('Try to pass some args when invoking this script!');
198 } else {
199 system.args.forEach(function (arg, i) {
200 system.print(i + ': ' + arg);
201 });
202 }
203 system.exit();
204
205 Example output:
d8875a4 @ariya Fix the markdown for the example output.
ariya authored
206
3dc9cbf @ariya Document some of the API. Not finished yet.
ariya authored
207 > hammerjs args.js Foo Bar
208 0: args.js
209 1: Foo
210 2: Bar
211
0bbeee9 @ariya Use markdown README.
ariya authored
212 <code>scandir.js</code>: Recursively traverses directory and prints all found *.js files.
6d8ca71 @ariya Example scandir.js to do recursive traversal of file system.
ariya authored
213
214 if (system.args.length !== 2) {
215 system.exit(-1);
216 }
217 var scanDirectory = function (path) {
218 if (fs.exists(path) && fs.isFile(path) && path.match('.js$')) {
219 system.print(path);
220 } else if (fs.isDirectory(path)) {
221 fs.list(path).forEach(function (e) {
222 scanDirectory(path + '/' + e);
223 });
224 }
225 };
226 scanDirectory(system.args[1]);
227
0bbeee9 @ariya Use markdown README.
ariya authored
228 <code>syntax.js</code>: Loads a script file and prints the syntax tree.
6393229 @ariya Example syntax.js which dumps the syntax tree.
ariya authored
229
6d8ca71 @ariya Example scandir.js to do recursive traversal of file system.
ariya authored
230 var f, line, content = '';
231 if (system.args.length !== 2) {
232 system.exit(-1);
233 }
234 f = fs.open(system.args[1], 'r');
235 while (true) {
236 line = f.readLine();
237 if (line.length === 0) {
238 break;
239 }
240 content += line;
241 }
242 f.close();
0bbeee9 @ariya Use markdown README.
ariya authored
243 system.print(JSON.stringify(Reflect.parse(content), undefined, 4));
9748f2d @ariya Activate debugging support when building in debug mode.
ariya authored
244
49c6f20 @ariya Bring back the debugger support.
ariya authored
245 # Debugging
246
be95b45 @ariya Revamp the debugger support.
ariya authored
247 Requirement: [node-inspector](https://github.com/dannycoates/node-inspector).
248 Note: This may change in the future and HammerJS will have its own
249 built-in debugger handler.
49c6f20 @ariya Bring back the debugger support.
ariya authored
250
be95b45 @ariya Revamp the debugger support.
ariya authored
251 Run the script as usual but with <code>--debug</code> option, e.g.:
49c6f20 @ariya Bring back the debugger support.
ariya authored
252
be95b45 @ariya Revamp the debugger support.
ariya authored
253 hammerjs --debug examples/countdown.js
49c6f20 @ariya Bring back the debugger support.
ariya authored
254
be95b45 @ariya Revamp the debugger support.
ariya authored
255 Instead of running the script directly, now HammerJS pauses until the
256 debugger starts.
49c6f20 @ariya Bring back the debugger support.
ariya authored
257
be95b45 @ariya Revamp the debugger support.
ariya authored
258 Run the node-inspector:
49c6f20 @ariya Bring back the debugger support.
ariya authored
259
260 node-inspector
261
262 Open a WebKit-based web browser, e.g. Safari or Chrome, then go to the
263 following URL:
264
be95b45 @ariya Revamp the debugger support.
ariya authored
265 http://0.0.0.0:8080/debug?port=5858
49c6f20 @ariya Bring back the debugger support.
ariya authored
266
267 Now it is possible to breakpoint, single step, run/pause, add watch, and
268 so on from the debugger interface.
269
be95b45 @ariya Revamp the debugger support.
ariya authored
270 HammerJS also understand <code>debugger</code> statement inside the
271 script (if any) and always breaks there.
Something went wrong with that request. Please try again.