# redeyed [![build status](https://secure.travis-ci.org/thlorenz/redeyed.svg?branch=master)](http://travis-ci.org/thlorenz/redeyed)

<a href="https://www.patreon.com/bePatron?u=8663953"><img alt="become a patron" src="https://c5.patreon.com/external/logo/become_a_patron_button.png" height="35px"></a>

*Add color to your JavaScript!*

![frog](http://allaboutfrogs.org/gallery/photos/redeyes/red1.gif)

[Red Eyed Tree Frog](http://allaboutfrogs.org/info/species/redeye.html) *(Agalychnis callidryas)*

## What?

Takes JavaScript code, along with a config and returns the original code with tokens wrapped and/or replaced as configured.

## Where?

- server side using nodejs
- in the [browser](#browser-support)

## What for?

One usecase is adding metadata to your code that can then be used to apply syntax highlighting.

## How?

- copy the [config.js](https://github.com/thlorenz/redeyed/blob/master/config.js) and edit it in order to specify how
  certain tokens are to be surrounded/replaced
- replace the `undefined` of each token you want to configure with one of the following

### {String} config

`'before:after'`

wraps the token inside before/after 

### {Object} config

`{ _before: 'before', _after: 'after' }`

wraps token inside before/after

#### Missing before and after resolution for {String} and {Object} config

For the `{String}` and `{Object}` configurations, 'before' or 'after' may be omitted:

- `{String}`: 
  - `'before:'` (omitting 'after')
  - `':after'` (omitting 'before')
- `{Object}`: 
  - `{ _before: 'before' }` (omitting '_after')
  - `{ _after: 'after' }` (omitting '_before')

In these cases the missing half is resolved as follows:

- from the `parent._default` (i.e., `Keyword._default`) if found
- otherwise from the `config._default` if found
- otherwise `''` (empty string)

### {Function} config

`function (tokenString, info) { return {String}|{Object}; }`

#### Inputs

- tokenString: the content of the token that is currently being processed
- info: an object with the following structure

```js
{
    // {Int}
    // the index of the token being processed inside tokens
    tokenIndex

    // {Array}
    // all tokens that are being processed including comments 
    // (i.e. the result of merging esprima tokens and comments)
  , tokens  

    // {Object} 
    // the abstract syntax tree of the parsed code
  , ast  

    // {String}
    // the code that was parsed (same string as the one passed to redeyed(code ..)
  , code
}
```

In most cases the `tokenString` is all you need. The extra info object is passed in case you need to gather more
information about the `token`'s surroundings in order to decide how to transform it. 
See: [replace-log-example](https://github.com/thlorenz/redeyed/blob/master/examples/replace-log.js)

#### Output

You can return a {String} or an {Object} from a {Function} config.

- when returning a {String}, the token value will be replaced with it
- when returning an {Object}, it should be of the following form:

```js
{
    // {String}
    // the string that should be substituted for the value of the current and all skipped tokens
    replacement

    // {Object} (Token)
    // the token after which processing should continue
    // all tokens in between the current one and this one inclusive will be ignored
  , skipPastToken
}
```

### Transforming JavaScript code

***redeyed(code, config[, opts])***

Invoke redeyed with your **config**uration, a **code** snippet and maybe **opts** as in the below example:

```javascript
var redeyed = require('redeyed')
  , config = require('./path/to/config')
  , code = 'var a = 3;'
  , result;

// redeyed will throw an error (caused by the esprima parser) if the code has invalid javascript
try {
  result = redeyed(code, config);
  console.log(result.code);
} catch(err) {
  console.error(err);
}
```

***opts***:
```js
{ // {Boolean}
  // if true `result.ast` property contains the abstract syntax tree of the code
  // if false (default) `result.ast` is not assigned and therefore `undefined`
  buildAst: true|false
  // {Boolean}
  // if `true`, jsx syntax is supported, default `false`
  // due to how esprima works, the AST is built when this option is `true`, even if
  // `buildAST` is `false`
, jsx: true|false
  // {Boolean}
  // if true `result.code` is not assigned and therefore `undefined`
  // if false (default) `result.code` property contains the result of `split.join`
  nojoin: true|false
  // {Object}
  // overrides default parser `esprima-fb` and needs to be compatible with it
  parser: require('esprima') 
}
```

***return value***:

```js
{   ast      
  , tokens   
  , comments 
  , splits   
  , code     
}
```

- ast `{Array}`: [abstract syntax tree](http://en.wikipedia.org/wiki/Abstract_syntax_tree) as returned by [esprima
  parse](http://en.wikipedia.org/wiki/Abstract_syntax_tree)
- tokens `{Array}`: [tokens](http://en.wikipedia.org/wiki/Token_(parser)) provided by esprima (excluding
  comments)
- comments `{Array}`: block and line comments as provided by esprima
- splits `{Array}`: code pieces split up, some of which where transformed as configured
- code `{String}`: transformed code, same as `splits.join('')` unless this step has been skipped (see opts)

## Browser Support

### AMD

Ensure to include [esprima](https://github.com/ariya/esprima) as one of your dependencies

```js
define(['redeyed'], function (redeyed) {
 [ .. ]
});
```

### Attached to global window object

The `redeyed {Function}` will be exposed globally as `window.redeyed` - big surprise!

```html
<script type="text/javascript" src="https://unpkg.com/esprima"></script>
<script type="text/javascript" src="https://unpkg.com/redeyed"></script>
```

## redeyed in the wild

- [cardinal](https://github.com/thlorenz/cardinal): Syntax highlights JavaScript code with ANSI colors to be printed to
  the terminal
- [peacock](http://thlorenz.github.com/peacock/): JavaScript syntax highlighter that generates html that is compatible
  with pygments styles.

## Examples

- `npm explore redeyed; npm demo` will let you try the [browser example](https://github.com/thlorenz/redeyed/tree/master/examples/browser)
- `npm explore redeyed; npm demo-log` will let you try the [replace log example](https://github.com/thlorenz/redeyed/blob/master/examples/replace-log.js)