Skip to content
This repository was archived by the owner on Feb 12, 2022. It is now read-only.

Commit bff3b1c

Browse files
jgnewmanjgnewman
committed
initial commit
1 parent a7284db commit bff3b1c

File tree

13 files changed

+4522
-1
lines changed

13 files changed

+4522
-1
lines changed

‎.babelrc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"presets": ["es2015"]
3+
}

‎README.md

Lines changed: 148 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,149 @@
11
# custom-syntax-highlighter
2-
Define your own syntax for highlighting code blocks
2+
3+
### Define your own syntax for highlighting code blocks.
4+
5+
So you don't like other syntax highlighters on the market, eh?
6+
7+
Too bloated?
8+
9+
Too complicated?
10+
11+
Buggy?
12+
13+
Doesn't support your language?
14+
15+
Meet **custom-syntax-highlighter** – the tiny, unassuming library that will finally give you exactly what you need: control.
16+
17+
## How it works:
18+
19+
Sorry to have to tell you this, but if you're going to parse your own syntax, you're going to need a basic understanding of regular expressions. If you don't have that, you're gonna hate this. If you do, it'll be cake.
20+
21+
So the first thing you do is install it:
22+
23+
```bash
24+
$ yarn add custom-syntax-highlighter
25+
26+
# or...
27+
28+
$ npm install custom-syntax-highlighter
29+
```
30+
31+
Then you need to import it:
32+
33+
```javascript
34+
import highlight from 'custom-syntax-highlighter';
35+
```
36+
37+
Then you can go to town.
38+
39+
The idea is that you will define a collection of patterns to match against. Each one is associated with a class name. Custom-syntax-highlighter will loop over your code blocks and wrap the matches it finds with spans that have the class name. This way, you are free to control what gets wrapped and how it gets styled.
40+
41+
So let's say you had the following code:
42+
43+
```html
44+
<pre>
45+
<code>
46+
callFunction('with string')
47+
</code>
48+
</pre>
49+
```
50+
51+
You might attack it with something like this:
52+
53+
```javascript
54+
highlight({
55+
patterns: {
56+
'string' : /^(\'[^\'\n]*\')/,
57+
'fn-call' : [/^([A-z_]+)\(/, '', '(']
58+
}
59+
})
60+
```
61+
62+
Which would create this:
63+
64+
```html
65+
<pre>
66+
<code>
67+
<span class="fn-call">callFunction</span>(<span class="string">'with string'</span>)
68+
</code>
69+
</pre>
70+
```
71+
72+
Allowing you to then style it as you like:
73+
74+
```css
75+
.fn-call { color: blue }
76+
.string { color: green }
77+
```
78+
79+
### Why did that work?
80+
81+
The `highlight` function takes a configuration object with many options, the most important of which is the "patterns" option. This should take the form of an object (or function, but we'll get to that) where each key is a class name and each value is, in its most basic form, a regular expression that matches the class name.
82+
83+
Custom-syntax-highlighter works by testing each pattern against a string. If it doesn't find a match, it cuts the first character off the string and tries again. When it finds a match, it cuts off the whole match, wraps it in a span, and then continues until the string is completely used up. As such, **ALL OF YOUR PATTERNS SHOULD BEGIN WITH THE "^" CHARACTER TO INDICATE THAT ONLY THE BEGINNING OF THE STRING SHOULD BE TESTED**.
84+
85+
If you don't follow this rule, the processing will be far less efficient and you will get unexpected results.
86+
87+
You'll notice that each pattern in our example contains a capture group. This is how the system knows which piece of the matched pattern to actually wrap. Because sometimes you need to detect other characters that aren't part of the captured match, you can provide a 3-item array instead of a plain regular expression (as we did in the "fn-call" example). Item 0 is the regular expression, item 1 is a prefix to place before the wrapped match, and item 2 is a suffix to place after it, as needed.
88+
89+
And that's how you do it.
90+
91+
## More Options
92+
93+
#### `linenums: Boolean`
94+
95+
Defaults to false. If true, you'll get nice line numbers prefixed to each line.
96+
97+
#### `selector: String`
98+
99+
Defaults to `"pre code"`. It determines how the code blocks that should be processed can be identified.
100+
101+
#### `preProcess: Function`
102+
103+
Takes the incoming string of code after some whitespace cleaning has been done to it. It allows you to mess with the string a little bit if you need to before the system processes it. You should return a string of code for the system to process.
104+
105+
#### `postProcess: Function`
106+
107+
Takes the string of code after it has been processed and had spans inserted. This allows you to do any last minute tweaks before it gets rendered back into the DOM. For example, you could do something like...
108+
109+
```javascript
110+
highlight({
111+
112+
patterns: myPatterns,
113+
114+
postProcess: string => {
115+
return string.replace(/,/g, '<span class="comma">,</span>')
116+
}
117+
118+
})
119+
```
120+
121+
#### Using a function for the `patterns` options
122+
123+
If you use a function for the "patterns" options, that function will be called once for each identified block and should return either nothing if you don't want to process it, or an object of patterns with which to do the processing. For example:
124+
125+
```javascript
126+
highlight({
127+
128+
patterns: block => {
129+
130+
if (/javascript/.test(block.className)) {
131+
return javaScriptPatterns;
132+
133+
} else if (/html/.test(block.className)) {
134+
return htmlPatterns;
135+
136+
}
137+
// Otherwise, return nothing.
138+
}
139+
140+
})
141+
```
142+
143+
---
144+
145+
And now you're ready to build your own highlighter! Remember, if it doesn't work, it's probably your own fault.
146+
147+
Just kidding.
148+
149+
But seriously though... regex.

‎bin/index.js

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
'use strict';
2+
3+
/**
4+
* Recursively parses a string of text in a way that loosely mimicks a Jison parser.
5+
* It looks at the beginning of the string, and attempts to find a match. If there
6+
* is no match, it collects a raw character and recurses. If it finds a match, it
7+
* collects the match, wraps it in a span with a class name, and recurses. It
8+
* goes until the whole string has been collected.
9+
*
10+
* @param {Object} patterns The patterns to parse against
11+
* @param {String} incoming The original text, being shortened as we recurse.
12+
* @param {String} output The new text with spans.
13+
*
14+
* @return {String} The output.
15+
*/
16+
function parse(patterns, incoming, output) {
17+
18+
/*
19+
* These variables will be used to help us figure out how to
20+
* wrap text when we find a match.
21+
*/
22+
var match = null;
23+
var matchType = null;
24+
var matchPrefix = null;
25+
var matchSuffix = null;
26+
output = output || '';
27+
28+
/*
29+
* Return the output when the incoming string has nothing left in it.
30+
*/
31+
if (!incoming.length) return output || '';
32+
33+
/*
34+
* Check each pattern against the string. If we find a match, assign it to the
35+
* match variable.
36+
*/
37+
Object.keys(patterns).some(function (key) {
38+
var isRegex = patterns[key] instanceof RegExp;
39+
var pattern = isRegex ? patterns[key] : patterns[key][0];
40+
var prefix = isRegex ? null : patterns[key][1] || null;
41+
var suffix = isRegex ? null : patterns[key][2] || null;
42+
43+
match = incoming.match(pattern);
44+
matchType = match ? key : null;
45+
matchPrefix = prefix;
46+
matchSuffix = suffix;
47+
return !!match;
48+
});
49+
50+
/*
51+
* If there was no match, collect one character and recurse.
52+
*/
53+
if (!match) {
54+
return parse(patterns, incoming.slice(1), output + incoming[0]);
55+
56+
/*
57+
* If there was a match, wrap it in a span. If we have a prefix and/or
58+
* suffix, drop those in too.
59+
*/
60+
} else {
61+
var replacement = '<span class="' + matchType + '">' + match[1] + '</span>';
62+
if (matchPrefix) replacement = matchPrefix + replacement;
63+
if (matchSuffix) replacement = replacement + matchSuffix;
64+
65+
/*
66+
* Collect the match and recurse
67+
*/
68+
return parse(patterns, incoming.slice(match[0].length), output + replacement);
69+
}
70+
}
71+
72+
/**
73+
* Custom-syntax-highlighter is nice and knows that you like to indent code
74+
* when you're writing. It doesn't expect you to dedent your `pre` and `code`
75+
* tags all the way to the left just so it won't appear weirdly indented in the
76+
* output.
77+
*
78+
* This function does some convenient whitespace parsing to help with things like that.
79+
*
80+
* @param {String} text The original, unparsed text.
81+
*
82+
* @return {String} The cleaned up text.
83+
*/
84+
function clean(text) {
85+
86+
/*
87+
* Cut out useless new line lines at the front and back.
88+
* Check to see if there's some indentation and return if not.
89+
*/
90+
var trimmed = text.replace(/^\n+|\n+\s+$/g, '');
91+
var spaceToCut = trimmed.match(/^\s+/);
92+
if (!spaceToCut) return trimmed;
93+
94+
/*
95+
* Split the block into an array of lines. For each one, remove the
96+
* matched indentation from the front.
97+
*/
98+
var textArray = trimmed.split('\n');
99+
var dedented = textArray.map(function (string, index) {
100+
return !string || /^\s+$/.test(string) ? string : string.replace(spaceToCut[0], '');
101+
}).join('\n');
102+
103+
/*
104+
* Spit out the dedented text.
105+
*/
106+
return '\n' + dedented;
107+
}
108+
109+
/**
110+
* Highlights code blocks in a way you specify.
111+
*
112+
* @param {Object} config Allows the following keys:
113+
* patterns: {...} (The regex patterns used to parse)
114+
* linenums: true (Turns on line numbers)
115+
* selector: 'pre' (Defaults to 'pre code')
116+
* preProcess: fn (Allows you to eff with the string after parsing)
117+
* postProcess: fn (Allows you to eff with the string after parsing)
118+
*
119+
* @return {undefined}
120+
*/
121+
function highlight(config) {
122+
var selector = config.selector || 'pre code';
123+
var postProcess = config.postProcess || function (str) {
124+
return str;
125+
};
126+
var preProcess = config.preProcess || function (str) {
127+
return str;
128+
};
129+
130+
/*
131+
* Find all `pre code` blocks and loop over them. For each block...
132+
*/
133+
Array.prototype.slice.call(document.querySelectorAll(selector)).forEach(function (block) {
134+
var patterns = (typeof config.patterns === 'function' ? config.patterns(block) : config.patterns) || {};
135+
136+
/*
137+
* Get the inner text, clean the text, then parse the text with the patterns.
138+
*/
139+
var innerText = block.innerText;
140+
var cleanText = clean(innerText);
141+
var parsed = postProcess(parse(patterns, preProcess(cleanText)));
142+
143+
/*
144+
* If the user wants line numbers, split the parsed text on new lines
145+
* and loop over each line.
146+
*/
147+
if (config.linenums) {
148+
parsed = parsed.split('\n').map(function (string, index) {
149+
150+
/*
151+
* Create a line number like 00, 01, 02, etc...
152+
*/
153+
if (!index) return string;
154+
var ind = index - 1 + '';
155+
if (ind.length < 2) ind = '0' + ind;
156+
157+
/*
158+
* Return a new span on the beginning og the line.
159+
*/
160+
return '<span class="linenum">' + ind + '</span> ' + string;
161+
}).join('\n');
162+
}
163+
block.innerHTML = parsed;
164+
});
165+
}
166+
167+
/*
168+
* Export the hightlight function
169+
*/
170+
module.exports = exports = highlight;

0 commit comments

Comments
 (0)