Skip to content
Newer
Older
100644 272 lines (184 sloc) 7.49 KB
0bbeee9 Use markdown README.
Ariya Hidayat 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 Long live HammerJS!
Ariya Hidayat authored
2
0bbeee9 Use markdown README.
Ariya Hidayat 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 Clarify the build steps, per platform.
Ariya Hidayat authored
7 # Build instructions
0bbeee9 Use markdown README.
Ariya Hidayat authored
8
d9600fe Simplify the build instructions.
Ariya Hidayat authored
9 Building HammerJS is as easy as:
cbc41d4 Info on parallel make jobs.
Ariya Hidayat authored
10
d9600fe Simplify the build instructions.
Ariya Hidayat authored
11 ./configure
bcd7758 Adjust the build instructions, after the CMake change.
Ariya Hidayat authored
12 make
f078b9b Long live HammerJS!
Ariya Hidayat authored
13
d9600fe Simplify the build instructions.
Ariya Hidayat authored
14 To install the executable (with the target directory <code>/usr/local/bin</code>):
0a0f4bc Add Visual Studio/C++ build instructions.
Ariya Hidayat authored
15
d9600fe Simplify the build instructions.
Ariya Hidayat authored
16 make install
0a0f4bc Add Visual Studio/C++ build instructions.
Ariya Hidayat authored
17
d9600fe Simplify the build instructions.
Ariya Hidayat authored
18 Alternatively copy <code>hammerjs</code> executable to some directory in the PATH.
0a0f4bc Add Visual Studio/C++ build instructions.
Ariya Hidayat authored
19
d9600fe Simplify the build instructions.
Ariya Hidayat authored
20 For more detailed instructions, see the INSTALL file.
784caf6 Add the experimental build info for MinGW on Windows.
Ariya Hidayat authored
21
84e314b Emphasize build tips.
Ariya Hidayat 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 Add a little bit info on using it.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
48 # API
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
49
50 There are few objects at the global scope: 'system', 'fs', and 'Reflect'.
51
0bbeee9 Use markdown README.
Ariya Hidayat authored
52 ## system
53
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
54 'system' object has the following functions:
55
56 * print(obj, ...) displays obj as a string to the console output.
e0f3e71 Document the Stream object.
Ariya Hidayat authored
57 It is possible to print several objects separated by comma,
58 the output will be separated by white space.
0bbeee9 Use markdown README.
Ariya Hidayat authored
59
60 Example:
61
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
66
67 Example:
68
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat 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 Implement system.sleep() function.
Ariya Hidayat 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 Document some of the API. Not finished yet.
Ariya Hidayat 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 Fix wrong header position.
Ariya Hidayat authored
92 ## fs
93
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
94 'fs' object has the following functions:
95
96 * exists(path) returns true if the specified path exists, otherwise
97 returns false.
0bbeee9 Use markdown README.
Ariya Hidayat authored
98
99 Example:
100
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat 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 Add read-only fs.pathSeparator.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
129 ## Reflect
130
5525870 Document Reflect object.
Ariya Hidayat authored
131 'Reflect' object has the following functions:
132
133 * parse(code) returns JSON-formatted syntax tree corresponding to the code.
b304c0b Better hyperlink to the parser API reference.
Ariya Hidayat authored
134 See [SpiderMonkey Parser API](https://wiki.mozilla.org/JavaScript:SpiderMonkey:Parser_API) for the
5525870 Document Reflect object.
Ariya Hidayat authored
135 details of the syntax tree structure.
0bbeee9 Use markdown README.
Ariya Hidayat authored
136
137 Example:
138
aabd17a Give an example of Reflect.parse() output.
Ariya Hidayat authored
139 Reflect.parse("var answer = 42;");
140
0bbeee9 Use markdown README.
Ariya Hidayat authored
141 will give the following output:
142
aabd17a Give an example of Reflect.parse() output.
Ariya Hidayat 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 Document Reflect object.
Ariya Hidayat authored
165
0bbeee9 Use markdown README.
Ariya Hidayat authored
166 ## Stream
167
e0f3e71 Document the Stream object.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
185 # Examples
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
186
0bbeee9 Use markdown README.
Ariya Hidayat authored
187 All the example scripts below are available in the <code>examples/</code> directory.
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
188
0bbeee9 Use markdown README.
Ariya Hidayat authored
189 <code>hello.js</code>: Shows a simple text message.
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
190
191 system.print('Hello','world!');
192 system.exit();
193
0bbeee9 Use markdown README.
Ariya Hidayat authored
194 <code>args.js</code>: Displays all the arguments passed to the script.
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat 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 Fix the markdown for the example output.
Ariya Hidayat authored
206
3dc9cbf Document some of the API. Not finished yet.
Ariya Hidayat authored
207 > hammerjs args.js Foo Bar
208 0: args.js
209 1: Foo
210 2: Bar
211
0bbeee9 Use markdown README.
Ariya Hidayat authored
212 <code>scandir.js</code>: Recursively traverses directory and prints all found *.js files.
6d8ca71 Example scandir.js to do recursive traversal of file system.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
228 <code>syntax.js</code>: Loads a script file and prints the syntax tree.
6393229 Example syntax.js which dumps the syntax tree.
Ariya Hidayat authored
229
6d8ca71 Example scandir.js to do recursive traversal of file system.
Ariya Hidayat 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 Use markdown README.
Ariya Hidayat authored
243 system.print(JSON.stringify(Reflect.parse(content), undefined, 4));
9748f2d Activate debugging support when building in debug mode.
Ariya Hidayat authored
244
49c6f20 Bring back the debugger support.
Ariya Hidayat authored
245 # Debugging
246
be95b45 Revamp the debugger support.
Ariya Hidayat 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 Bring back the debugger support.
Ariya Hidayat authored
250
be95b45 Revamp the debugger support.
Ariya Hidayat authored
251 Run the script as usual but with <code>--debug</code> option, e.g.:
49c6f20 Bring back the debugger support.
Ariya Hidayat authored
252
be95b45 Revamp the debugger support.
Ariya Hidayat authored
253 hammerjs --debug examples/countdown.js
49c6f20 Bring back the debugger support.
Ariya Hidayat authored
254
be95b45 Revamp the debugger support.
Ariya Hidayat authored
255 Instead of running the script directly, now HammerJS pauses until the
256 debugger starts.
49c6f20 Bring back the debugger support.
Ariya Hidayat authored
257
be95b45 Revamp the debugger support.
Ariya Hidayat authored
258 Run the node-inspector:
49c6f20 Bring back the debugger support.
Ariya Hidayat 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 Revamp the debugger support.
Ariya Hidayat authored
265 http://0.0.0.0:8080/debug?port=5858
49c6f20 Bring back the debugger support.
Ariya Hidayat 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 Revamp the debugger support.
Ariya Hidayat 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.