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

Commit 937f82b

Browse files
dcodeIOdcodeIO
committed
1.0.0
1 parent 8b9d277 commit 937f82b

File tree

16 files changed

+1775
-961
lines changed

16 files changed

+1775
-961
lines changed

‎MetaScript.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
*/ //
2222
module.exports = (function() {
2323
// not strict for global var shenanigans
24-
24+
2525
/**
2626
* Current meta program version.
2727
* @type {string}

‎README.md‎

Lines changed: 29 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ lines it enables developers to transform sources in pretty much every way possib
1111
<img src="https://raw.github.com/dcodeIO/MetaScript/master/example.jpg" />
1212
</p>
1313

14+
[![Donate](https://raw.githubusercontent.com/dcodeIO/MetaScript/master/donate.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=info%40code-emitter.com&item_name=Open%20Source%3A%20MetaScript)
15+
1416
How does it work?
1517
-----------------
1618
If you already know JavaScript, adding some meta is as simple as remembering that:
@@ -32,11 +34,6 @@ Let's assume that you have a library and that you want its version number to be
3234
MyLibrary.VERSION = /*?== VERSION */;
3335
// or, alternatively, if VERSION is always string-safe:
3436
MyLibrary.VERSION = "/*?= VERSION */";
35-
// or, alternatively, if you don't mind a missing trailing semicolon:
36-
MyLibrary.VERSION = //?== VERSION
37-
// or, alternatively, if you like it procedural:
38-
MyLibrary.VERSION = /*? write(JSON.stringify(VERSION)) */;
39-
// etc.
4037
```
4138

4239
This is what the meta program, when compiled, will look like:
@@ -61,7 +58,17 @@ Advanced examples
6158
Of course it's possible to do much more with it, like declaring macros and defining an entire set of useful utility
6259
functions, just like with any sort of preprocessor:
6360

64-
#### That's a globally available utility function:
61+
#### That's a globally available utility function as a snippet:
62+
63+
```js
64+
//?...
65+
includeFile = function(file) {
66+
write(indent(require("fs").readFileSync(file)), __);
67+
}
68+
//?.
69+
```
70+
71+
or, as a block:
6572

6673
```js
6774
/*? includeFile = function(file) {
@@ -75,12 +82,12 @@ Using it:
7582
//? includeFile("some/other/file.js")
7683
```
7784

78-
#### That's a globally available macro:
85+
#### That's a globally available macro using inline blocks:
7986

8087
```js
8188
//? ASSERT_OFFSET = function(varname) {
8289
if (/*?= varname */ < 0 || /*?= varname */ > this.capacity()) {
83-
throw(new RangeError("Illegal /*?= varname */"));
90+
throw RangeError("Illegal /*?= varname */");
8491
}
8592
//? }
8693
```
@@ -99,28 +106,13 @@ Results in:
99106
```js
100107
function writeInt8(value, offset) {
101108
if (offset < 0 || offset > this.capacity()) {
102-
throw(new RangeError("Illegal offset"));
109+
throw RangeError("Illegal offset");
103110
}
104111
...
105112
}
106113
```
107114

108-
#### And that's a snippet with both the utility function and macro from above:
109-
110-
```js
111-
//?...
112-
includeFile = function(file) {
113-
write(indent(require("fs").readFileSync(file)), __);
114-
};
115-
116-
ASSERT_OFFSET = function(varname) {
117-
writeln(__+'if ('+varname+' < 0 || '+varname+' > this.capacity()) {');
118-
writeln(__+' throw(new RangeError("Illegal '+varname+'"));');
119-
};
120-
//?.
121-
```
122-
123-
Some early examples are available in the [tests folder](https://github.com/dcodeIO/MetaScript/tree/master/tests). While
115+
Some examples are available in the [tests folder](https://github.com/dcodeIO/MetaScript/tree/master/tests). While
124116
these are JavaScript examples, MetaScript should fit nicely with any other programming language that uses `// ...` and
125117
`/* ... */` style comments.
126118

@@ -166,18 +158,25 @@ There are a few quite useful utility functions available to every meta program:
166158

167159
* **write(contents:string)**
168160
Writes some raw data to the resulting document, which is equal to using `/*?= contents */`.
161+
169162
* **writeln(contents:string)**
170163
Writes some raw data, followed by a line break, to the resulting document, which is equal to using `//?= __+contents`.
164+
171165
* **dirname(filename:string)**
172166
Gets the directory name from a file name.
167+
173168
* **include(filename:string, absolute:boolean=)**
174169
Includes another source file or multiple ones when using a glob expression. `absolute` defaults to `false` (relative)
170+
175171
* **indent(str:string, indent:string|number):string** indents a block of text using the specified indentation given
176172
either as a whitespace string or number of whitespaces to use.
173+
177174
* **escapestr(str:string):string**
178175
Escapes a string to be used inside of a single or double quote enclosed JavaScript string.
176+
179177
* **snip()**
180178
Begins a snipping operation at the current offset of the output.
179+
181180
* **snap():string**
182181
Ends a snipping operation, returning the (suppressed) output between the two calls to `snip()` and `snap()`.
183182

@@ -186,10 +185,14 @@ Most notably there is the variable [__](https://github.com/dcodeIO/MetaScript/wi
186185
remembers the current indentation level. This is used for example to indent included sources exactly like the meta block
187186
that contains the include call.
188187

188+
Using utility dependencies
189+
--------------------------
190+
In case this isn't obvious: Add the dependency to your package.json and use `//? myutility = require('metascript-myutility')`.
191+
189192
Documentation
190193
-------------
191194
* [Get additional insights at the wiki](https://github.com/dcodeIO/MetaScript/wiki)
192-
* [View the API documentation](http://htmlpreview.github.com/?http://github.com/dcodeIO/MetaScript/master/docs/MetaScript.html)
195+
* [View the API documentation](http://htmlpreview.github.io/?https://raw.githubusercontent.com/dcodeIO/MetaScript/master/docs/index.html)
193196
* [View the tiny but fully commented source](https://github.com/dcodeIO/MetaScript/blob/master/MetaScript.js)
194197

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

‎bin/metac‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,13 @@ var ascli = require("ascli"),
88
MetaScript = require(path.join(__dirname, "..", "MetaScript.js")),
99
opt = app.opt;
1010

11-
if (!opt.quiet)
12-
process.stderr.write(ascli("metac".green.bold, "MetaScript compiler "+("v"+pkg.version).gray.bold)+"\n");
13-
1411
if (app.argv.length < 1) {
15-
console.log("Usage: ".white.bold+"metac".green.bold+" sourcefile [> outfile]\n");
12+
process.stderr.write(ascli("metac".green.bold, "MetaScript compiler "+("v"+pkg.version).gray.bold)+"\n");
13+
process.stderr.write(" Usage: ".white.bold+"metac".green.bold+" sourcefile [> outfile]\n\n");
1614
process.exit(1);
1715
}
1816

1917
var filename = app.argv[0];
20-
2118
try {
2219
process.stdout.write(MetaScript.compile(fs.readFileSync(filename)));
2320
if (!opt.quiet)

‎bin/metascript‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,9 @@ var ascli = require("ascli"),
88
opt = app.opt;
99

1010
var quiet = opt.quiet; delete opt.quiet;
11-
12-
if (!quiet)
13-
process.stderr.write(ascli("metascript".green.bold, ("v"+pkg.version).gray.bold));
14-
1511
if (app.argv.length < 1) {
16-
console.log("Usage: ".white.bold+"metascript".green.bold+" sourcefile -SOMEDEFINE=\"some\" -OTHERDEFINE=\"thing\" [> outfile]\n");
12+
process.stderr.write(ascli("metascript".green.bold, ("v"+pkg.version).gray.bold));
13+
process.stderr.write(" Usage: ".white.bold+"metascript".green.bold+" sourcefile -SOMEDEFINE=\"some\" -OTHERDEFINE=\"thing\" [> outfile]\n\n");
1714
process.exit(1);
1815
}
1916

@@ -22,7 +19,6 @@ var filename = app.argv[0],
2219

2320
if (!quiet)
2421
console.error(("Processing '"+filename+"' with scope:\n").white.bold+JSON.stringify(scope, null, 2).grey.bold);
25-
2622
try {
2723
process.stdout.write(MetaScript.transform(fs.readFileSync(filename), filename, scope)); // Runs in new vm context
2824
if (!quiet)

0 commit comments

Comments
 (0)