X Tutup
Skip to content
This repository was archived by the owner on Jun 5, 2020. It is now read-only.

Commit fe9ec4e

Browse files
dcodeIOdcodeIO
committed
README, docs
1 parent 6c84e13 commit fe9ec4e

File tree

14 files changed

+2538
-29
lines changed

14 files changed

+2538
-29
lines changed

‎MetaScript.js‎

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,18 @@
2020
* see: https://github.com/dcodeIO/MetaScript for details
2121
*/ //
2222
(function(global) {
23-
// not strict
23+
// not strict for global var shenanigans
2424

25-
// This is a rather small program with lots of comments, so everyone can hack it easily.
26-
2725
/**
2826
* Constructs a new MetaScript instance.
27+
* @exports MetaScript
2928
* @param {string=} source Source to compile
3029
* @constructor
3130
*/
3231
var MetaScript = function(source) {
3332

3433
/**
35-
* Meta program.
34+
* Meta program source.
3635
* @type {?string}
3736
*/
3837
this.program = typeof source !== 'undefined' ? MetaScript.compile(source) : null;
@@ -64,7 +63,7 @@
6463
out = []; // Output stack
6564

6665
// Escapes a string to be used in a JavaScript string enclosed in single quotes
67-
function escape(s) {
66+
function escapestr(s) {
6867
return s.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\r/g, '\\r').replace(/\n/g, '\\n');
6968
}
7069

@@ -88,11 +87,11 @@
8887
match;
8988
while (match = expr.exec(source)) {
9089
s = source.substring(index, match.index+1);
91-
if (s !== '') out.push(' write(\''+escape(s)+'\');\n');
90+
if (s !== '') out.push(' write(\''+escapestr(s)+'\');\n');
9291
index = match.index+1;
9392
}
9493
s = source.substring(index, source.length);
95-
if (s !== '') out.push(' write(\''+escape(s)+'\');\n');
94+
if (s !== '') out.push(' write(\''+escapestr(s)+'\');\n');
9695
}
9796

9897
// Turn the meta inside out:
@@ -117,7 +116,7 @@
117116

118117
// Expose indentation and evaluate expression
119118
if (indent !== lastIndent) {
120-
out.push('__=\''+escape(lastIndent = indent)+'\';\n');
119+
out.push('__=\''+escapestr(lastIndent = indent)+'\';\n');
121120
}
122121
out.push(evaluate(source.substring(match.index+3, matchEnd.index).trim()));
123122
if (match[2] === '=')
@@ -141,7 +140,7 @@
141140

142141
// Expose indentation and evaluate expression
143142
if (indent !== lastIndent) {
144-
out.push('__=\''+escape(lastIndent = indent)+'\';\n');
143+
out.push('__=\''+escapestr(lastIndent = indent)+'\';\n');
145144
}
146145
out.push(evaluate(source.substring(match.index+3, matchEnd.index).trim()));
147146

@@ -176,16 +175,17 @@
176175
*/
177176
MetaScript.transform = function(source, scope, basedir) {
178177
if (MetaScript.IS_NODE) {
179-
var sandbox;
180-
require("vm").runInNewContext('__result = new MetaScript(__source).transform(__scope, __basedir);', sandbox = {
181-
__source: source,
182-
__scope: scope,
183-
__basedir: basedir,
184-
MetaScript: MetaScript
178+
var vm = require("vm"),
179+
sandbox;
180+
vm.runInNewContext('__result = new MetaScript(__source).transform(__scope, __basedir);', sandbox = {
181+
__source : source,
182+
__scope : scope,
183+
__basedir : basedir,
184+
MetaScript : MetaScript
185185
});
186186
return sandbox.__result;
187187
} else {
188-
return new MetaScript(source).transform(scope, basedir);
188+
return new MetaScript(source).transform(scope, basedir); // Will probably pollute the global namespace
189189
}
190190
};
191191

@@ -211,6 +211,7 @@
211211

212212
/**
213213
* Writes some contents to the document (no indentation).
214+
* @function write
214215
* @param {*} s Contents to write
215216
*/
216217
function write(s) {
@@ -219,6 +220,7 @@
219220

220221
/**
221222
* Writes some contents to the document, followed by a new line.
223+
* @function writeln
222224
* @param {*} s Contents to write
223225
*/
224226
function writeln(s) {
@@ -228,6 +230,7 @@
228230

229231
/**
230232
* Extracts the directory name from a file name.
233+
* @function dirname
231234
* @param {string} filename File name
232235
* @returns {string} Directory name, defaults to `.`
233236
*/
@@ -238,7 +241,8 @@
238241
}
239242

240243
/**
241-
* Intents a block of text.
244+
* Indents a block of text.
245+
* @function indent
242246
* @param {string} str Text to indent
243247
* @param {string|number} indent Whitespace text to use for indentation or the number of whitespaces to use
244248
* @returns {string} Indented text
@@ -259,6 +263,7 @@
259263

260264
/**
261265
* Includes another source file.
266+
* @function include
262267
* @param {string} __filename File to include
263268
* @param {boolean} __absolute Whether the path is absolute, defaults to `false` for a relative path
264269
*/
@@ -296,6 +301,7 @@
296301

297302
/**
298303
* Escaoes a string to be used inside of a single or double quote enclosed JavaScript string.
304+
* @function escapestr
299305
* @param {string} s String to escape
300306
* @returns {string} Escaped string
301307
*/
@@ -354,7 +360,7 @@
354360
if (typeof module != 'undefined' && module["exports"]) { // CommonJS
355361
module["exports"] = MetaScript;
356362
} else if (typeof define != 'undefined' && define["amd"]) { // AMD
357-
define(function() { return MetaScript; });
363+
define([], function() { return MetaScript; });
358364
} else { // Shim
359365
if (!global["dcodeIO"]) {
360366
global["dcodeIO"] = {};

‎README.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ will result in:
4848
MyLibrary.VERSION = "1.0";
4949
```
5050

51-
It's just that simple.
51+
It's just that simple and everything else is, of course, up to your imagination.
5252

5353
Advanced examples
5454
-----------------
@@ -99,7 +99,9 @@ function writeInt8(value, offset) {
9999
}
100100
```
101101

102-
More in-depth examples are [available in the wiki](https://github.com/dcodeIO/MetaScript/wiki).
102+
Some early examples are available in the [tests folder](https://github.com/dcodeIO/MetaScript/tree/master/tests). While
103+
these are JavaScript examples, MetaScript should fit nicely with any other programming language that uses `// ...` and
104+
`/* ... */` style comments.
103105

104106
API
105107
---
@@ -149,7 +151,7 @@ There are a few quite useful utility functions available to every meta program:
149151
* **dirname(filename:string)**
150152
Gets the directory name from a file name.
151153
* **include(filename:string, absolute:boolean=)**
152-
Includes another source file. `absolute` defaults to `false` (relative)
154+
Includes another source file or multiple ones when using a glob expression. `absolute` defaults to `false` (relative)
153155
* **indent(str:string, indent:string|number):string** indents a block of text using the specified indentation given
154156
either as a whitespace string or number of whitespaces to use.
155157
* **escapestr(str:string):string**
@@ -158,12 +160,10 @@ There are a few quite useful utility functions available to every meta program:
158160
Additionally, there is one internal variable named `__` (2x underscore) that remembers the current indentation level.
159161
This is used for example to indent included sources exactly like the meta block that contains the include call.
160162

161-
Examples
162-
--------
163-
Some early examples are available in the [tests folder](https://github.com/dcodeIO/MetaScript/tree/master/tests). While
164-
these are JavaScript examples, MetaScript should fit nicely with any other programming language that uses `// ...` and
165-
`/* ... */` style comments.
166-
167-
Everything else is, of course, up to your imagination.
163+
Documentation
164+
-------------
165+
* [Get additional insights from the wiki](https://github.com/dcodeIO/MetaScript/wiki)
166+
* [Tiny but fully commented source](https://github.com/dcodeIO/MetaScript/blob/master/MetaScript.js)
167+
* [View the API documentation](http://htmlpreview.github.com/?http://github.com/dcodeIO/MetaScript/master/docs/MetaScript.html)
168168

169169
**License:** Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html

0 commit comments

Comments
 (0)
X Tutup