1 | # cardinal [![Build Status](https://secure.travis-ci.org/thlorenz/cardinal.svg)](http://travis-ci.org/thlorenz/cardinal)
|
2 |
|
3 | <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>
|
4 |
|
5 | [![NPM](https://nodei.co/npm/cardinal.png?downloads=true&stars=true)](https://nodei.co/npm/cardinal/)
|
6 |
|
7 | **car·di·nal** *(kärdn-l, kärdnl)* - crested thick-billed North American finch having bright red plumage in the male.
|
8 |
|
9 | ![screenshot](https://github.com/thlorenz/cardinal/raw/master/assets/screen-shot.png)
|
10 |
|
11 | ## Features
|
12 |
|
13 | - highlights JavaScript code with ANSI colors to improve terminal output
|
14 | - theming support, see [custom color themes](https://github.com/thlorenz/cardinal/tree/master/themes)
|
15 | - optionally print line numbers
|
16 | - API and command line interface (`cdl`)
|
17 | - `.cardinalrc` config to customize settings
|
18 | - supports UNIX pipes
|
19 |
|
20 | ***
|
21 |
|
22 | **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
|
23 |
|
24 | - [Installation](#installation)
|
25 | - [As library](#as-library)
|
26 | - [As Commandline Tool](#as-commandline-tool)
|
27 | - [Commandline](#commandline)
|
28 | - [Highlight a file](#highlight-a-file)
|
29 | - [As part of a UNIX pipe](#as-part-of-a-unix-pipe)
|
30 | - [Theme](#theme)
|
31 | - [API](#api)
|
32 | - [*highlight(code[, opts])*](#highlightcode-opts)
|
33 | - [*highlightFileSync(fullPath[, opts])*](#highlightfilesyncfullpath-opts)
|
34 | - [*highlightFile(fullPath[, opts], callback)*](#highlightfilefullpath-opts-callback)
|
35 | - [opts](#opts)
|
36 | - [Examples ([*browse*](https://github.com/thlorenz/cardinal/tree/master/examples))](#examples-[browse]https://githubcom/thlorenz/cardinal/tree/master/examples)
|
37 |
|
38 |
|
39 | ## Installation
|
40 |
|
41 | ### As library
|
42 |
|
43 | npm install cardinal
|
44 |
|
45 | ### As Commandline Tool
|
46 |
|
47 | [sudo] npm install -g cardinal
|
48 |
|
49 | **Note:**
|
50 |
|
51 | When installed globally, cardinal exposes itself as the `cdl` command.
|
52 |
|
53 | ## Commandline
|
54 |
|
55 | ### Highlight a file
|
56 |
|
57 | cdl <file.js> [options]
|
58 |
|
59 | **options**:
|
60 | - `--nonum`: turns off line number printing (relevant if it is turned on inside `~/.cardinalrc`
|
61 |
|
62 | ### As part of a UNIX pipe
|
63 |
|
64 | cat file.js | grep console | cdl
|
65 |
|
66 | **Note:**
|
67 |
|
68 | Not all code lines may be parsable JavaScript. In these cases the line is printed to the terminal without
|
69 | highlighting it.
|
70 |
|
71 | ### Theme
|
72 |
|
73 | The default theme will be used for highlighting.
|
74 |
|
75 | To use a different theme, include a `.cardinalrc` file in your `HOME` directory.
|
76 |
|
77 | This is a JSON file of the following form:
|
78 |
|
79 | ```json
|
80 | {
|
81 | "theme": "hide-semicolons",
|
82 | "linenos": true|false
|
83 | }
|
84 | ```
|
85 |
|
86 | - `theme` can be the name of any of the [built-in themes](https://github.com/thlorenz/cardinal/tree/master/themes) or the
|
87 | full path to a custom theme anywhere on your computer.
|
88 | - linenos toggles line number printing
|
89 |
|
90 | ## API
|
91 |
|
92 | ### *highlight(code[, opts])*
|
93 |
|
94 | - returns the highlighted version of the passed code ({String}) or throws an error if it was not able to parse it
|
95 | - opts (see below)
|
96 |
|
97 | ### *highlightFileSync(fullPath[, opts])*
|
98 |
|
99 | - returns the highlighted version of the file whose fullPath ({String}) was passed or throws an error if it was not able
|
100 | to parse it
|
101 | - opts (see below)
|
102 |
|
103 | ### *highlightFile(fullPath[, opts], callback)*
|
104 |
|
105 | - calls back with the highlighted version of the file whose fullPath ({String}) was passed or with an error if it was not able
|
106 | to parse it
|
107 | - opts (see below)
|
108 | - `callback` ({Function}) has the following signature: `function (err, highlighted) { .. }`
|
109 |
|
110 | ### opts
|
111 |
|
112 | opts is an {Object} with the following properties:
|
113 |
|
114 | - `theme` {Object} is used to optionally override the theme used to highlight
|
115 | - `linenos` {Boolean} if `true` line numbers are included in the highlighted code
|
116 | - `firstline` {Integer} sets line number of the first line when line numbers are printed
|
117 | - `jsx` {Boolean} if `true` _JSX_ syntax is supported, otherwise cardinal will raise an error
|
118 | when encountering _JSX_ (default: `false`)
|
119 |
|
120 | **Note** The `json` option is obsoleted and not necessary anymore as cardinal properly understands both JSON and JavaScript.
|
121 |
|
122 | ## Examples ([*browse*](https://github.com/thlorenz/cardinal/tree/master/examples))
|
123 |
|
124 | - [sample .cardinalrc](https://github.com/thlorenz/cardinal/blob/master/examples/.cardinalrc)
|
125 | - [highlighting a code snippet](https://github.com/thlorenz/cardinal/blob/master/examples/highlight-string.js) via
|
126 | ***highlight()***
|
127 | - [file that highlights itself](https://github.com/thlorenz/cardinal/blob/master/examples/highlight-self.js) via
|
128 | ***highlightFile()*** including line numbers
|
129 | - [file that highlights itself hiding all
|
130 | semicolons](https://github.com/thlorenz/cardinal/blob/master/examples/highlight-self-hide-semicolons.js) via
|
131 | ***highlightFileSync()***
|