text processing utilities

Highlight Dokumentation

Plug-Ins

Die Plug-In Schnittstelle erlaubt Anpassungen der Syntax-Erkennung und der Farbgebung. Die Ausgabedatei kann im Kopf- und Fußteil erweitert werden, und Syntaxelemente können um weitere Informationen ergänzt werden.
Ein einfaches Plug-In könnte neue Schlüsselworter mit eigener Formatierung definieren oder bestehende Listen erweitern. Fortgeschrittene Skripte lesen beispielsweise Informationen aus ctags-Dateien ein und geben diese als Tooltips aus, oder geben HTML mit Javascript Code-Folding aus.
Das Highlight-Paket enthält mehrere Plug-Ins als Vorlage.

Skriptaufbau

Das folgende Skript enthält ein minimales Plug-In ohne Auswirkung auf die Ausgabe, da die Funktionen mit leerem Rumpf definiert sind:

01 Description="Boilerplate plugin"
02 
03 -- optional parameter: syntax description
04 function syntaxUpdate(desc)
05 end
06 
07 -- optional parameter: theme description
08 function themeUpdate(desc)
09 end
10 
11 Plugins={
12   { Type="theme", Chunk=themeUpdate },
13   { Type="lang", Chunk=syntaxUpdate },
14 }

Die erste Zeile enthält eine Beschreibung des Plug-Ins.

Die nächsten Zeilen enthalten Funktionsdefinitionen: Die syntaxUpdate-Funktion wird auf Sprachdefinitionen angewandt (*.lang), während die themeUpdate-Funktion auf Farbschemata angewandt wird (*.theme). Die Namen der Funktionen können frei gewählt werden.
Der desc-Parameter enthält die Beschreibung der Sprachdefiniton oder des Farbschemas. Er kann benutzt werden, um Änderungen nur auf bestimmte Eingabedaten anzuwenden (z.B. sollen syslog-Schlüsselwörter nur bei C Code ergänzt werden).

Das Plugins-Array verbindet die Funktionen mit den Lua-States, die beim Laden der lang- oder theme-Skripte erzeugt werden. In diesem Beispiel ist themeUpdate mit dem theme-State verbunden, und syntaxUpdate mit dem lang-State. Es ist nicht nötig, beide Verbindungen anzugeben, wenn nur ein Typ der Konfigurationsskripte angepasst werden soll.

Elemente der Sprachdefinitionen

Diese Liste enthält alle Elemente, die überschrieben oder erweitert werden können, um das Syntax-Highlighting anzupassen:

Syntax definition items:

Comments: table
Description: string
Digits: string
EnableIndentation: boolean
Identifiers: string
IgnoreCase: boolean
Keywords: table
NestedSections: table
Operators: string
PreProcessor: table
Strings: table

Document modification items:

HeaderInjection: string
FooterInjection: string

Read only (internal highlighting states):

HL_STANDARD: number
HL_BLOCK_COMMENT: number
HL_BLOCK_COMMENT_END: number
HL_EMBEDDED_CODE_BEGIN: number
HL_EMBEDDED_CODE_END: number
HL_ESC_SEQ: number
HL_ESC_SEQ_END: number
HL_IDENTIFIER_BEGIN: number
HL_IDENTIFIER_END: number
HL_KEYWORD: number
HL_KEYWORD_END: number
HL_LINENUMBER: number
HL_LINE_COMMENT: number
HL_LINE_COMMENT_END: number
HL_NUMBER: number
HL_OPERATOR: number
HL_OPERATOR_END: number
HL_PREPROC: number
HL_PREPROC_END: number
HL_PREPROC_STRING: number
HL_STRING: number
HL_STRING_END: number
HL_UNKNOWN: number
HL_REJECT: number

Read only (other):

HL_PLUGIN_PARAM: string (set with --plug-in-param)
HL_LANG_DIR: string (path of language definition directory)


Read only (output document format):

HL_OUTPUT: number (selected format)
HL_FORMAT_HTML: number
HL_FORMAT_XHTML: number
HL_FORMAT_TEX: number
HL_FORMAT_LATEX: number
HL_FORMAT_RTF: number
HL_FORMAT_ANSI: number
HL_FORMAT_XTERM256: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE: number
HL_FORMAT_PANGO: number
HL_FORMAT_ODT: number

Functions:

AddKeyword: function
OnStateChange: function
Decorate: function
DecorateLineBegin: function
DecorateLineEnd: function

WICHTIG: Die Funktionen werden nur dann ausgewertet, wenn sie als lokale Funktion innerhalb der im Plugins-Array angegebenen Funktion definiert werden. An anderen Stellen im Skript werden sie ignoriert.

Funktion OnStateChange

Diese Hook-Funktion wird immer dann ausgeführt, wenn sich der Zustand des Parsers ändert (z.B. von HL_STANDARD zu HL_KEYWORD wenn ein Schlüsselwort erkannt wird). Mit OnStateChange kann der neue Zustand angepasst werden oder es können Syntaxelemente manipuliert werden.

OnStateChange(oldState, newState, token, kwGroupID)

  Hook Event: Highlighting parser state change
  Parameters: oldState:  old state
              newState:  intended new state
              token:     the current token which triggered
	                 the new state
              kwGroupID: if newState is HL_KEYWORD, the parameter
                         contains the keyword group ID
  Returns:    Correct state to continue OR HL_REJECT

Return HL_REJECT if the recognized token and state should be discarded; only the 
first character of token will be outputted using the state defined as oldState.

Beispiele:

01 function OnStateChange(oldState, newState, token, kwgroup)
02    if newState==HL_KEYWORD and kwgroup==5 then
03       AddKeyword(token, 5)
04    end
05    return newState
06 end

Dise Funktion fügt das aktuelle Token zu der internen Schlüsselwort-Liste hinzu, wenn es zur Schlüsselwortgruppe 5 gehört. Wird Gruppe 5 durch einen regulären Ausdruck bestimmt, so wird das Token später als Schlüsselwort erkannt, auch wenn der Ausdruck dann nicht zutreffen sollte.

01 function OnStateChange(oldState, newState, token)
02    if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then
03       return HL_STRING_END
04    end
05    return newState
06 end

Dise Funktion behebt ein Problem mit dem Lua Begrenzer "]]", der Kommentare und Strings abschliessen kann.

Funktion AddKeyword

Diese Funktion fügt ein Schlüsselwort zu einer der internen Listen hinzu. Sie tut nichts wenn das Schlüsselwort bereits Element einer Liste ist. Die mit AddKeyword angegebenen Schlüsselwörter bleiben für alle Dateien derselben Syntax bestehen, wenn Highlight im Batch-Modus ausgeführt wird.

AddKeyword(keyword, kwGroupID)

  Parameters: keyword:   string which should be added to a keyword list
              kwGroupID: keyword group ID of the keyword
  Returns:    true if successfull

Decorate-Funktionen

Die Decorate-Funktion wird ausgeführt, wenn ein Token erkannt wurde. Mit ihrer Hilfe kann das Token verändert oder zusätzlicher Text im Ausgabeformat hinzugefügt werden (z.B. Hyperlinks).

Decorate(token, state, kwGroupID)

  Hook Event: Token identification
  Parameters: token:     the current token
	      state:     the current state
              kwGroupID: if state is HL_KEYWORD, the parameter
                         contains the keyword group ID
  Returns:    Altered token string or nothing if original token should be
              outputted

Diee Funktionen DecorateLineBegin und DecorateLineEnd werden aufgerufen wenn eine Zeile beginnt oder endet. So können einzelne Zeilen besonders formatiert werden.

DecorateLineBegin(lineNumber)

  Hook Event: output of a new line
  Parameters: lineNumber: the current line number
  Returns:    A string to be prepended to a new line (or nothing) 

DecorateLineEnd(lineNumber)

  Hook Event: output of a line ending
  Parameters: lineNumber: the current line number
  Returns:    A string to be appended to a line (or nothing)

Achtung: Der Rückgabewert von Decorate-Funktionen wird innerhalb von Formatierungstags des Ausgabeformats ausgegeben. Der Rückgabewert wird von highlight nicht geprüft oder verändert.

Beispiel:
01 function Decorate(token, state)
02   if (state == HL_KEYWORD) then
03     return  string.upper(token)
04   end
05 end

Diese Funktion konvertiert alle Schlüsselwörter in Großbuchstaben.

Elemente der Farbbeschreibungen

Diese Liste enthält alle Elemente, die überschrieben oder erweitert werden können, um die Farbausgabe anzupassen:

Output formatting items:

Default: table
Canvas: table
Number: table
Escape: table
String: table
StringPreProc: table
BlockComment: table
PreProcessor: table
LineNum: table
Operator: table
LineComment: table
Keywords: table

Custom theme items:

Injections: table

Read only (output document format):

HL_OUTPUT: number
HL_FORMAT_HTML: number
HL_FORMAT_XHTML: number
HL_FORMAT_TEX: number
HL_FORMAT_LATEX: number
HL_FORMAT_RTF: number
HL_FORMAT_ANSI: number
HL_FORMAT_XTERM256: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE: number
HL_FORMAT_ODT: number

Komplettes Beispiel:

01 -- Beginne mit der Beschreibung des Plug-ins
02 Description="Add qtproject.org reference links to HTML, LaTeX or RTF output"
03 
04 -- Die syntaxUpdate-Funktion enthält Code, der die Syntaxerkennung beeinflusst
05 function syntaxUpdate(desc)
06 
07   -- Wenn die aktuelle Datei kein C++ enthält, brechen wir ab
08   if desc~="C and C++" then
09      return
10   end
11       
12   -- Diese Funktion gibt einen qt-project Referenzlink des Tokens zurück
13   function getURL(token)
14      -- erzeuge den URL
15      url='http://qt-project.org/doc/qt-4.8/'..string.lower(token).. '.html'
16      
17      -- Füge die Addresse in einen Link passend zum Ausgabeformat ein
18      -- erst HTML, dann LaTeX und RTF
19      if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
20         return '<a class="hl" target="new" href="' 
21                .. url .. '">'.. token .. '</a>'
22      elseif (HL_OUTPUT == HL_FORMAT_LATEX) then
23         return '\\href{'..url..'}{'..token..'}'
24      elseif (HL_OUTPUT == HL_FORMAT_RTF) then
25         return '{{\\field{\\*\\fldinst HYPERLINK "'
26                ..url..'" }{\\fldrslt\\ul\\ulc0 '..token..'}}}'
27      end
28    end
29 
30   -- Die Decorate Funktion wird für jedes erkannte Token aufgerufen
31   function Decorate(token, state)
32 
33     -- Wir interessieren uns nur für Schlüsselwörter, Präprozessor- und Standardelemente
34     if (state ~= HL_STANDARD and state ~= HL_KEYWORD and 
35         state ~=HL_PREPROC) then
36       return
37     end
38 
39     -- Qt-Schlüsselwörter beginnen mit Q, gefolgt von einem Groß- und einem Kleinbuchstaben
40     -- Wenn dieses Muster zum Token passt, geben wir den URL zurück
41     -- Wenn wir nichts zurückgeben, bleibt das Token unverändert
42     if string.find(token, "Q%u%l")==1 then
43       return getURL(token)
44     end
45 
46   end
47 end
48 
49 -- Die themeUpdate-Funktion beeinflußt Themes
50 function themeUpdate(desc)
51   -- Mit der Injections-Tabelle kann das Theme um weitere Formatangaben erweitert werden
52   
53   -- HTML: wir fügen CSS hinzu, um die Links zu verschönern
54   -- Sie sollten dasselbe Format wie die umschließenden Tags haben
55   if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
56     Injections[#Injections+1]=
57       "a.hl, a.hl:visited {color:inherit;font-weight:inherit;}"
58       
59   -- LaTeX: Links benötigen das hyperref-Paket, also fügen wir es hinzu
60   -- Die Optionen colorlinks und pdfborderstyle entfernen unschöne Boxen in der Ausgabe
61   elseif (HL_OUTPUT==HL_FORMAT_LATEX) then
62     Injections[#Injections+1]=
63       "\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}"
64   end
65 end
66 
67 -- Chunks zuweisen
68 Plugins={
69   { Type="lang", Chunk=syntaxUpdate },
70   { Type="theme", Chunk=themeUpdate },
71 }
Tupel7