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