{"id":13659616,"url":"https://github.com/dcodeIO/MetaScript","last_synced_at":"2025-04-24T15:30:32.493Z","repository":{"id":13191905,"uuid":"15875539","full_name":"dcodeIO/MetaScript","owner":"dcodeIO","description":"Sophisticated meta programming in JavaScript, e.g. to build different versions of a library from a single source tree.","archived":true,"fork":false,"pushed_at":"2019-03-29T08:24:28.000Z","size":1309,"stargazers_count":137,"open_issues_count":6,"forks_count":13,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-09-16T02:45:10.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://dcode.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcodeIO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-13T17:19:37.000Z","updated_at":"2024-09-15T18:19:33.000Z","dependencies_parsed_at":"2022-09-13T02:53:17.182Z","dependency_job_id":null,"html_url":"https://github.com/dcodeIO/MetaScript","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcodeIO%2FMetaScript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcodeIO%2FMetaScript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcodeIO%2FMetaScript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcodeIO%2FMetaScript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcodeIO","download_url":"https://codeload.github.com/dcodeIO/MetaScript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223948553,"owners_count":17230132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T05:01:10.597Z","updated_at":"2024-11-10T13:30:44.304Z","avatar_url":"https://github.com/dcodeIO.png","language":"JavaScript","readme":"![MetaScript](https://raw.github.com/dcodeIO/MetaScript/master/MetaScript.png)\n==============================================================================\n\n**Metaprogramming** is the writing of computer programs that write or manipulate other programs (or themselves) as their\ndata, or that do part of the work at compile time that would otherwise be done at runtime.\n\n**MetaScript** is a tool for build time meta programming using JavaScript as the meta language. Written between the\nlines it enables developers to transform sources in pretty much every way possible.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.github.com/dcodeIO/MetaScript/master/example.jpg\" /\u003e\n\u003c/p\u003e\n\n[![Donate](https://raw.githubusercontent.com/dcodeIO/MetaScript/master/donate.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=info%40code-emitter.com\u0026item_name=Open%20Source%3A%20MetaScript)\n\nHow does it work?\n-----------------\nIf you already know JavaScript, adding some meta is as simple as remembering that:\n\n* `//?` begins a line of meta.\n* `/*?` begins a block of meta and `*/` ends it.\n* `//?...` begins a snippet of meta and `//?.` ends it.\n* `?=` writes the expression's raw result to the document.\n* `?==` writes the expression's typed result to the document (runs it through `JSON.stringify`).\n\nMetaScript then turns the meta inside out, making it the actual program, that outputs the contents in between.\n\nA simple example\n----------------\nLet's assume that you have a library and that you want its version number to be included as the constant\n`MyLibrary.VERSION`. With meta, this is as simple as:\n\n```js\nMyLibrary.VERSION = /*?== VERSION */;\n// or, alternatively, if VERSION is always string-safe:\nMyLibrary.VERSION = \"/*?= VERSION */\";\n```\n\nThis is what the meta program, when compiled, will look like:\n\n```js\n  write('MyLibrary.VERSION = ');\nwrite(JSON.stringify(VERSION));\n  write(';\\n');\n```\n\nAccordingly, a transformation of the source done by running that exact meta program with a scope of `{ VERSION: \"1.0\" }`\nwill result in:\n\n```js\nMyLibrary.VERSION = \"1.0\";\n```\n\nIt's just that simple and everything else is, of course, up to your imagination.\n\nAdvanced examples\n-----------------\nOf course it's possible to do much more with it, like declaring macros and defining an entire set of useful utility\nfunctions, just like with any sort of preprocessor:\n\n#### That's a globally available utility function as a snippet:\n\n```js\n//?...\nsimpleIncludeExample = function(file) {\n    write(indent(require(\"fs\").readFileSync(file).toString(\"utf8\")), __);\n}\n//?.\n```\n\nor, as a block:\n\n```js\n/*? simpleIncludeExample = function(file) {\n    write(indent(require(\"fs\").readFileSync(file).toString(\"utf8\")), __);\n} */\n```\n\nUsing it:\n\n```js\n//? simpleIncludeExample(\"some/other/file.js\")\n```\n\nThis is, of course, just an example. See [built-in utility](https://github.com/dcodeIO/MetaScript#built-in-utility) for\nwhat's actually available out of the box.\n\n#### That's a globally available macro using inline blocks:\n\n```js\n//? ASSERT_OFFSET = function(varname) {\n    if (/*?= varname */ \u003c 0 || /*?= varname */ \u003e this.capacity()) {\n        throw RangeError(\"Illegal /*?= varname */\");\n    }\n//? }\n```\n\nUsing it:\n\n```js\nfunction writeInt8(value, offset) {\n    //? ASSERT_OFFSET('offset');\n    ...\n}\n```\n\nResults in:\n\n```js\nfunction writeInt8(value, offset) {\n    if (offset \u003c 0 || offset \u003e this.capacity()) {\n        throw RangeError(\"Illegal offset\");\n    }\n    ...\n}\n```\n\nSome examples are available in the [tests folder](https://github.com/dcodeIO/MetaScript/tree/master/tests). While\nthese are JavaScript examples, MetaScript should fit nicely with any other programming language that uses `// ...` and\n`/* ... */` style comments.\n\nAPI\n---\nThe API is pretty much straight forward:\n\n* **new MetaScript(source:string, filename:string)**  \n  Creates a new instance with `source`, located at `filename`, compiled to a meta program.\n* **MetaScript#program**  \n  Contains the meta program's source.\n* **MetaScript#transform(scope:Object):string**  \n  Runs the meta program in the current context, transforming the source depending on what's defined in `scope` and\n  returns the final source.\n  \nOne step compilation / transformation:\n\n* **MetaScript.compile(source:string):string**  \n  Compiles the specified source to a meta program and returns its source.\n* **MetaScript.transform(source:string, filename:string, scope:Object):string**  \n  Compiles `source`, located at `filename`, to a meta program and transforms it using the specified scope in a new VM\n  context.\n\nCommand line\n------------\nTransforming sources on the fly is simple with node:\n\n`npm install -g metascript`\n\n```\n Usage: metascript sourcefile -SOMEDEFINE=\"some\" -OTHERDEFINE=\"thing\" [\u003e outfile]\n```\n\nAnd in the case that you have to craft your own runtime, the raw compiler is also available as `metac`:\n\n```\n Usage: metac sourcefile [\u003e outfile]\n```\n\nBuilt-in utility\n----------------\nThere are a few quite useful utility functions available to every meta program:\n\n* **write(contents:string)**  \n  Writes some raw data to the resulting document, which is equal to using `/*?= contents */`.\n  \n* **writeln(contents:string)**  \n  Writes some raw data, followed by a line break, to the resulting document, which is equal to using `//?= __+contents`.\n  \n* **dirname(filename:string)**  \n  Gets the directory name from a file name.\n  \n* **include(filename:string, absolute:boolean=)**  \n  Includes another source file or multiple ones when using a glob expression. `absolute` defaults to `false` (relative)\n  \n* **indent(str:string, indent:string|number):string** indents a block of text using the specified indentation given\n  either as a whitespace string or number of whitespaces to use.\n  \n* **escapestr(str:string):string**  \n  Escapes a string to be used inside of a single or double quote enclosed JavaScript string.\n  \n* **snip()**  \n  Begins a snipping operation at the current offset of the output.\n  \n* **snap():string**  \n  Ends a snipping operation, returning the (suppressed) output between the two calls to `snip()` and `snap()`.\n  \nAdditionally, there are [a few internal variables](https://github.com/dcodeIO/MetaScript/wiki#other-__-prefixed-variables).\nMost notably there is the variable [__](https://github.com/dcodeIO/MetaScript/wiki#the-__-variable) (2x underscore) that\nremembers the current indentation level. This is used for example to indent included sources exactly like the meta block\nthat contains the include call.\n\nUsing utility dependencies\n--------------------------\nIn case this isn't obvious: Add the dependency to your package.json and, in MetaScript, use:\n```js\n//? myutility = require('metascript-myutility')\n```\n\nUsage as a task\n---------------\n* [Meinaart van Straalen](https://github.com/meinaart) created a Grunt task:\n  [grunt-metascript](https://github.com/meinaart/grunt-metascript) ([npm](https://www.npmjs.org/package/grunt-metascript))\n* [Wutian](https://github.com/Naituw) created a Broccoli task:\n  [broccoli-metascript](https://github.com/Naituw/broccoli-metascript)\n* [Jose Pereira](https://github.com/oNaiPs) created a Gulp task:\n  [gulp-metascript](https://github.com/oNaiPs/gulp-metascript) ([npm](https://www.npmjs.com/package/gulp-metascript))\n\nDocumentation\n-------------\n* [Get additional insights at the wiki](https://github.com/dcodeIO/MetaScript/wiki)\n* [View the API documentation](http://htmlpreview.github.io/?https://raw.githubusercontent.com/dcodeIO/MetaScript/master/docs/index.html)\n* [View the tiny but fully commented source](https://github.com/dcodeIO/MetaScript/blob/master/MetaScript.js)\n\n**License:** Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html\n","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=info%40code-emitter.com\u0026item_name=Open%20Source%3A%20MetaScript"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdcodeIO%2FMetaScript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FdcodeIO%2FMetaScript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdcodeIO%2FMetaScript/lists"}