Skip to content

Commit

Permalink
Updates READMEs to reflect new website.
Browse files Browse the repository at this point in the history
  • Loading branch information
Paul Cuthbertson committed Mar 28, 2016
1 parent efcef59 commit 32566b9
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 166 deletions.
111 changes: 15 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,132 +1,51 @@
# 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 [email protected]:paulcuth/starlight.git
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
<script src="//cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.34/browser.min.js"></script>
<script src="./starlight.js" data-run-script-tags></script>
```

Notice the `data-run-script-tags` attribute on the Starlight `<script>` tag? That tells the browser-lib to find, parse and execute any other `<script>` tags with `type="application/x-lua"`.

So then just include your Lua in the page, like so:
```js
<script type="application/x-lua">
print 'Hello Web'
</script>
```
#### 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
<script type="application/x-lua">
window:alert 'hello'
window.document:createElement 'div'
window.navigator.geolocation:getCurrentPosition(successCallback, failCallback)
</script>
```

If you really want to access the properties of `window` in the global namespace, you can call `window.extract()`.
```lua
<script type="application/x-lua">
window.extract()

alert 'hello'
document:createElement 'div'
navigator.geolocation:getCurrentPosition(successCallback, failCallback)
</script>
```

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
[![Join the chat at https://gitter.im/paulcuth/starlight](https://img.shields.io/badge/gitter-join%20chat-green.svg)](https://gitter.im/paulcuth/starlight)

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()

2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "starlight",
"description": "A Lua -> ES6 transpiler",
"version": "0.1.7",
"version": "0.1.8",
"author": {
"name": "Paul Cuthbertson"
},
Expand Down
73 changes: 4 additions & 69 deletions src/build-tools/grunt/README.md
View file
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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)_

0 comments on commit 32566b9

Please sign in to comment.