syntax

Syntax
======

Unobtrusive Syntax Highlighting Library

About
-----

Syntax is JavaScript library (for use in Node.js and Browser
environments) to apply Syntax Highlighting to a piece of input text --
usually source code. Syntax is based on four major design aspects:

- Good Language Support:
The language-specific determination of comments, keywords and
literals should be a reasonable one. As syntax highlighting
is a science of its own, Syntax under the hood uses the excellent
Highlight.js library.

- Unobtrusive Syntax Highlighting:
The author, Ralf S. Engelschall, is a die-hard coder with a very
strict opinion when it comes to source code. One of his opinions is
that syntax highlighting has to be as unobstrusive as possible and
hence should highlight comments, keywords, and literals only. As a
consequence, Syntax intentionally(!) reduces the syntax highlighting
of the underlying Highlight.js to just
these three kinds of syntactical elements.

- Anchors and Markers:
In technical documentation it is regularily necessary to mark
arbitrary pieces of code and interspice reference anchors.
Unfortunately, whatever syntax is used for marking and anchors, this
always conflicts with the language-dependent syntax highlighting
as the marking and anchors renders the source code invalid. Syntax
resolves this problem by first reducing the (rich) input text to plain
text (by removing markings and anchors) and reapplying the markings
and anchors during output generation.

- Arbitrary Output Formats:
Usually, having HTML or XML output format is sufficient, but sometimes
one also wants to support other formats and for this one needs the
precise offset information for anchors, markings, comments, keywords
and literals. Syntax supports this by internally using such an offset
based markup information and also exposing it in the API for external
consumption.

Installation
------------

#### Node environments (with NPM package manager):

``shell
$ npm install syntax
`

#### Browser environments (with Bower package manager):

`shell
$ bower install syntax
`

Example
-------

The following is an example of Syntax in the Node.js environment:

`js
import Syntax from "syntax"

let syntax = new Syntax({
language: "javascript",
cssPrefix: ""
})

syntax.richtext(
"/ sample comment /\n" +
"={function foo}= (bar, quux) {\n" +
" return 42 =(1)=\n" +
"}\n"
)

console.log(syntax.plaintext())
// +--- output: ---------------------------
// | / sample comment /\n
// | function foo (bar, quux) {\n
// | return 42 \n
// | }\n
// +---------------------------------------

console.log(require("util").inspect(syntax.markup(), { depth: null }))
// +--- output: ---------------------------
// | { anchor: { '1': 62 },
// | marker: [ [ 21, 33 ] ],
// | comment: [ [ 0, 20 ] ],
// | keyword: [ [ 21, 29 ], [ 52, 58 ] ],
// | literal: [ [ 59, 61 ] ] }
// +---------------------------------------

console.log(syntax.html())
// +--- output: ---------------------------
// | / sample comment /\n
// | function foo (bar, quux) {\n
// | return 42 \n
// | }\n
// +---------------------------------------
`

For an example of Syntax in the Browser environment, see
the included Sample project.

Application Programming Interface (API)
---------------------------------------

$3

- import Syntax from "syntax"

Import Syntax (ECMAScript 6 variant).

- var Syntax = require("syntax").default

Import Syntax (CommonJS variant).

$3

- Constructor: Syntax(config?: Object): Syntax

Create a new syntax highlighting instance with
optional configuration settings.

- Class Method: Syntax.version(): { major: Number, minor: Number, micro: Number, date: Number }:

Return the Sugar library version. The date is in numeric format YYYYMMDD.

- Method: Syntax#config(config?: Object): Syntax

Set configuration settings. The available configuration options are:

- language (default: "auto"):

Control the syntax highlighting of comments, keywords and literals.
By default, the language is guessed. See below for recognized
language identifiers. Set to "none" to enforce no syntax
highlighting of comments, keywords and literals at all (then
just markings and anchors are recognized).

- cssPrefix (default: "syntax-"):

The CSS class prefix used in the HTML output.

- xmlPrefix (default: "syntax-"):

The XML tag prefix used in the XML output.

- tabReplace (default: " "):

The string TAB characters are replaced to in the output.

- newlineReplace (default: "\n"):

The string newlines (\r?\n) are replaced to in the output.

- regexAnchorOpen (default: "=\\("):

The regular expression (as a string) to recognize the opening of anchors.
Remember to extra-escape the special characters and to pass this as a
string, as Syntax internally has to assemble the regular expressions.

- regexAnchorClose (default: "\\)="):

The regular expression (as a string) to recognize the closing of anchors.
Remember to extra-escape the special characters and to pass this as a
string, as Syntax internally has to assemble the regular expressions.

- regexMarkerOpen (default: "=\\{"):

The regular expression (as a string) to recognize the opening of markings.
Remember to extra-escape the special characters and to pass this as a
string, as Syntax internally has to assemble the regular expressions.

- regexMarkerClose (default: "\\}="):

The regular expression (as a string) to recognize the closing of markings.
Remember to extra-escape the special characters and to pass this as a
string, as Syntax internally has to assemble the regular expressions.

- Method: Syntax#richtext(input: String): Syntax

Set the rich input text to process.

- Method: Syntax#plaintext(): String

Method: Syntax#plaintext(plaintext: String): Syntax

Get or set the plain (output) text (the rich text after removing explicit markers and anchors).
The plain text is updated when richtext() is called. If using a custom
markup information it can be also set manually.

- Method: Syntax#markup(): Markup

Method: Syntax#markup(markup: Markup): Syntax

Get or set the markup information. The markup information is updated
when richtext() is called. But a custom markup information can
be provided manually, too. The format of the markup information is:

`
{
anchor: {
:
:
},
marker: [
[ , ]
:
],
comment: [
[ , ]
:
],
keyword: [
[ , ]
:
],
literal: [
[ , ]
:
]
}
`

The positions are zero-based and end positions are at the first
character not included in the range.

- Method: Syntax#html(): String

Apply the output markup information onto the output plain text and
render the result as HTML, based on interweaved
and tags.

- Method: Syntax#xml(): String

Apply the output markup information onto the output plain text and
render the result as XML, based on interweaved
<{xmlPrefix}{type}> and tags.

Language Support
----------------

By default, Syntax supports the following major languages (with the
language configuration option identifiers in parenthesis):

1. Web Languages: XML/HTML (xml), CSS (css), LESS
(less), HTTP (http).

2. Configuration Languages: JSON (json), YAML yaml, INI ini.

3. Progamming Languages: C/C++ (cpp), Objective-C (objectivec),
Swift (swift), C# (cs, csharp), F# (fsharp), Go (go), Java
(java), Kotlin (kotlin), Groovy (groovy), Scala (scala), JavaScript (js,
javascript), TypeScript (typescript), PHP (php), Perl (perl),
Python (python), Ruby (ruby).

4. Shell Languages: Bourne Shell (shell), Bash (bash), PowerShell
(powershell), Makefile (makefile).

5. Other Languages: SQL (sql), MarkDown (markdown), Diff (diff).

Those languages are pre-loaded in Node.js and bundled
with Syntax in the browser. In Node.js more languages
can be auto-loaded by just setting the language
configuration to its official identifier. See Highlight.js'
sources
for the identifiers (it is just the filename without the .js
extension). In browser environments, auto-loading additional languages
obviously does not work. There you have to bundle the additional
languages youself and call hljs.registerLanguage()` yourself.

Implementation Notice
---------------------

Although Syntax is written in ECMAScript 6, it is transpiled to ECMAScript
5 and this way runs in really all(!) current (as of 2015) JavaScript
environments, of course.

License
-------

Copyright © 2015-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.