diff --git a/README.md b/README.md index d0fd6ad..1a0fe13 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,19 @@ # Starlight -A Lua to ECMAScript 6 transpiler. +A Lua to ECMAScript 6 translator. +http://starlight.paulcuth.me.uk [![Circle CI](https://img.shields.io/circleci/project/paulcuth/starlight/master.svg?label=master)](https://circleci.com/gh/paulcuth/starlight/tree/master) [![Circle CI](https://img.shields.io/circleci/project/paulcuth/starlight/dev.svg?label=dev)](https://circleci.com/gh/paulcuth/starlight/tree/dev) ![Tagged version number](https://img.shields.io/github/tag/paulcuth/starlight.svg?color=brightgreen) +## Using Starlight -## Getting started +For usage and examples please visit the Starlight documentation: +http://starlight.paulcuth.me.uk/docs + + + +## Building Starlight Checkout the repo and install dependencies: ``` git clone git@github.com:paulcuth/starlight.git @@ -14,88 +21,22 @@ cd starlight npm install ``` -### Parse and run Lua in the browser -#### Build the lib -To use Starlight to parse Lua script tags in the brower, build the browser-lib: +#### Build the browser-lib +To use Starlight to parse Lua script tags in the browser, build the browser-lib: ``` grunt browser-lib ``` This will create `dist/bowser-lib/starlight.js` along with example usage in the same folder. -#### Basic use -If your target browsers don't support ES6 natively, you'll need to include Babel parser along with the Starlight browser-lib: -```html - - -``` - -Notice the `data-run-script-tags` attribute on the Starlight ` -``` -#### Interacting with the DOM -The JavaScript `window` object is available with the same name, but be aware `window` ~= `_G`. You need to access all DOM properties through the `window` table, for example: -```lua - -``` -If you really want to access the properties of `window` in the global namespace, you can call `window.extract()`. -```lua - -``` - -Make sure you always use the colon syntax to call methods on the DOM, as in the examples above. - - -### Translate Lua files to ES6 in your Grunt build +### Build the Grunt plugin [![NPM version number](https://img.shields.io/npm/v/grunt-starlight.svg?label=grunt-starlight)](https://www.npmjs.com/package/grunt-starlight) -To use Starlight to translate Lua to ES6 as part of your build pipeline, first install the plugin: -``` -npm install grunt-starlight +To use Starlight to translate Lua to ES6 as part of the build pipeline, build the Grunt plugin: ``` - -Then, in your `Gruntfile`: -``` -grunt.initConfig({ - starlight: { - 'hello-world': { - src: 'src/lua/hello-world.lua', - dest: 'dist/js/hello-world.lua.js', - } - } -}); -``` - -You can also build many Lua files into a single JavaScript file, like the following example for building Starlight's own tests. Remember to set which file will execute first using `options.main`. -``` -grunt.initConfig({ - starlight: { - test: { - src: 'test/lua/**/*.lua', - dest: 'dist/test/test.lua.js', - options: { - main: 'test-runner.lua', - basePath: 'test/lua' - } - } - } -}); +grunt grunt-plugin ``` +This will create the plugin in the `dist/build-tools/grunt-starlight` directory and also copy it to the project's `node_modules` directory. ## Get involved @@ -103,30 +44,8 @@ grunt.initConfig({ Please feel free to ask anything about the project on the [Gitter channel](https://gitter.im/paulcuth/starlight). Any pull requests for bugfixes, feature suggestions, etc. are gratefully appreciated. -If you're working on the Grunt plugin, you'll need to build that using: -``` -grunt grunt-plugin -``` - Any work on the parser or the runtime will require a default build. Note that for this to run, you'll need to have the Grunt plugin installed using `grunt grunt-plugin`. ``` grunt ``` - - - -## Roadmap -The next features to add: - -- [ ] Performance tests -- [ ] Add plug-ins architecture - - Coroutines (as generators are not a 1:1 map) -- [ ] Customisation of environment and plugins at build-time - - Selectively add standard libs. -- [ ] Implement missing standard lib functions - - string.format() - - string.dump() - - load() - - loadfile() - diff --git a/package.json b/package.json index 16f904f..be7fea8 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "starlight", "description": "A Lua -> ES6 transpiler", - "version": "0.1.7", + "version": "0.1.8", "author": { "name": "Paul Cuthbertson" }, diff --git a/src/build-tools/grunt/README.md b/src/build-tools/grunt/README.md index a40a392..1217eb1 100644 --- a/src/build-tools/grunt/README.md +++ b/src/build-tools/grunt/README.md @@ -1,6 +1,6 @@ # grunt-starlight - -> A Lua -> ES6 transpiler +A Lua to ES6 translator +http://starlight.paulcuth.me.uk ## Getting Started This plugin requires Grunt `~0.4.5` @@ -19,71 +19,6 @@ grunt.loadNpmTasks('grunt-starlight'); ## The "starlight" task -### Overview -In your project's Gruntfile, add a section named `starlight` to the data object passed into `grunt.initConfig()`. - -```js -grunt.initConfig({ - starlight: { - options: { - // Task-specific options go here. - }, - your_target: { - // Target-specific file lists and/or options go here. - }, - }, -}); -``` - -### Options - -#### options.separator -Type: `String` -Default value: `', '` - -A string value that is used to do something with whatever. - -#### options.punctuation -Type: `String` -Default value: `'.'` - -A string value that is used to do something else with whatever else. - -### Usage Examples - -#### Default Options -In this example, the default options are used to do something with whatever. So if the `testing` file has the content `Testing` and the `123` file had the content `1 2 3`, the generated result would be `Testing, 1 2 3.` - -```js -grunt.initConfig({ - starlight: { - options: {}, - files: { - 'dest/default_options': ['src/testing', 'src/123'], - }, - }, -}); -``` - -#### Custom Options -In this example, custom options are used to do something else with whatever else. So if the `testing` file has the content `Testing` and the `123` file had the content `1 2 3`, the generated result in this case would be `Testing: 1 2 3 !!!` - -```js -grunt.initConfig({ - starlight: { - options: { - separator: ': ', - punctuation: ' !!!', - }, - files: { - 'dest/default_options': ['src/testing', 'src/123'], - }, - }, -}); -``` - -## Contributing -In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/). +For details on how to configure the Starlight task, including working examples, please visit the Starlight docs: +http://starlight.paulcuth.me.uk/docs/using-starlight-with-grunt -## Release History -_(Nothing yet)_