README_PLUGINS 14.3 KB
Newer Older
1
-------------------------------------------------------------------------------
André Simon's avatar
André Simon committed
2
---  HIGHLIGHT PLUGIN MANUAL - Version 3.36   ------------------ March 2017 ---
3 4 5 6 7
-------------------------------------------------------------------------------

CONTENT
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
8 9 10
1. ABOUT
2. SCRIPT STRUCTURE
3. SYNTAX CHUNK ELEMENTS
saalen's avatar
saalen committed
11 12
   3.1 FUNCTION ADDKEYWORD
   3.2 FUNCTION ONSTATECHANGE
13
   3.3 DECORATE FUNCTIONS
saalen's avatar
saalen committed
14 15 16 17
4. THEME CHUNK ELEMENTS
5. STEP BY STEP
6. EXAMPLES
7. PLUG-IN USAGE
18 19


saalen's avatar
saalen committed
20
1. ABOUT
saalen's avatar
saalen committed
21 22 23
-------------------------------------------------------------------------------

The plug-in interface allows modifications of syntax parsing and colouring.
saalen's avatar
saalen committed
24 25 26 27 28
The output's header or footer can be enhanced, and recognized syntax elements
may be outputted with additional information.
A common task would be to define a new set of syntax keywords, or to add items
to existing keyword groups. More advanced plug-ins add tooltips based on ctags 
input or source code folding to the output (see section 6).
saalen's avatar
saalen committed
29 30 31


2. SCRIPT STRUCTURE
32 33
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
34 35
The following script contains the basic plug-in structure which has no effect 
on the output:
36

saalen's avatar
saalen committed
37
Description="Plugin Boilerplate"
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

-- optional parameter: syntax description
function syntaxUpdate(desc)
end

-- optional parameter: theme description
function themeUpdate(desc)
end

Plugins={
  { Type="theme", Chunk=themeUpdate },
  { Type="lang", Chunk=syntaxUpdate },
}

The first line contains a description which gives a short summary of the
plug-in effects.

The next lines contain function definitions:
The syntaxUpdate function is applied on syntax definition scripts (*.lang),
whereas the themeUpdate function is applied on colour themes (*.theme).
saalen's avatar
saalen committed
58 59 60 61
The desc parameter contains the description string of the loaded syntax
definition or colour theme. This information can be used to restrict
modifications to certain kinds of input (i.e. only C code should be
enhanced with syslog keywords).
62

saalen's avatar
saalen committed
63 64 65
Finally the Plugins array connects the functions to the Lua states which 
are created when highlight loads a lang or theme script. In this example,
themeUpdate is connected to the theme state, and syntaxUpdate to the lang
saalen's avatar
saalen committed
66
state. It is not required to always define both connections if your plugin
saalen's avatar
saalen committed
67
only affects one of the config script types.
68 69


saalen's avatar
saalen committed
70
3. SYNTAX CHUNK ELEMENTS
71 72
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
73
The following list includes all variables and constants you may use to adjust 
Saalen's avatar
Saalen committed
74 75
the parser's syntax highlighting.

saalen's avatar
saalen committed
76
Syntax definition items:
77 78 79 80 81 82 83 84 85 86 87 88

Comments: table
Description: string
Digits: string
EnableIndentation: boolean
Identifiers: string
IgnoreCase: boolean
Keywords: table
NestedSections: table
Operators: string
PreProcessor: table
Strings: table
saalen's avatar
saalen committed
89 90 91

Document modification items:

92 93
HeaderInjection: string
FooterInjection: string
94

saalen's avatar
saalen committed
95
Read only (internal highlighting states):
96

saalen's avatar
saalen committed
97
HL_STANDARD: number
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
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
120
HL_REJECT: number
121

saalen's avatar
saalen committed
122 123 124
Read only (output document format):

HL_OUTPUT: number (selected format)
saalen's avatar
saalen committed
125 126 127 128 129 130 131 132 133
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
134
HL_FORMAT_PANGO: number
saalen's avatar
saalen committed
135
HL_FORMAT_ODT: number
saalen's avatar
saalen committed
136

saalen's avatar
saalen committed
137 138 139 140 141
Read only (other):

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

142 143 144 145
Functions:

AddKeyword: function
OnStateChange: function
saalen's avatar
saalen committed
146
Decorate: function
147 148
DecorateLineBegin: function
DecorateLineEnd: function
saalen's avatar
saalen committed
149 150

IMPORTANT: Functions will only be executed if they are defined as local
saalen's avatar
saalen committed
151
functions within the "lang" chunk referenced in the Plugins array. 
saalen's avatar
saalen committed
152
They will be ignored when defined elsewhere in the script.
153 154


saalen's avatar
saalen committed
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
3.1 FUNCTION ADDKEYWORD
-------------------------------------------------------------------------------

This function will add a keyword to one of the the internal keyword lists.
It has no effect if the keyword was added before.
Keywords added with AddKeyword will remain active for all files of the same
syntax if highlight is in batch mode.

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
  

3.2 FUNCTION ONSTATECHANGE
171 172
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
173
This function is a hook which is called if an internal state changes (e.g. from
174 175 176 177 178 179 180 181
HL_STANDARD to HL_KEYWORD if a keyword is found). It can be used to alter
the new state or to manipulate syntax elements.

OnStateChange(oldState, newState, token, kwGroupID)

  Hook Event: Highlighting parser state change
  Parameters: oldState:  old state
              newState:  intended new state
saalen's avatar
saalen committed
182
              token:     the current token which triggered the new state
183 184
              kwGroupID: if newState is HL_KEYWORD, the parameter
                         contains the keyword group ID
185 186
  Returns:    Correct state to continue OR HL_REJECT

saalen's avatar
saalen committed
187 188
Return HL_REJECT if the recognized token and state should be discarded; the 
first character of token will be outputted and highlighted as oldState.
189 190 191 192 193 194 195 196 197 198

Examples:

function OnStateChange(oldState, newState, token, kwgroup)
   if newState==HL_KEYWORD and kwgroup==5 then
      AddKeyword(token, 5)
   end
   return newState
end

saalen's avatar
saalen committed
199 200 201 202
This function adds the current keyword to the internal keyword list if the 
keyword belongs to keyword group 5. If keyword group 5 is defined by a regex,
this token will be recognized later as keyword even if the regular expression 
does no longer match.
203 204 205 206 207 208 209 210 211 212 213 214

function OnStateChange(oldState, newState, token)
   if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then
      return HL_STRING_END
   end
   return newState
end

This function resolves a Lua parsing issue with the "]]" close delimiter which
ends both comments and strings.


215
3.3 DECORATE FUNCTIONS
saalen's avatar
saalen committed
216 217
-------------------------------------------------------------------------------

218
The Decorate function is a hook which is called if a syntax token has been 
219
identified. It can be used to alter the token or to add additional text in the
220
target output format (e.g. hyperlinks). 
saalen's avatar
saalen committed
221

222
Decorate(token, state, kwGroupID, stateTrace)
223

saalen's avatar
saalen committed
224
  Hook Event: Token identification
225 226 227 228 229
  Parameters: token:      current token
              state:      current state
              kwGroupID:  if state is HL_KEYWORD, the parameter
                          contains the keyword group ID
              stateTrace: string containing past states of the current line;
saalen's avatar
saalen committed
230
                          separated by ';'; limited to 100 entries
saalen's avatar
saalen committed
231 232 233
  Returns:    Altered token string or nothing if original token should be 
              outputted

saalen's avatar
saalen committed
234 235 236 237
Examples:

function Decorate(token, state)
  if (state == HL_KEYWORD) then
saalen's avatar
saalen committed
238
    return string.upper(token)
saalen's avatar
saalen committed
239 240 241 242 243 244
  end
end

This function converts all keywords to upper case.


245
The functions DecorateLineBegin and DecorateLineEnd are called if a new line
246
starts or ends. They can be used to add special formatting to lines of code.
247 248 249 250 251 252 253 254 255 256 257 258 259

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)
  
260 261 262 263 264

IMPORTANT: The return value of Decorate functions will be embedded in the 
formatting tags of the output format. The return values are not modified or 
validated by highlight.

265
  
saalen's avatar
saalen committed
266
4. THEME CHUNK ELEMENTS
267 268
-------------------------------------------------------------------------------

Saalen's avatar
Saalen committed
269 270 271
The following list includes all items you may overwrite or extend to adjust
the formatting (colour and font attributes) of the output:

saalen's avatar
saalen committed
272 273
Output formatting items:

274 275 276 277 278 279 280 281 282 283 284 285
Default: table
Canvas: table
Number: table
Escape: table
String: table
StringPreProc: table
BlockComment: table
PreProcessor: table
LineNum: table
Operator: table
LineComment: table
Keywords: table
saalen's avatar
saalen committed
286 287

Read only (output document format)::
saalen's avatar
saalen committed
288 289 290 291 292 293 294 295 296 297 298

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
299
HL_FORMAT_PANGO: number
saalen's avatar
saalen committed
300
HL_FORMAT_ODT: number
301

saalen's avatar
saalen committed
302 303 304 305
Add additional stying information:

Injections: table

306

saalen's avatar
saalen committed
307
5. STEP BY STEP
308 309
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
310 311
This example will add reference hyperlinks to Qt keywords:

312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
-- first add a description of what the plug-in does
Description="Add qtproject.org reference links to HTML, LaTeX or RTF output"

-- the syntaxUpdate function contains code related to syntax recognition
function syntaxUpdate(desc)

  -- if the current file is no C++ file we exit
  if desc~="C and C++" then
     return
  end
      
  -- this function returns a qt-project reference link of the given token
  function getURL(token)
     -- generate the URL
     url='http://qt-project.org/doc/qt-4.8/'..string.lower(token).. '.html'
     
saalen's avatar
saalen committed
328 329
     -- embed the URL in a hyperlink according to the output format
     -- first HTML, then LaTeX and RTF
330
     if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
saalen's avatar
saalen committed
331 332 333 334
         return '<a class="hl" target="new" href="' 
                .. url .. '">'.. token .. '</a>'
     elseif (HL_OUTPUT == HL_FORMAT_LATEX) then
         return '\\href{'..url..'}{'..token..'}'
335
     elseif (HL_OUTPUT == HL_FORMAT_RTF) then
saalen's avatar
saalen committed
336 337
         return '{{\\field{\\*\\fldinst HYPERLINK "'
                ..url..'" }{\\fldrslt\\ul\\ulc0 '..token..'}}}'
338 339 340 341 342 343 344 345
     end
   end

  -- the Decorate function will be invoked for every recognized token
  function Decorate(token, state)

    -- we are only interested in keywords, preprocessor or default items
    if (state ~= HL_STANDARD and state ~= HL_KEYWORD and 
saalen's avatar
saalen committed
346
        state ~=HL_PREPROC) then
347 348 349
      return
    end

saalen's avatar
saalen committed
350 351 352
    -- Qt keywords start with Q, followed by an upper and a lower case letter
    -- if this pattern applies to the token, we return the URL
    -- if we return nothing, the token is outputted as is
353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
    if string.find(token, "Q%u%l")==1 then
      return getURL(token)
    end

  end
end

-- the themeUpdate function contains code related to the theme
function themeUpdate(desc)
  -- the Injections table can be used to add style information to the theme
  
  -- HTML: we add additional CSS style information to beautify hyperlinks,
  -- they should have the same color as their surrounding tags
  if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
    Injections[#Injections+1]=
saalen's avatar
saalen committed
368
      "a.hl, a.hl:visited {color:inherit;font-weight:inherit;}"
saalen's avatar
saalen committed
369

370 371 372 373
  -- LaTeX: hyperlinks require the hyperref package, so we add this here
  -- the colorlinks and pdfborderstyle options remove ugly boxes in the output
  elseif (HL_OUTPUT==HL_FORMAT_LATEX) then
    Injections[#Injections+1]=
saalen's avatar
saalen committed
374
      "\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}"
375 376 377 378 379 380 381 382 383
  end
end

-- let highlight load the chunks
Plugins={
  { Type="lang", Chunk=syntaxUpdate },
  { Type="theme", Chunk=themeUpdate },
}

384

saalen's avatar
saalen committed
385
6. EXAMPLES
386 387
-------------------------------------------------------------------------------

saalen's avatar
saalen committed
388
The plugins directory contains example scripts, including: 
389 390 391

bash_functions.lua
Description: Add function names to keyword list
saalen's avatar
saalen committed
392 393
Features:    Adds new keyword group based on a regex, defines OnStateChange,
             uses AddKeyword
394 395 396

theme_invert.lua
Description: Invert colours of the original theme
saalen's avatar
saalen committed
397 398 399 400 401 402 403 404 405 406 407
Features:    Modifies all color attributes of the theme script, uses Lua
             pattern matching
          
cpp_ref_cplusplus_com.lua
Description: Add qtproject.org reference links to HTML, LaTeX or RTF output of
             C++ code
Features:    Uses Decorate to add hyperlinks for a defined set of C++ keywords.
             Adds CSS styles with Injections.

ctags_html_tooltips.lua
Description: Add tooltips based on a ctags file (default input file: tags)
saalen's avatar
saalen committed
408
Features:    Uses file input (defined by cli option --plug-in-param) and
saalen's avatar
saalen committed
409
             parses tags data before Decorate is called.
410
             
saalen's avatar
saalen committed
411
outhtml_curly_brackets_matcher.lua
412 413
Description: Shows matching curly brackets in HTML output.
Features:    Uses Decorate to add span tags with unique ids to opening and 
saalen's avatar
saalen committed
414 415
             closing brackets.
             Adds JavaScript with HeaderInjection variable.
saalen's avatar
saalen committed
416
             Inserts additional CSS styles with Injections variable.
saalen's avatar
saalen committed
417 418 419 420 421 422 423
             
outhtml_keyword_matcher.lua
Description: Shows matching keywords in HTML output.
Features:    Uses Decorate to add span tags with unique ids to opening and 
             closing brackets.
             Uses OnStateChange to assign an internal ID to each keyword.
             Adds JavaScript with HeaderInjection variable.
saalen's avatar
saalen committed
424
             Inserts additional CSS styles with Injections variable.
saalen's avatar
saalen committed
425
             
saalen's avatar
saalen committed
426 427 428 429 430
outhtml_codefold.lua
Description: Adds code folding for C style languages, Pascal, Lua and Ruby to 
             HTML output
Features:    Uses DecorateLineBegin and DecorateLineEnd to add ID-spans to each 
             line.
saalen's avatar
saalen committed
431
             Applies Decorate to each code block delimiter to add onClick event 
saalen's avatar
saalen committed
432 433 434 435
             handlers.
             Adds JavaScript with HeaderInjection and FooterInjection variables.
             Inserts additional CSS styles with Injections variable.
             
436
 
saalen's avatar
saalen committed
437
7. PLUG-IN USAGE
Saalen's avatar
Saalen committed
438 439 440
-------------------------------------------------------------------------------

Command line interface:
saalen's avatar
saalen committed
441
Run highlight --list-scripts=plugins to show all installed plug-ins.
saalen's avatar
saalen committed
442

saalen's avatar
saalen committed
443
Use --plug-in to load a plug-in script file. This option can be applied 
444 445 446 447
more than once to apply several plug-ins. Omit the .lua suffix.
You can store your plug-in scripts for testing in ~/.highlight/plugins.

Example:
saalen's avatar
saalen committed
448
highlight my.cpp -Ilz --plug-in=html_curly_brackets_matcher > ~/test_out/my.html
449

Saalen's avatar
Saalen committed
450 451 452

GUI:
Add the plug-in scripts in the plug-in selection tab and enable them using the
453
checkboxes.