Highlight Dokumentation
Plug-Ins
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="NOOP 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 der Auswirkungen 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 Änderugen 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:
Comments: table Description: string Digits: string EnableIndentation: boolean Identifiers: string IgnoreCase: boolean Keywords: table NestedSections: table Operators: string PreProcessor: table Strings: table Read only constants: HL_LANG_DIR: string 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_STANDARD: number HL_STRING: number HL_STRING_END: number HL_UNKNOWN: number 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 Functions: AddKeyword: function OnStateChange: function Decorate: function
WICHTIG: Die Funktionen werden nur dann ausgewertet, wenn sie als lokale Funktion innerhalb der im Plugins-Array angegebenen lang-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
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
Funktion Decorate
Diese Hook-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). Achtung: Der Rückgabewert von Decorate wird innerhalb von umschließenden Formatierungstags ausgegeben. Der Rückgabewert wird von highlight nicht geprüft oder verändert.
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
Beispiele:
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.
01 knowntags={} 02 file = assert(io.open(HL_INPUT_FILE, "r")) 03 -- read file and fill knowntags 04 05 function Decorate(token, state, kwclass) 06 for k,v in pairs(knowntags) do 07 if k==token then 08 return '<span title="'..v..'">'..token .. '</span>' 09 end 10 end 11 end
Diese Funktion versieht Token mit Tooltips, wenn sie in der angegebenen tags Datei enthalten sind.
Elemente der Farbbeschreibungen
Diese Liste enthält alle Elemente, die überschrieben oder erweitert werden können, um die Farbausgabe anzupassen:
Default: table Canvas: table Number: table Escape: table String: table StringPreProc: table BlockComment: table PreProcessor: table LineNum: table Operator: table LineComment: table Keywords: table Injections: table Read only: 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
Beispiele:
01 -- function to update language definition with syslog levels 02 function syntaxUpdate(desc) 03 if desc=="C and C++" then 04 table.insert( Keywords, 05 { Id=5, List={"LOG_EMERG", "LOG_CRIT", "LOG_ALERT", 06 "LOG_ERR", "LOG_WARNING","LOG_NOTICE","LOG_INFO", 07 "LOG_DEBUG"} 08 } ) 09 end 10 end 11 12 -- function to update theme definition 13 function themeUpdate(desc) 14 if desc=="Kwrite Editor" then 15 Canvas={ Colour="#E0EAEE" } 16 end 17 table.insert(Keywords, {Colour= "#ff0000", Bold=true}) 18 end 19 20 Plugins={ 21 { Type="theme", Chunk=themeUpdate }, 22 { Type="lang", Chunk=syntaxUpdate }, 23 }
01 Description="Add wxwidgets.org reference links to HTML, LaTeX or RTF output of C++ code" 02 03 function syntaxUpdate(desc) 04 05 if desc~="C and C++" then 06 return 07 end 08 09 function getURL(token) 10 urltoken, cnt = string.gsub(token, "%u", "_%1") 11 url='http://docs.wxwidgets.org/2.9.3/class'..string.lower(urltoken).. '.html' 12 13 if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then 14 return '<a class="hl" target="new" href="' .. url .. '">'.. token .. '</a>' 15 elseif (HL_OUTPUT == HL_FORMAT_LATEX) then 16 return '\\href{'..url..'}{'..token..'}' 17 elseif (HL_OUTPUT == HL_FORMAT_RTF) then 18 return '{{\\field{\\*\\fldinst HYPERLINK "'..url..'" }\\fldrslt \\ul\\ulc0 '..token..'}}' 19 end 20 end 21 22 function Decorate(token, state) 23 if (state ~= HL_STANDARD and state ~= HL_KEYWORD ) then 24 return 25 end 26 if string.find(token, "wx%u")==1 then 27 return getURL(token) 28 end 29 end 30 end 31 32 function themeUpdate(desc) 33 if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then 34 Injections[#Injections+1]="a.hl, a.hl:visited {color:inherit;font-weight:inherit;}" 35 elseif (HL_OUTPUT==HL_FORMAT_LATEX) then 36 Injections[#Injections+1]="\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}" 37 end 38 end 39 40 Plugins={ 41 42 { Type="lang", Chunk=syntaxUpdate }, 43 { Type="theme", Chunk=themeUpdate }, 44 45 }
