redeyed

What is redeyed?

The redeyed npm package provides functionality for syntax highlighting and code transformation by allowing modifications to JavaScript code through configuration of hooks for tokens and types. It enables parsing JavaScript code, identifying tokens and their types, and then applying transformations or highlighting based on the configuration provided.

What are redeyed's main functionalities?

Syntax Highlighting

This feature allows for syntax highlighting of JavaScript code. By configuring the `String` token, all string literals in the code can be highlighted. The example demonstrates how to highlight string literals in green using ANSI escape codes.

const redeyed = require('redeyed');
const config = {
  String: {
    _default: { open: '\x1b[32m', close: '\x1b[39m', _default: true }
  }
};
const code = '"Hello, world!"';
const highlighted = redeyed(code, config).code;
console.log(highlighted);

Code Transformation

This feature enables code transformation by applying custom transformations to specific JavaScript tokens. In the example, all instances of the `function` keyword are prefixed with `_function_`, demonstrating a simple transformation.

const redeyed = require('redeyed');
const config = {
  Keyword: {
    'function': { open: '_function_', close: '' }
  }
};
const code = 'function example() {}';
const transformed = redeyed(code, config).code;
console.log(transformed);

Other packages similar to redeyed

esprima

Esprima is a popular JavaScript parser that provides a detailed syntax tree of JavaScript code. While it doesn't directly offer syntax highlighting or transformation, it serves as a foundation for building such tools. Compared to redeyed, Esprima offers more in-depth analysis but requires more setup for syntax highlighting or code transformation.

jscodeshift

jscodeshift is a toolkit for running codemods over multiple JavaScript or TypeScript files. It uses a different approach than redeyed by focusing on code transformations rather than syntax highlighting. jscodeshift offers a more comprehensive API for complex code modifications, making it more suitable for large-scale refactoring.

highlight.js

highlight.js is a syntax highlighter written in JavaScript. It supports a wide range of programming languages, including JavaScript. Unlike redeyed, which allows for dynamic modification of code through configuration, highlight.js focuses solely on syntax highlighting without the ability to transform code.

README

redeyed

Add color to your JavaScript!

Red Eyed Tree Frog (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

What for?

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

How?

• copy the 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

{
    // {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

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:

{
    // {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 configuration, a code snippet and maybe opts as in the below example:

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:

{ // {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:

{   ast      
  , tokens   
  , comments 
  , splits   
  , code     
}

• ast {Array}: abstract syntax tree as returned by esprima parse
• tokens {Array}: tokens 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 as one of your dependencies

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

Attached to global window object

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

<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: Syntax highlights JavaScript code with ANSI colors to be printed to the terminal
• 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
• npm explore redeyed; npm demo-log will let you try the replace log example