GeSHi PHP Cross Reference Developer Tools

Source: /docs/geshi-doc.txt - 1741 lines - 114453 bytes - Summary - Text - Print

   1  [NOTE: This documentation has simply been copy-pasted from the HTML form and is NOT up to date, I recommend you
   2  read that instead]
   3  
   4  GeSHi Documentation
   5  Version 1.0.7.22
   6  
   7  Author:          Nigel McNie, Benny Baumann
   8  Copyright:       © 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
   9  Email:           nigel@geshi.org, BenBE@omorphia.de
  10  GeSHi Website:   http://qbnz.com/highlighter
  11  
  12  This is the documentation for GeSHi - Generic Syntax Highlighter. The most modern version of this document is available on the web - go to http://qbnz.com/highlighter/documentation.php to view it.
  13  
  14  Any comments, questions, confusing points? Please contact me! I need all the information I can get to make the use of GeSHi and everything related to it (including this documentation) a breeze.
  15  Contents
  16  
  17      * 1. Introduction
  18            o 1.1 Features
  19            o 1.2 About GeSHi
  20            o 1.3 Credits
  21            o 1.4 Feedback
  22      * 2. The Basics
  23            o 2.1 Getting GeSHi
  24            o 2.2 Installing GeSHi
  25                  + 2.2.1 Requirements
  26                  + 2.2.2 Extracting GeSHi
  27                  + 2.2.3 Installation
  28            o 2.3 Basic Usage
  29      * 3. Advanced Features
  30            o 3.1 The Code Container
  31            o 3.2 Line Numbers
  32                  + 3.2.1 Enabling Line Numbers
  33                  + 3.2.2 Styling Line Numbers
  34                  + 3.2.3 Choosing a Start Number
  35            o 3.3 Using CSS Classes
  36                  + 3.3.1 Enabling CSS Classes
  37                  + 3.3.2 Setting the CSS Class/ID
  38                  + 3.3.3 Getting the Stylesheet
  39                  + 3.3.4 Using an External Stylesheet
  40            o 3.4 Changing Styles
  41                  + 3.4.1 The Overall Styles
  42                  + 3.4.2 Line Number Styles
  43                  + 3.4.3 Setting Keyword Styles
  44                  + 3.4.4 Setting Comment Styles
  45                  + 3.4.5 Setting Other Styles
  46            o 3.5 Case Sensitivity and Auto Casing
  47                  + 3.5.1 Auto Caps/Nocaps
  48                  + 3.5.2 Setting Case Sensitivity
  49            o 3.6 Changing the Source/Language/Path/Charset
  50                  + 3.6.1 Changing the Source Code
  51                  + 3.6.2 Changing the Language
  52                  + 3.6.3 Changing the Path
  53                  + 3.6.4 Changing the Character Set
  54                  + 3.6.5 Using load_from_file to change the language and source code
  55            o 3.7 Error Handling
  56            o 3.8 Disabling Styling of Some Lexics
  57            o 3.9 Setting the Tab Width
  58            o 3.10 Using Strict Mode
  59            o 3.11 Adding/Removing Keywords
  60                  + 3.11.1 Adding a Keyword
  61                  + 3.11.2 Removing a Keyword
  62                  + 3.11.3 Adding a Keyword Group
  63                  + 3.11.4 Removing a Keyword Group
  64            o 3.12 Headers and Footers for your code
  65                  + 3.12.1 Keyword Substitution
  66                  + 3.12.2 Setting Header Content
  67                  + 3.12.3 Setting Footer Content
  68                  + 3.12.4 Styling Header Content
  69                  + 3.12.5 Styling Footer Content
  70            o 3.13 Keyword URLs
  71                  + 3.13.1 Setting a URL for a Keyword Group
  72                  + 3.13.2 Disabling URLs for a Keyword Group
  73                  + 3.13.3 Disabling all URLs for Keywords
  74                  + 3.13.4 Styling Links
  75                  + 3.13.5 Setting the Link Target
  76            o 3.14 Using Contextual Importance
  77            o 3.15 Highlighting Special Lines "Extra"
  78                  + Specifying the Lines to Highlight Extra
  79                  + Styles for the Highlighted Lines
  80            o 3.16 Adding IDs to Each Line
  81            o 3.17 Getting the Time of Styling
  82      * 4 Language Files
  83            o 4.1 An Example Language File
  84            o 4.2 Language File Conventions
  85            o 4.3 Language File Sections
  86                  + 4.3.1 The Header
  87                  + 4.3.2 The First Indices
  88                  + 4.3.3 Keywords
  89                  + 4.3.4 Symbols and Case Sensitivity
  90                  + 4.3.5 Styles for your Language Files
  91                  + 4.3.6 URLs for Functions
  92                  + 4.3.7 Object Orientation Support
  93                  + 4.3.8 Using Regular Expressions
  94                  + 4.3.9 Contextual Highlighting and Strict Mode
  95                  + 4.3.10 Tidying Up
  96      * 5 Method/Constant Reference
  97  
  98  1: Introduction
  99  Top | Contents | Next | Previous
 100  
 101  GeSHi is exactly what the acronym stands for: a Generic Syntax Highlighter. As long as you have a language file for almost any computer language - whether it be a scripting language, object orientated, markup or anything in between - GeSHi can highlight it! GeSHi is extremely customisable - the same source can be highlighted multiple times in multiple ways - the same source even with a different language. GeSHi outputs XHTML strict compliant code*, and can make use of CSS to save on the amount of output. And what is the cost for all of this? You need PHP. That's all!
 102  
 103  *Most of the time. Some languages do not output XHTML strict code, and using line numbers with the PRE header is not legal either. These problems will be fixed in 1.2.
 104  1.1: Features
 105  Top | Contents | Next | Previous
 106  
 107  Here are some of the standout features of GeSHi:
 108  
 109      * Programmed in PHP: GeSHi is coded entirely in PHP. This means that where ever you have PHP, you can have GeSHi! Almost any free webhost supports PHP, and GeSHi works fine with PHP > 4.3.0*.
 110      * Support for many languages: GeSHi comes with about 100 languages, including PHP, HTML, CSS, Java, C, Lisp, XML, Perl, Python, ASM and many more!
 111      * XHTML compliant output: GeSHi produces XHTML compliant output, using stylesheets, so you need not worry about GeSHi ruining your claims to perfection in the standards department ;)
 112      * Highly customisable: GeSHi allows you to change the style of the output on the fly, use CSS classes or not, use an external stylesheet or not, use line numbering, change the case of output keywords... the list goes on and on!
 113      * Flexible: Unfortunately, GeSHi is quite load/time intensive for large blocks of code. However, you want speed? Turn off any features you don't like, pre-make a stylesheet and use CSS classes to reduce the amount of output and more - it's easy to strike a balance that suits you.
 114  
 115  This is just a taste of what you get with GeSHi - the best syntax highlighter for the web in the world!
 116  
 117  *Support is granted for PHP 4.3.0 and above, but especially 4.3.x cannot be guaranteed to work due to a lack of test systems. If you are forced to use such old PHP versions complain at your hoster or contact us if you find compatibility issues so we can try to resolve them. It's only PHP 4.4.X and above that is verified to work.
 118  1.2: About GeSHi
 119  Top | Contents | Next | Previous
 120  
 121  GeSHi started as a mod for the phpBB forum system, to enable highlighting of more languages than the available (which can be roughly estimated to exactly 0 ;)). However, it quickly spawned into an entire project on its own. But now it has been released, work continues on a mod for phpBB* - and hopefully for many forum systems, blogs and other web-based systems.
 122  
 123  *I am no longer working on this MOD, however if someone else wants to they can contact me for more information.
 124  
 125  Several systems are using GeSHi now, including:
 126  
 127      * Dokuwiki - An advanced wiki engine
 128      * gtk.php.net - Their manual uses GeSHi for syntax highlighting
 129      * WordPress - A powerful blogging system*
 130      * PHP-Fusion - A constantly evovling CMS
 131      * SQL Manager - A Postgres DBAL
 132      * Mambo - A popular open source CMS
 133      * MediaWiki - A leader in Wikis*
 134      * TikiWiki - A megapowerful Wiki/CMS
 135      * TikiPro - Another powerful Wiki based on Tikiwiki
 136      * RWeb - A site-building tool
 137  
 138  * Available as plugin only. In addition, some of the other entries mentioned here may only have GeSHi available as a plugin.
 139  
 140  GeSHi is the original work of Nigel McNie. The project was later handed over to Benny Baumann. Others have helped with aspects of GeSHi also, they're mentioned in the THANKS file.
 141  1.3: Credits
 142  Top | Contents | Next | Previous
 143  
 144  Many people have helped out with GeSHi, whether by creating language files, submitting bug reports, suggesting new ideas or simply pointing out a new idea or something I'd missed. All of these people have helped to build a better GeSHi, you can see them in the THANKS file.
 145  
 146  Do you want your name on this list? Why not make a language file, or submit a valid bug? Or perhaps help me with an added feature I can't get my head around, or suggest a new feature, or even port GeSHi to anothe language? There's lots you can do to help out, and I need it all :)
 147  1.4: Feedback
 148  Top | Contents | Next | Previous
 149  
 150  I need your feedback! ANYthing you have to say is fine, whether it be a query, congratulations, a bug report or complaint, I don't care! I want to make this software the best it can be, and I need your help! You can contact me in the following ways:
 151  
 152      * E-mail: nigel@geshi.org
 153      * Forums: Sourceforge.net Forums or GeSHi home forums
 154  
 155  Remember, any help I am grateful for :)
 156  2: The Basics
 157  Top | Contents | Next | Previous
 158  
 159  In this section, you'll learn a bit about GeSHi, how it works and what it uses, how to install it and how to use it to perform basic highlighting.
 160  2.1: Getting GeSHi
 161  Top | Contents | Next | Previous
 162  
 163  If you're reading this and don't have GeSHi, that's a problem ;). So, how do you get your hands on it? Visit http://qbnz.com/highlighter/downloads.php to obtain the latest version.
 164  2.2: Installing GeSHi
 165  Top | Contents | Next | Previous
 166  
 167  Installing GeSHi is a snap, even for those most new to PHP. There's no tricks involved. Honest!
 168  2.2.1: Requirements
 169  Top | Contents | Next | Previous
 170  
 171  GeSHi requires the following to be installable:
 172  
 173      * PHP. It's untested with anything other below 4.4.X. I hope to extend this range soon. I see no reason why it won't work with any version of PHP above 4.3.0.
 174      * Approximately 2 megabytes of space. The actual script is small - around 150K - but most of the size comes from the large number of language files (over 100!). If you're pushed for space, make sure you don't upload to your server the docs/ or contrib/ directory, and you may want to leave out any language files that don't take your fancy either.
 175  
 176  As you can see, the requirements are very small. If GeSHi does NOT work for you in a particular version of PHP, let me know why and I'll fix it.
 177  
 178  Packages come in .zip, .tar.gz and .tar.bz2 format, so there's no complaining about whether it's available for you. *nix users probably want .tar.gz or .tar.bz2 and windows users probably want .zip.
 179  2.2.2: Extracting GeSHi
 180  Top | Contents | Next | Previous
 181  
 182  To extract GeSHi in Linux (.tar.gz):
 183  
 184     1. Open a shell
 185     2. cd to the directory where the archive lies
 186     3. Type tar -xzvf [filename] where [filename] is the name of the archive (typically GeSHi-1.X.X.tar.gz)
 187     4. GeSHi will be extracted to its own directory
 188  
 189  To extract GeSHi in Windows (.zip):
 190  
 191     1. Open Explorer
 192     2. Navigate to the directory where the archive lies
 193     3. Extract the archive. The method you use will depend on your configuration. Some people can right-click upon the archive and select "Extract" from there, others may have to drag the archive and drop it upon an extraction program.
 194  
 195  To extract from .zip you'll need an unzipping program - unzip in Linux, or Winzip, Winrar or similar for Windows.
 196  2.2.3: Installation
 197  Top | Contents | Next | Previous
 198  
 199  GeSHi is nothing more than a PHP class with related language support files. Those of you familiar with PHP can then guess how easy the installation will be: simply copy it into your include path somewhere. You can put it wherever you like in this include path. I recommend that you put the language files in a subdirectory of your include path too - perhaps the same subdirectory that geshi.php is in. Remember this path for later.
 200  
 201  If you don't know what an include path is, don't worry. Simply copy GeSHi to your webserver. So for example, say your site is at http://mysite.com/myfolder, you can copy GeSHi to your site so the directory structure is like this:
 202  
 203  http://mysite.com/myfolder/geshi/[language files]
 204  http://mysite.com/myfolder/geshi.php
 205  
 206  Or you can put it in any subdirectory you like:
 207  
 208  http://mysite.com/myfolder/includes/geshi/[language files]
 209  http://mysite.com/myfolder/includes/geshi.php
 210  
 211  Caution:
 212  
 213  When using GeSHi on a live site, the only directory required is the geshi/ subdirectory. Both contrib/ and docs/ are worthless, and furthermore, as some people discovered, one of the files in contrib had a security hole (fixed as of 1.0.7.3). I suggest you delete these directories from any live site they are on.
 214  2.3: Basic Usage
 215  Top | Contents | Next | Previous
 216  
 217  Use of GeSHi is very easy. Here's a simple example:
 218  //
 219  // Include the GeSHi library
 220  //
 221  include_once ('geshi.php');
 222  
 223  //
 224  // Define some source to highlight, a language to use
 225  // and the path to the language files
 226  //
 227  $source = '$foo = 45;
 228  for ( $i = 1; $i < $foo; $i++ )
 229  {
 230    echo "$foo<br />\n";
 231    --$foo;
 232  }';
 233  $language = 'php';
 234  //
 235  // Create a GeSHi object
 236  //
 237  $geshi =& new GeSHi($source, $language);
 238  
 239  //
 240  // And echo the result!
 241  //
 242  echo $geshi->parse_code();
 243  
 244  As you can see, there's only three really important lines:
 245  include_once ('geshi.php');
 246  
 247  This line includes the GeSHi class for use
 248  $geshi = new GeSHi($source, $language);
 249  
 250  This line creates a new GeSHi object, holding the source and the language you want to use for highlighting.
 251  echo $geshi->parse_code();
 252  
 253  This line spits out the result :)
 254  
 255  So as you can see, simple usage of GeSHi is really easy. Just create a new GeSHi object and get the code!
 256  
 257  Since version 1.0.2, there is a function included with GeSHi called geshi_highlight. This behaves exactly as the php function highlight_string behaves - all you do is pass it the language you want to use to highlight and the path to the language files as well as the source. Here are some examples:
 258  // Simply echo the highlighted code
 259  geshi_highlight($source, 'php', $path);
 260  
 261  // Get the code back, for use later
 262  $code = geshi_highlight($source, 'java', $path, true)
 263  
 264  // Check if there is an error with parsing this code
 265  ob_start();
 266  $result = geshi_highlight($source, 'perl', $path);
 267  $code = ob_get_contents();
 268  ob_end_clean();
 269  if ( !$result )
 270  {
 271          // There was an error with highlighting...
 272  }
 273  else
 274  {
 275          // All OK :)
 276  }
 277  
 278  However, these are really simple examples and doesn't even begin to cover all the advanced features of GeSHi. If you want to learn more, continue on to section 3: Advanced Features.
 279  3: Advanced Features
 280  Top | Contents | Next | Previous
 281  
 282  This section documents the advanced features of GeSHi - strict mode, using CSS classes, changing styles on the fly, disabling highlighting of some things and more.
 283  
 284  In this section there are many code snippets. For all of these, you should assume that the GeSHi library has been included, and a GeSHi object has been created and is referenced by the variable $geshi. Normally, the source, language and path used are arbitary.
 285  3.1 The Code Container
 286  Top | Contents | Next | Previous
 287  
 288  The Code Container has a fundamental effect on the layout of your code before you even begin to style. What is the Code Container? It's the bit of markup that goes around your code to contain it. By default your code is surrounded by a <pre>, but you can also specify a <div>.
 289  
 290  The <pre> header is the default. If you're familiar with HTML you'll know that whitespace is rendered "as is" by a <pre> element. The advantage for you is that if you use <pre> the whitespace you use will appear pretty much exactly how it is in the source, and what's more GeSHi won't have to add a whole lot of <br />'s and non-breaking spaces (&nbsp;) to your code to indent it. This saves you source code (and your valuable visitors waiting time and your bandwidth).
 291  
 292  But if you don't like <pre> or it looks stupid in your browser no matter what styles you try to apply to it or something similar, you might want to use a <div> instead. A <div> will result in more source - GeSHi will have to insert whitespace markup - but in return you can wrap long lines of code that would otherwise have your browser's horizontal scrollbar appear. Of course with <div> you can *not* wrap lines if you please. The highlighter demo at the GeSHi home page uses the <div> approach for this reason.
 293  
 294  At this stage there isn't an option to wrap the code in <code> tags (unless you use the function geshi_highlight), partly because of the inconsistent and unexpected ways stuff in <code> tags is highlighted. Besides, <code> is an inline element. But this may become an option in future versions.
 295  
 296  As of GeSHi 1.0.7.2 there is a new header type, that specifies that the code should not be wrapped in anything at all.
 297  
 298  Another requested addition has been made in GeSHi 1.0.7.20 to force GeSHi to create a block around the highlighted source even if this wasn't necessary, thus styles that are applied to the output of GeSHi can directly influence the code only even if headers and footers are present.
 299  
 300  To change/set the header to use, you call the set_header_type() method:
 301  $geshi->set_header_type(GESHI_HEADER_DIV);
 302  // or...
 303  $geshi->set_header_type(GESHI_HEADER_PRE); // or...
 304  $geshi->set_header_type(GESHI_HEADER_NONE);
 305  
 306  Those are the only three arguments you should pass to set_header_type. Passing anything else may cause inconsistencies in what is used as the Code Container (although it *should* simply use a <pre>). Better not to risk it.
 307  Note:
 308  
 309  GESHI_HEADER_DIV, GESHI_HEADER_PRE and GESHI_HEADER_NONE are constants, so don't put them in strings!
 310  Caution:
 311  
 312  The default styles for the <pre> and <div> will be different, especially if you use line numbers!. I have found that a <pre> results in code that is smaller than for that of a <div>, you should rectify this difference by using set_overall_style() if you need to. But be aware of this difference for if you are changing the header type!
 313  3.2: Line Numbers
 314  Top | Contents | Next | Previous
 315  
 316  GeSHi has the ability to add line numbers to your code (see the demo available at http://qbnz.com/highlighter/demo.php to see what can be achieved). Line numbers are a great way to make your code look professional, especially if you use the fancy line numbers feature.
 317  3.2.1: Enabling Line Numbers
 318  Top | Contents | Next | Previous
 319  
 320  To highlight a source with line numbers, you call the enable_line_numbers() method:
 321  $geshi->enable_line_numbers($flag);
 322  
 323  Where $flag is one of the following:
 324  
 325      * GESHI_NORMAL_LINE_NUMBERS - Use normal line numbering
 326      * GESHI_FANCY_LINE_NUMBERS - Use fancy line numbering
 327      * GESHI_NO_LINE_NUMBERS - Disable line numbers (default)
 328  
 329  Normal line numbers means you specify a style for them, and that style gets applied to all of them. Fancy line numbers means that you can specify a different style for each nth line number. You change the value of n (default 5):
 330  $geshi->enable_line_numbers(GESHI_FANCY_LINE_NUMBERS, 37);
 331  
 332  The second parameter is not used in any other mode. Setting it to 0 is the same as simply using normal line numbers. Setting it to 1 applies the fancy style to every line number.
 333  Note:
 334  
 335  The values above are CONSTANTS - so don't put them in strings!
 336  3.2.2 Styling Line Numbers
 337  Top | Contents | Next | Previous
 338  
 339  As of GeSHi 1.0.2, line numbers are added by the use of ordered lists. This solves the old issues of line number styles inheriting from styles meant for the code. Also, this solves an important issue about selecting code. For example, line numbers look nice, but when you go to select the code in your browser to copy it? You got the line numbers too! Not such a good thing, but thankfully this issue is now solved. What is the price? Unfortunately the whole way that styles are inherited/used has changed for those of you who were familiar with 1.0.1, and there is quite a bit more HTML involved. So think carefully about these things before you enable line numbers.
 340  
 341  Now, onto how to style line numbers:
 342  
 343  Styles are set for line numbers using the set_line_style() method:
 344  $geshi->set_line_style('background: #fcfcfc;');
 345  
 346  If you're using Fancy Line Numbers mode, you pass a second string for the style of the nth line number:
 347  $geshi->set_line_style('background: #fcfcfc;', 'background: #f0f0f0;');
 348  
 349  The second style will have no effect if you're not using Fancy Line Numbers mode.
 350  
 351  By default, the styles you pass overwrite the current styles. Add a boolean "true" after the styles you specify to combine them with the current styles:
 352  $geshi->set_line_style('background: red;', true);
 353  // or, for fancy line numbers
 354  $geshi->set_line_style('background: red;', 'background: blue;', true);
 355  Note:
 356  
 357  Due to a bug with Firefox the issue that should have been fixed with 1.0.2 has reappeared in another form as Firefox includes extra text\markup into plaintext versions of webpage copies. This can sometimes be useful (actually it's used to get the plaintext version of this documentation), but more often is quite annoying. Best practice so far is to either not use line numbers, or offer the visitor of your page a plaintext version of your source. To learn more have a look at the SF.net BugTracker Issue #1651996. This will hopefully be fixed in GeSHi version 1.2 or as soon as Firefox provides webdevelopers with adequate ways to control this feature - whichever comes first!
 358  Caution:
 359  
 360  When you set line number styles, the code will inherit those styles! This is the main issue to come out of the 1.0.2 release. If you want your code to be styled in a predictable manner, you'll have to call the set_code_style() method to rectify this problem.
 361  
 362  Note also that you cannot apply background colours to line numbers unless you use set_overall_style(). Here's how you'd style:
 363  
 364     1. Use set_overall_style() to style the overall code block. For example, you can set the border style/colour, any margins and padding etc. using this method. In addition: set the background colour for all the line numbers using this method.
 365     2. Use set_line_style() to style the foreground of the line numbers. For example, you can set the colour, weight, font, padding etc. of the line numbers using this method.
 366     3. Use set_code_style() to explicitly override the styles you set for line numbers using set_line_style. For example, if you'd set the line numbers to be bold (or even if you'd only set the fancy line number style to be bold), and you didn't actually want your code to be bold, you'd make sure that font-weight: normal; was in the stylesheet rule you passed to set_code_style
 367  
 368  This is the one major change from GeSHi 1.0.1 - make sure you become familiar with this, and make sure that you check any code you have already styled with 1.0.1 when you upgrade to make sure nothing bad happens to it.
 369  3.2.3: Choosing a Start Number
 370  Top | Contents | Next | Previous
 371  
 372  As of GeSHi 1.0.2, you can now make the line numbers start at any number, rather than just 1. This feature is useful if you're highlighting code from a file from around a certain line number in that file, as an additional guide to those who will view the code. You set the line numbers by calling the start_line_numbers_at() method:
 373  $geshi->start_line_numbers_at($number);
 374  
 375  $number must be a positive integer (or zero). If it is not, GeSHi will convert it anyway.
 376  
 377  If you have not enabled line numbers, this will have no effect.
 378  Caution:
 379  
 380  Although I'd like GeSHi to have XHTML strict compliance, this feature will break compliancy (however transitional compliancy remains). This is because the only widely supported way to change the start value for line numbers is by using the start="number" attribute of the <ol> tag. Although CSS does provide a mechanism for doing this, it is only supported in Opera versions 7.5 and above (not even Firefox supports this).
 381  3.3: Using CSS Classes
 382  Top | Contents | Next | Previous
 383  
 384  Using CSS to highlight your code instead of in-lining the styles is a definate bonus. Not only is it more compliant (the w3c is deprecating the style attribute in XHTML 2.0) but it results in far less outputted code - up to a whopping 90% saving - which makes a *huge* difference to those unlucky of us on modems!
 385  3.3.1: Enabling CSS Classes
 386  Top | Contents | Next | Previous
 387  
 388  By default, GeSHi doesn't use the classes, so it's easy just to whack out some highlighted code if you need without worrying about stylesheets. However, if you're a bit more organised about it, you should use the classes ;). To turn the use of classes on, you call the enable_classes() method:
 389  $geshi->enable_classes();
 390  
 391  If you want to turn classes OFF for some reason later:
 392  $geshi->enable_classes(false);
 393  
 394  If classes are enabled when parse_code() is called, then the resultant source will use CSS classes in the output, otherwise it will in-line the styles. The advantages of using classes are great - the reduction in source will be very noticeable, and what's more you can use one stylesheet for several different highlights on the same page. In fact, you can even use an external stylesheet and link to that, saving even more time and source (because stylesheets are cached by browsers).
 395  Note:
 396  
 397  There have been problems with inline styles and the Symbol Highlighting added in 1.0.7.21. If you can you should therefore turn CSS classes ON to avoid those issues.
 398  Caution:
 399  
 400  This should be the very first method you call after creating a new GeSHi object! That way, various other methods can act upon your choice to use classes correctly. In theory, you could call this method just before parsing the code, but this may result in unexpected behaviour.
 401  3.3.2: Setting the CSS class and ID
 402  Top | Contents | Next | Previous
 403  
 404  You can set an overall CSS class and id for the code. This is a good feature that allows you to use the same stylesheet for many different snippets of code. You call set_overall_class() and set_overall_id to accomplish this:
 405  $geshi->set_overall_class('mycode');
 406  $geshi->set_overall_id('dk48ck');
 407  
 408  The default classname is the name of the language being used. This means you can use just the one stylesheet for all sources that use the same language, and incidentally means that you probably won't have to call these methods too often.
 409  
 410  CSS IDs are supposed to be unique, and you should use them as such. Basically, you can specify an ID for your code and then use that ID to highlight that code in a unique way. You'd do this for a block of code that you expressly wanted to be highlighted in a different way (see the section below on gettting the stylesheet for your code for an example).
 411  3.3.3: Getting the stylesheet for your code
 412  Top | Contents | Next | Previous
 413  
 414  The other half of using CSS classes is getting the stylesheet for use with the classes. GeSHi makes it very easy to get a stylesheet for your code, with one easy method call:
 415  $geshi->enable_classes();
 416  
 417  // Here we have code that will spit out a header for
 418  // a stylesheet. For example:
 419  
 420  echo '<html>
 421  <head><title>Code</title>
 422  <style type="text/css">
 423  <!--';
 424  
 425  // Echo out the stylesheet for this code block
 426  
 427  echo $geshi->get_stylesheet();
 428  
 429  // And continue echoing the page
 430  
 431  echo '-->
 432  </style></head>
 433  <body>';
 434  
 435  The get_stylesheet() method gets the stylesheet for your code in one easy call. All you need to do is output it in the correct place. As you can also see, you don't even have to enable class usage to get the stylesheet nessecary either - however not enabling classes but using the stylesheet may result in problems later.
 436  
 437  By default, get_stylesheet() tries to echo the least amount of code possible. Although currently it doesn't check to see if a certain lexic is even in the source, you can expect this feature in the future. At least for the present however, if you explicitly disable the highlighting of a certain lexic, or disable line numbers, the related CSS will not be outputted. This may be a bad thing for you perhaps you're going to use the stylesheet for many blocks of code, some with line numbers, others with some lexic enabled where this source has it disabled. Or perhaps you're building an external stylesheet and want all lexics included. So to get around this problem, you do this:
 438  $geshi->get_stylesheet(false);
 439  
 440  This turns economy mode off, and all of the stylesheet will be outputted regardless.
 441  
 442  Now lets say you have several snippets of code, using the same language. In most of them you don't mind if they're highlighted the same way (in fact, that's exactly what you want) but in one of them you'd like the source to be highlighted differently. Here's how you can do that:
 443  // assume path is the default "geshi/" relative to the current directory
 444  $geshi1 = new GeSHi($source1, $lang);
 445  $geshi2 = new GeSHi($source2, $lang);
 446  $geshi3 = new GeSHi($source3, $lang);
 447  
 448  // Turn classes on for all sources
 449  $geshi1->enable_classes();
 450  $geshi2->enable_classes();
 451  $geshi3->enable_classes();
 452  
 453  // Make $geshi3 unique
 454  $geshi3->set_overall_id('different');
 455  
 456  //
 457  // Methods are called on $geshi3 to change styles...
 458  //
 459  
 460  echo '<html>
 461  <head><title>Code</title>
 462  <style type="text/css">
 463  <!--
 464  ';
 465  
 466  // Get the nessecary stylesheets
 467  echo $geshi1->get_stylesheet();
 468  echo $geshi3->get_stylesheet();
 469  
 470  echo '-->
 471  </style></head>
 472  <body>';
 473  
 474  
 475  echo 'Code snippet 1:';
 476  echo $geshi1->parse_code();
 477  echo 'Code snippet 2 (same highlighting as 1):';
 478  echo $geshi2->parse_code();
 479  echo 'Code snippet 3 (DIFFERENT highlighting):';
 480  echo $geshi3->parse_code();
 481  
 482  echo '</body></html>';
 483  
 484  Before version 1.0.2, you needed to set the class of the code you wanted to be unique to the empty string. This limitation has been removed in version 1.0.2 - if you set the ID of a block of code, all styling will be done based on that ID alone.
 485  3.3.4: Using an External Stylesheet
 486  Top | Contents | Next | Previous
 487  
 488  An external stylesheet can reduce even more the amount of code needed to highlight some source. However there are some drawbacks with this. To use an external stylesheet, it's up to you to link it in to your document, normally with the following HTML:
 489  <html>
 490  <head>
 491  <link rel="stylesheet" type="text/css" href="url_to_stylesheet.css" />
 492  
 493  In your external stylesheet you put CSS declarations for your code. Then just make sure you're using the correct class (use set_overall_class() to ensure this) and this should work fine.
 494  
 495  This method is great if you don't mind the source always being highlighted the same (in particular, if you're making a plugin for a forum/wiki/other system, using an external stylesheet is a good idea!). It saves a small amount of code and your bandwidth, and it's relatively easy to just change the stylesheet should you need to. However, using this will render the methods that change the styles of the code useless, because of course the stylesheet is no longer being dynamically generated. You can still disable highlighting of certain lexics dynamically, however.
 496  Note:
 497  
 498  As of version 1.0.2, GeSHi comes with a contrib/ directory, which in it contains a "wizard" script for creating a stylesheet. Although this script is by no means a complete solution, it will create the necessary rules for the basic lexics - comments, strings for example. Things not included in the wizard include regular expressions for any language that uses them (PHP and XML are two languages that use them), and keyword-link styles. However, this script should take some of the tedium out of the job of making an external stylesheet. Expect a much better version of this script in version 1.2!
 499  3.4: Changing Styles
 500  Top | Contents | Next | Previous
 501  
 502  One of the more powerful features of GeSHi is the ability to change the style of the output dynamically. Why be chained to the boring styles the language authors make up? You can change almost every single aspect of highlighted code - and can even say whether something is to be highlighted at all.
 503  
 504  If you're confused about "styles", you probably want to have a quick tutorial in them so you know what you can do with them. Checkout the homepage of CSS at http://www.w3.org/Style/CSS.
 505  3.4.1: The Overall Styles
 506  Top | Contents | Next | Previous
 507  
 508  The code outputted by GeSHi is either in a <div> or a <pre> (see the section entitled "The Code Container"), and this can be styled.
 509  $geshi->set_overall_style('... styles ...');
 510  
 511  Where styles is a string containing valid CSS declarations. By default, these styles overwrite the current styles, but you can change this by adding a second parameter:
 512  $geshi->set_overall_style('color: blue;', true);
 513  
 514  The default styles "shine through" wherever anything isn't highlighted. Also, you can apply more advanced styles, like position: (fixed|relative) etc, because a <div>/<pre> is a block level element.
 515  Note:
 516  
 517  Remember that a <div> will by default have a larger font size than a <pre>, as discussed in the section "The Code Container".
 518  3.4.2: Line Number Styles
 519  Top | Contents | Next | Previous
 520  
 521  You may wish to refer to the section Styling Line Numbers before reading this section.
 522  
 523  As of version 1.0.2, the way line numbers are generated is different, so therefore the way that they are styled is different. In particular, now you cannot set the background style of the fancy line numbers to be different from that of the normal line numbers.
 524  
 525  Line number styles are set by using the method set_line_style:
 526  $geshi->set_line_style($style1, $style2);
 527  
 528  $style1 is the style of the line numbers by default, and $style2 is the style of the fancy line numbers.
 529  Caution:
 530  
 531  Things have changed since 1.0.1! This note is very important - please make sure you check this twice before complaining about line numbers!
 532  
 533  Because of the way that ordered lists are done in HTML, there really isn't normally a way to style the actual numbers in the list. I've cheated somewhat with GeSHi - I've made it possible to use CSS to style the foreground of the line numbers. So therefore, you can change the color, font size and type, and padding on them. If you want to have a pretty background, you must use set_overall_style() to do this, and use set_code_style() to style the actual code! This is explained in the section above: Styling Line Numbers.
 534  
 535  In addition, the styles for fancy line numbers is now the difference between the normal styles and the styles you want to achieve. For example, in GeSHi prior to 1.0.2 you may have done this to style line numbers:
 536  $geshi->set_line_style('color: red; font-weight: bold;', 'color: green; font-weight: bold');
 537  
 538  Now you instead can do this:
 539  $geshi->set_line_style('color: red; font-weight: bold;', 'color: green;');
 540  
 541  The font-weight: bold; will automatically carry through to the fancy styles. This is actually a small saving in code - but the difference may be confusing for anyone using 1.0.1 at first.
 542  3.4.3: Setting Keyword Styles
 543  Top | Contents | Next | Previous
 544  
 545  Perhaps the most regular change you will make will be to the styles of a keyword set. In order to change the styles for a particular set, you'll have to know what the set is called first. Sets are numbered from 1 up. Typically, set 1 contains keywords like if, while, do, for, switch etc, set 2 contains null, false, true etc, set 3 contains function inbuilt into the language (echo, htmlspecialchars etc. in PHP) and set 4 contains data types and similar variable modifiers: int, double, real, static etc. However these things are not fixed, and you should check the language file to see what key you want. Having a familiarity with a language file is definately a plus for using it.
 546  
 547  To change the styles for a keyword set, call the set_keyword_group_style() method:
 548  $geshi->set_keyword_group_style($group, $styles);
 549  
 550  Where $group is the group to change the styles for and $styles is a string containing the styles to apply to that group.
 551  
 552  By default, the styles you pass overwrite the current styles. Add a boolean true after the styles you specify to combine them with the current styles:
 553  $geshi->set_keyword_group_style(3, 'color: white;', true);
 554  3.4.4: Setting Comment Styles
 555  Top | Contents | Next | Previous
 556  
 557  To change the styles for a comment group, call the set_comments_style() method:
 558  $geshi->set_comments_style($group, $styles);
 559  
 560  Where $group is either a number corresponding to a single-line comment, or the string 'MULTI' to specify multiline comments:
 561  $geshi->set_comments_style(1, 'font-style: italic;');
 562  $geshi->set_comments_style('MULTI', 'display: hidden;');
 563  
 564  By default, the styles you pass overwrite the current styles. Add a boolean true after the styles you specify to combine them with the current styles:
 565  $geshi->set_comments_style(1, 'font-weight: 100;', true);
 566  Note:
 567  
 568  In 1.0.7.22 a new kind of Comments called "COMMENT_REGEXP" has been added. Those are handled by setting single line comment styles.
 569  3.4.5: Setting Other Styles
 570  Top | Contents | Next | Previous
 571  
 572  GeSHi can highlight many other aspects of your source other than just keywords and comments. Strings, Numbers, Methods and Brackets among other things can all also be highlighted. Here are the related methods:
 573  $geshi->set_escape_characters_style($styles[, $preserve_defaults]);
 574  $geshi->set_symbols_style($styles[, $preserve_defaults]);
 575  $geshi->set_strings_style($styles[, $preserve_defaults]);
 576  $geshi->set_numbers_style($styles[, $preserve_defaults]);
 577  $geshi->set_methods_style($key, $styles[, $preserve_defaults]);
 578  $geshi->set_regexps_style($key, $styles[, $preserve_defaults]);
 579  
 580  $styles is a string containing valid stylesheet declarations, while $preserve_defaults should be set to true if you want your styles to be merged with the previous styles. In the case of set_methods_style, you should select a group to set the styles of, check the language files for the number used for each "object splitter".
 581  
 582  Like this was possible for set_method_style a new parameter has been introduced for set_symbols_style too which allows you to select the group of symbols for which you'd like to change your style. $geshi->set_symbols_style($styles[, $preserve_defaults[, $group]]);
 583  If the third parameter is not given, group 0 is assumed. Furthermore you should note that any changes to group 0 are also reflected in the bracket style, i.e. a pass-through call to set_bracket_style is made.
 584  3.5: Case Sensitivity and Auto Casing
 585  Top | Contents | Next | Previous
 586  
 587  Controlling the case of the outputted source is an easy job with GeSHi. You can control which keywords are converted in case, and also control whether keywords are checked in a case sensitive manner.
 588  3.5.1: Auto-Caps/Nocaps
 589  Top | Contents | Next | Previous
 590  
 591  Auto-Caps/Nocaps is a nifty little feature that capitalises or lowercases automatically certain lexics when they are styled. I dabble in QuickBASIC, a dialect of BASIC which is well known for it's capatalisation, and SQL is another language well known for using caps for readability.
 592  
 593  To change what case lexics are rendered in, you call the set_case_keywords() method:
 594  $geshi->set_case_keywords($caps_modifier);
 595  
 596  The valid values to pass to this method are:
 597  
 598      * GESHI_CAPS_NO_CHANGE - Don't change the case of any lexics, leave as they are found
 599      * GESHI_CAPS_UPPER - Uppercase all lexics found
 600      * GESHI_CAPS_LOWER - Lowercase all lexics found
 601  
 602  Caution:
 603  
 604  When I say "lexic", I mean "keywords". Any keyword in any keyword array will be modified using this option! This is one small area of inflexibility I hope to fix in 1.2.X.
 605  
 606  I suspect this will only be used to specify GESHI_CAPS_NO_CHANGE to turn off autocaps for languages like SQL and BASIC variants, like so:
 607  $geshi = new GeSHi($source, 'sql');
 608  $geshi->set_case_keywords(GESHI_CAPS_NO_CHANGE); // don't want keywords capatalised
 609  
 610  All the same, it can be used for some interesting effects:
 611  $geshi = new GeSHi($source, 'java');
 612  // Anyone who's used java knows how picky it is about CapitalLetters...
 613  $geshi->set_case_keywords(GESHI_CAPS_LOWER);
 614  // No *way* the source will look right now ;)
 615  3.5.2: Setting Case Sensitivity
 616  Top | Contents | Next | Previous
 617  
 618  Some languages, like PHP, don't mind what case function names and keywords are in, while others, like Java, depend on such pickiness to maintain their bad reputations ;). In any event, you can use the set_case_sensitivity to change the case sensitiveness of a particular keyword group from the default:
 619  $geshi->set_case_sensitivity($key, $sensitivity);
 620  
 621  Where $key is the key of the group for which you wish to change case sensitivness for (see the language file for that language), and $sensitivity is a boolean value - true if the keyword is case sensitive, and false if not.
 622  3.6: Changing the Source, Language, Config Options
 623  Top | Contents | Next | Previous
 624  
 625  What happens if you want to change the source to be highlighted on the fly, or the language. Or if you want to specify any of those basic fields after you've created a GeSHi object? Well, that's where these methods come in.
 626  3.6.1: Changing the Source Code
 627  Top | Contents | Next | Previous
 628  
 629  To change the source code, you call the set_source() method:
 630  $geshi->set_source($newsource);
 631  
 632  Example:
 633  $geshi = new GeSHi($source1, 'php');
 634  
 635  // Method calls to specify various options...
 636  
 637  $code1 = $geshi->parse_code();
 638  
 639  $geshi->set_source($source2);
 640  $code2 = $geshi->parse_code();
 641  3.6.2: Changing the Language
 642  Top | Contents | Next | Previous
 643  
 644  What happens if you want to change the language used for highlighting? Just call set_language():
 645  $geshi->set_language('newlanguage');
 646  
 647  Example:
 648  $geshi = new GeSHi($source, 'php');
 649  
 650  $code = $geshi->parse_code();
 651  
 652  // Highlight GeSHi's output
 653  $geshi->set_source($code);
 654  $geshi->set_language('html4strict');
 655  $geshi->enable_classes(false);
 656  echo $geshi->parse_code();
 657  Note:
 658  
 659  Names are case-insensitive - they will be converted to lower case to match a language file however. So if you're making a language file, remember it should have a name in lower case.
 660  Note:
 661  
 662  What you pass to this method is the name of a language file, minus the .php extension. If you're writing a plugin for a particular application, it's up to you to somehow convert user input into a valid language name.
 663  Caution:
 664  
 665  GeSHi include()s the language file, so be careful to make sure that users can't pass some wierd language name to include any old script! GeSHi tries to strip non-valid characters out of a language name, but you should always do this your self anyway. In particular, language files are always lower-case, with either alphanumeric characters, dashes or underscores in their name.
 666  
 667  At the very least, strip "/" characters out of a language name.
 668  3.6.3: Changing the Language Path
 669  Top | Contents | Next | Previous
 670  
 671  What happens if all of a sudden you want to use language files from a different directory from the current language file location? You call the set_language_path() method:
 672  $geshi->set_language_path($newpath);
 673  
 674  It doesn't matter whether the path has a trailing slash after it or not - only that it points to a valid folder. If it doesn't, that's your tough luck ;)
 675  3.6.4: Changing the Character Set
 676  Top | Contents | Next | Previous
 677  Note:
 678  
 679  As of GeSHi 1.0.7.18, you don't need to use this, as htmlspecialchars is not being used due to a security flaw in it (that is unpatched in even the most recent PHP4 versions, and in PHP5 < 5.2). As long as you set the encoding properly with a php header() call, your foreign characters will be displayed correctly.
 680  
 681  As of version 1.0.3, you can use the method set_encoding to specify the character set that your source is in. Valid names are those names that are valid for the PHP function htmlentities():
 682  $geshi->set_encoding($encoding);
 683  
 684  There is a table of valid strings for $encoding at the php.net manual linked to above. If you do not specify an encoding, or specify an invalid encoding, the character set used is ISO-8859-1.
 685  Using load_from_file to Change the Language and Source Code
 686  Top | Contents | Next | Previous
 687  
 688  As of GeSHi 1.0.5, you can use the method load_from_file to load the source code and language from a file. Simply pass this method a file name and it will attempt to load the source and set the language.
 689  $geshi->load_from_file($file_name, $lookup);
 690  
 691  $file_name is the file name to use, and $lookup is an optional parameter that contains a lookup array to use for deciding which language to choose. You can use this to override GeSHi's default lookup array, which may not contain the extension of the file you're after, or perhaps does have your extension but under a different language. The lookup array is of the form:
 692  
 693  array(
 694       *   'lang_name' => array('extension', 'extension', ...),
 695       *   'lang_name' ...
 696       * );
 697  
 698  Also, you can use the method get_language_name_from_extension if you need to convert a file extension to a valid language name. This method will return the empty string if it could not find a match in the lookup, and like load_from_file it accepts an optional second parameter that contains a lookup array.
 699  3.7: Error Handling
 700  Top | Contents | Next | Previous
 701  
 702  What happens if you try to highlight using a language that doesn't exist? Or if GeSHi can't read a required file? The results you get may be confusing. You may check your code over and over, and never find anything wrong. GeSHi provides ways of finding out if GeSHi itself found anything wrong with what you tried to do. After highlighting, you can call the error() method:
 703  $geshi = new GeSHi('hi', 'thisLangIsNotSupported');
 704  
 705  echo $geshi->error();  // echoes error message
 706  
 707  The error message you will get will look like this:
 708  
 709      GeSHi Error: GeSHi could not find the language thisLangIsNotSupported (using path geshi/) (code 2)
 710  
 711  The error outputted will be the last error GeSHi came across, just like how mysql_error() works.
 712  3.8: Disabling styling of some Lexics
 713  Top | Contents | Next | Previous
 714  
 715  One disadvantage of GeSHi is that for large source files using complex languages, it can be quite slow with every option turned on. Although future releases will concentrate on the speed/resource side of highlighting, for now you can gain speed increases by disabling some of the highlighting options. This is done by using a series of set_*_highlighting methods:
 716  
 717      * set_keyword_group_highlighting($group, $flag): Sets whether a particular $group of keywords is to be highlighted or not. Consult the necessary language file(s) to see what $group should be for each group (typically a positive integer). $flag is false if you want to disable highlighting of this group, and true if you want to re-enable higlighting of this group. If you disable a keyword group then even if the keyword group has a related URL one will not be generated for that keyword.
 718      * set_comments_highlighting($group, $flag): Sets whether a particular $group of comments is to be highlighted or not. Consult the necessary language file(s) to see what $group should be for each group (typically a positive integer, or the string 'MULTI' for multiline comments. $flag is false if you want to disable highlighting of this group, and true if you want to re-enable highlighting of this group.
 719      * set_regexps_highlighting($regexp, $flag): Sets whether a particular $regexp is to be highlighted or not. Consult the necessary language file(s) to see what $regexp should be for each regexp (typically a positive integer, or the string 'MULTI' for multiline comments. $flag is false if you want to disable highlighting of this group, and true if you want to re-enable highlighting of this group.
 720      * The following methods:
 721            o set_escape_characters_highlighting($flag)
 722            o set_symbols_highlighting($flag)
 723            o set_strings_highlighting($flag)
 724            o set_numbers_highlighting($flag)
 725            o set_methods_highlighting($flag)
 726        Work on their respective lexics (e.g. set_methods_highlighting will disable/enable highlighting of methods). For each method, if $flag is false then the related lexics will not be highlighted at all (this means no HTML will surround the lexic like usual, saving on time and bandwidth.
 727  
 728  In case all highlighting should be disabled or reenabled GeSHi provides two methods called disable_highlighting() and enable_highlighting($flag). The optional paramter $flag has been added in 1.0.7.21 and specifies the desired state, i.e. true (default) to turn all highlighting on, or false to turn all highlighting off. Since 1.0.7.21 the method disnable_highlighting() has become deprecated.
 729  3.9: Setting the Tab Width
 730  Top | Contents | Next | Previous
 731  
 732  If you're using the <pre> header, tabs are handled automatically by your browser, and in general you can count on good results. However, if you're using the <div> header, you may want to specify a tab width explicitly.
 733  
 734  Note that tabs created in this fashion won't be like normal tabs - there won't be "tab-stops" as such, instead tabs will be replaced with the specified number of spaces.
 735  
 736  To change the tab width, you call the set_tab_width() method:
 737  $geshi->set_tab_width($width);
 738  
 739  Where $width is the width in spaces that you'd like tabs to be.
 740  3.10: Using Strict Mode
 741  Top | Contents | Next | Previous
 742  
 743  Some languages like to get tricky, and jump in and out of the file that they're in. For example, the vast majority of you reading this will have used a PHP file. And you know that PHP code is only executed if it's within delimiters like <?php and ?> (there are others of course...). So what happens if you do the following in a php file?
 744  <img src="<?php echo rand(1, 100) ?>" />
 745  
 746  Well normally using GeSHi with PHP, or using a bad highlighter, you'll end up with this:
 747  <img src="<?php echo rand(1, 100) ?>" />
 748  
 749  What a mess! Especially if you're being slack about where you're putting your quotes, you could end up with the rest of your file as bright red. Fortunately, you can tell GeSHi to be "strict" about just when it highlights and when it does not, using the enable_strict_mode method:
 750  $geshi->enable_strict_mode($mode);
 751  
 752  Where $mode is true or not specified to enable strict mode, or false to disable strict mode if you've already turned it and don't want it now.
 753  
 754  Here's the result: much better!
 755  <img src="<?php echo rand(1, 100) ?>" />
 756  3.11: Adding/Removing Keywords
 757  Top | Contents | Next | Previous
 758  
 759  Lets say that you're working on a large project, with many files, many classes and many functions. Perhaps also you have the source code on the web and highlighted by GeSHi, perhaps as a front end to CVS, as a learning tool, something to refer to, whatever. Well, why not highlight the names of the functions and classes *your* project uses, as well as the standard functions and classes? Or perhaps you're not interested in highlighting certain functions, and would like to remove them? Or maybe you don't mind if an entire function group goes west in the interest of speed? GeSHi can handle all of this!
 760  3.11.1: Adding a Keyword
 761  Top | Contents | Next | Previous
 762  
 763  If you want to add a keyword to an existing keyword group, you use the add_keyword method:
 764  $geshi->add_keyword($key, $word);
 765  
 766  Where $key is the index of the group of keywords you want to add this keyword to, and $word is the word to add.
 767  
 768  This implies knowledge of the language file to know the correct index.
 769  Note:
 770  
 771  Keywords should contain at least two alphabetical characters (lower or upper case letters only). This is to enable GeSHi to work much faster by not bothering to try to detect keywords in parts of your source where there is no alphabetical characters.
 772  3.11.2: Removing a Keyword
 773  Top | Contents | Next | Previous
 774  
 775  Perhaps you want to remove a keyword from an existing group. Maybe you don't use it and want to save yourself some time. Whatever the reason, you can remove it using the remove_keyword method:
 776  $geshi->remove_keyword($key, $word);
 777  
 778  Where $key is the index of the gropu of keywords that you want to remove this keyword from, and $word is the word to remove.
 779  
 780  This implies knowledge of the language file to know the correct index - most of the time the keywords you'll want to remove will be in group 3, but this is not guaranteed and you should check the language file first.
 781  
 782  This function is silent - if the keyword is not in the group you specified, nothing awful will happen ;)
 783  3.11.3: Adding a Keyword Group
 784  Top | Contents | Next | Previous
 785  
 786  Lets say for your big project you have several main functions and classes that you'd like highlighted. Why not add them as their own group instead of having them highlighted the same way as other keywords? Then you can make them stand out, and people can instantly see which functions and classes are user defined or inbuilt. Furthermore, you could set the URL for this group to point at the API documentation of your project.
 787  
 788  You add a keyword group by using the add_keyword_group method:
 789  $geshi->add_keyword_group($key, $styles, $case_sensitive, $words);
 790  
 791  Where $key is the key that you want to use to refer to this group, $styles is the styles that you want to use to style this group, $case_sensitive is true or false depending on whether you want this group of keywords to be case sensitive or not and $words is an array of words (or a string) of which words to add to this group. For example:
 792  $geshi->add_keyword_group(10, 'color: #600000;', false, array('myfunc_1', 'myfunc_2', 'myfunc_3'));
 793  
 794  Adds a keyword group referenced by index 10, of which all keywords in the group will be dark red, each keyword can be in any case and which contains the keywords "myfunc_1", "myfunc_2" and "myfunc_3".
 795  
 796  After creating such a keyword group, you may call other GeSHi methods on it, just as you would for any other keyword group.
 797  Caution:
 798  
 799  If you specify a $key for which there is already a keyword group, the old keyword group will be overwritten! Most language files don't use numbers larger than 5, so I recommend you play it safe and use a number like 10 or 42.
 800  3.11.4: Removing a Keyword Group
 801  Top | Contents | Next | Previous
 802  
 803  Perhaps you *really* need speed? Why not just remove an entire keyword group? GeSHi won't have to loop through each keyword checking for its existance, saving much time. You remove a keyword group by using the remove_keyword_group method:
 804  $geshi->remove_keyword_group($key);
 805  
 806  Where $key is the key of the group you wish to remove. This implies knowleged of the language file.
 807  3.12: Headers and Footers for Your Code
 808  Top | Contents | Next | Previous
 809  
 810  So you want to add some special information to the highlighted source? GeSHi can do that too! You can specify headers and footers for your code, style them, and insert information from the highlighted source into your header or footer.
 811  3.12.1: Keyword Substitution
 812  Top | Contents | Next | Previous
 813  
 814  In your header and footer, you can put special keywords that will be replaced with actual configuration values for this GeSHi object. The keywords you can use are:
 815  
 816      * <TIME> or {TIME}: Is replaced by the time it took for the parse_code method - i.e., how long it took for your code to be highlighted. The time is returned to three decimal places.
 817      * <LANGUAGE> or {LANGUAGE}: Is replaced by a nice, friendly version of the language name used to highlight this code.
 818      * <VERSION> or {VERSION}: The GeSHi version used to highlight the code.
 819  
 820  3.12.2: Setting Header Content
 821  Top | Contents | Next | Previous
 822  
 823  The header for your code is a <div>, which is inside the containing block. Therefore, it is affected by the method set_overall_style, and should contain the sort of HTML that belongs in a <div>. You may use any HTML you like, and format it as an HTML document. You should use valid HTML - convert to entities any quotemarks or angle brackets you want displayed. You set the header content using the method set_header_content:
 824  $geshi->set_header_content($content);
 825  
 826  Where $content is the HTML you want to use for the header.
 827  3.12.3: Setting Footer Content
 828  Top | Contents | Next | Previous
 829  
 830  The footer for your code is a <div>, which is inside the containing block. Therefore, it is affected by the method set_overall_style, and should contain the sort of HTML that belongs in a <div>. You may use any HTML you like, and format it as an HTML document. You should use valid HTML - convert to entities any quotemarks or angle brackets you want displayed. You set the footer content using the method set_footer_content:
 831  $geshi->set_footer_content($content);
 832  
 833  Where $content is the HTML you want to use for the footer.
 834  3.12.4: Styling Header Content
 835  Top | Contents | Next | Previous
 836  
 837  You can apply styles to the header content you have set with the set_header_content_style:
 838  $geshi->set_header_content_style($styles);
 839  
 840  Where $styles is the stylesheet declarations you want to use to style the header content.
 841  3.12.5: Styling Footer Content
 842  Top | Contents | Next | Previous
 843  
 844  You can apply styles to the footer content you have set with the set_footer_content_style:
 845  $geshi->set_footer_content_style($styles);
 846  
 847  Where $styles is the stylesheet declarations you want to use to style the footer content.
 848  3.13: Keyword URLs
 849  Top | Contents | Next | Previous
 850  
 851  As of version 1.0.2, GeSHi allows you to specify a URL for keyword groups. This URL is used by GeSHi to convert the keywords in that group into URLs to appropriate documentation. And using add_keyword_group you can add functions and classes from your own projects and use the URL functionality to provide a link to your own API documentation.
 852  3.13.1: Setting a URL for a Keyword Group
 853  Top | Contents | Next | Previous
 854  
 855  To set the URL to be used for a keyword group, you use the set_url_for_keyword_group method:
 856  $geshi->set_url_for_keyword_group($group, $url);
 857  
 858  Where $group is the keyword group you want to assign the URL for, and $url is the URL for this group of keywords.
 859  
 860  You may be wondering how to make each keyword in the group point to the correct URL. You do this by putting {FNAME} in the URL at the correct place. For example, PHP makes it easy by linking www.php.net/function-name to the documentation for that function, so the URL used is http://www.php.net/{FNAME}.
 861  
 862  Of course, when you get to a language like Java, that puts its class documentation in related folders, it gets a little trickier to work out an appropriate URL (see the Java language file!). I hope to provide some kind of redirection service at the GeSHi website in the future.
 863  Note:
 864  
 865  As of Version 1.0.7.21 there have been added two more symbols you can use to link to functions. {FNAMEL} will generate the lowercase version of the keyword, {FNAMEU} will generate the upper-case version. {FNAME} will provide the keyword as specified in the language file.
 866  3.13.2: Disabling a URL for a Keyword Group
 867  Top | Contents | Next | Previous
 868  
 869  It's easy to disable a URL for a keyword group: Simply use the method set_url_for_keyword_group to pass an empty string as the URL:
 870  $geshi->set_url_for_keyword_group($group, '');
 871  3.13.3 Disabling all URLs for Keywords
 872  Top | Contents | Next | Previous
 873  
 874  As of GeSHi 1.0.7.18, you can disable all URL linking for keywords:
 875  $geshi->enable_keyword_links(false);
 876  3.13.4: Styling Links
 877  Top | Contents | Next | Previous
 878  
 879  You can also style the function links. You can style their default status, hovered, active and visited status. All of this is controlled by one method, set_link_styles:
 880  $geshi->set_link_styles($mode, $styles);
 881  
 882  Where $mode is one of four values:
 883  
 884      * GESHI_LINK: The default style of the links.
 885      * GESHI_HOVER: The style of the links when they have focus (the mouse is hovering over them).
 886      * GESHI_ACTIVE: The style of the links when they are being clicked.
 887      * GESHI_VISITED: The style of links that the user has already visited.
 888  
 889  And $styles is the stylesheet declarations to apply to the links.
 890  3.13.5: Setting the Link Target
 891  Top | Contents | Next | Previous
 892  
 893  Perhaps you want to set the target of link attributes, so the manual pages open in a new window? Use the set_link_target method:
 894  $geshi->set_link_target($target, $styles);
 895  
 896  Where $target is any valid (X)HTML target value - _blank or _top for example.
 897  3.14: Using Contextual Importance
 898  Top | Contents | Next | Previous
 899  Caution:
 900  
 901  This functionality is not only buggy, but is proving very hard to implement in 1.1.X. Therefore, this functionality may well be removed in 1.2.0. You are hereby warned!
 902  3.15: Highlighting Special Lines "Extra"
 903  Top | Contents | Next | Previous
 904  
 905  An alternative (and more stable) method of highlighting code that is important is to use extra highlighting by line. Although you may not know what line numbers contain the important lines, if you do this method is a much more flexible way of making important lines stand out.
 906  3.15.1: Specifying the Lines to Highlight Extra
 907  Top | Contents | Next | Previous
 908  
 909  To specify which lines to highlight extra, you past an array containing the line numbers to highlight_lines_extra:
 910  $geshi->highlight_lines_extra($array);
 911  
 912  The array could be in the form array(2, 3, 4, 7, 12, 344, 4242), made from a DB query, generated from looking through the source for certain important things and working out what line those things are... however you get the line numbers, the array should simply be an array of integers.
 913  
 914  Here's an example, using the same source as before:
 915  //
 916  // Here we go again! This time we'll simply highlight the 8th line
 917  //
 918  $source = 'public int[][] product ( n, m )
 919  {
 920    int [][] ans = new int[n][m];
 921    for ( int i = 0; i < n; i++ )
 922    {
 923      for ( int j = 0; i < m; j++ )
 924      {
 925        ans[i][j] = i * j;
 926      }
 927    }
 928    return ans;
 929  }';
 930  
 931  $geshi = new GeSHi($source, 'java');
 932  
 933  $geshi->highlight_lines_extra(array(8));
 934  echo $geshi->parse_code();
 935  
 936  Which produces:
 937  public int[][] product ( n, m )
 938  {
 939    int [][] ans = new int[n][m];
 940    for ( int i = 0; i < n; i++ )
 941    {
 942      for ( int j = 0; i < m; j++ )
 943      {
 944        ans[i][j] = i * j;
 945      }
 946    }
 947    return ans;
 948  }
 949  
 950  What's more, as you can see the code on a highlighted line is still actually highlighted itself.
 951  Note:
 952  
 953  As you can see, this is a little buggy, but that is because of HTML laws (code elements should not contain div elements). This works just fine if you use line numbers.
 954  3.15.2: Styles for the Highlighted Lines
 955  Top | Contents | Next | Previous
 956  
 957  Again as with contextual importance, you're not chained to the yellow theme that is the default. You can use the set_highlight_lines_extra_style method:
 958  $geshi->set_highlight_lines_extra_style($styles);
 959  
 960  Where $styles is the stylesheet declarations that you want to apply to highlighted lines.
 961  3.16: Adding IDs to Each Line
 962  Top | Contents | Next | Previous
 963  
 964  Perhaps you're a javascript junkie? GeSHi provides a way to give each line an ID so you can access that line with javascript, or perhaps just by plain CSS (though if you want to access lines by CSS you should use the method in the previous section). To enable IDs you call the enable_ids method:
 965  $geshi->enable_ids($flag);
 966  
 967  Where $flag is true or not present to enable IDs, and false to disable them again if you need.
 968  
 969  The ID generated is in the form {overall-css-id}-{line-number}. So for example, if you set the overall CSS id to be "mycode", then the IDs for each line would by "mycode-1", "mycode-2" etc. If there is no CSS ID set, then one is made up in the form geshi-[4 random characters], but this is not so useful for if you want to do javascript manipulation.
 970  3.17: Getting the Time of Styling
 971  Top | Contents | Next | Previous
 972  
 973  Once you've called parse_code, you can get the time it took to run the highlighting by calling the get_time method:
 974  $geshi = new GeSHi($source, $language, $path);
 975  
 976  $code = mysql_real_escape_string($geshi->parse_code());
 977  $time = $geshi->get_time();
 978  
 979  // do something with it
 980  mysql_query("INSERT INTO code VALUES ('$code', '$time')");
 981  4: Language Files
 982  Top | Contents | Next | Previous
 983  
 984  So now you know what features GeSHi offers, and perhaps you've even meddled with the source. Or perhaps you'd like a language file for language X but it doesn't seem to be supported? Rubbish! GeSHi will highlight anything, what do you think I coded this for? ^_^ You'll just have to learn how to make a language file yourself. And I promise it's not too hard - and if you're here you're in the right place!
 985  4.1: An Example Language File
 986  Top | Contents | Next | Previous
 987  
 988  Let's begin by looking at an example language file - the language file for the first language ever supported, PHP.
 989  
 990  <?php
 991  /*************************************************************************************
 992   * php.php
 993   * --------
 994   * Author: Nigel McNie (nigel@geshi.org)
 995   * Copyright: (c) 2004 Nigel McNie (http://qbnz.com/highlighter/)
 996   * Release Version: 1.0.2
 997   * CVS Revision Version: $Revision: 1195 $
 998   * Date Started: 2004/06/20
 999   * Last Modified: $Date: 2008-06-08 19:44:08 +0200 (So, 08. Jun 2008) $
1000   *
1001   * PHP language file for GeSHi.
1002   *
1003   * CHANGES
1004   * -------
1005   * 2004/XX/XX (1.0.2)
1006   *  -  Added URL support
1007   *  -  Added extra constants
1008   * 2004/08/05 (1.0.1)
1009   *  -  Added support for symbols
1010   * 2004/07/14 (1.0.0)
1011   *  -  First Release
1012   *
1013   * TODO (updated 2004/07/14)
1014   * -------------------------
1015   * * Make sure the last few function I may have missed
1016   *   (like eval()) are included for highlighting
1017   * * Split to several files - php4, php5 etc
1018   *
1019   *************************************************************************************
1020   *
1021   *     This file is part of GeSHi.
1022   *
1023   *   GeSHi is free software; you can redistribute it and/or modify
1024   *   it under the terms of the GNU General Public License as published by
1025   *   the Free Software Foundation; either version 2 of the License, or
1026   *   (at your option) any later version.
1027   *
1028   *   GeSHi is distributed in the hope that it will be useful,
1029   *   but WITHOUT ANY WARRANTY; without even the implied warranty of
1030   *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1031   *   GNU General Public License for more details.
1032   *
1033   *   You should have received a copy of the GNU General Public License
1034   *   along with GeSHi; if not, write to the Free Software
1035   *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
1036   *
1037   ************************************************************************************/
1038  
1039  $language_data = array (
1040      'LANG_NAME' => 'PHP',
1041      'COMMENT_SINGLE' => array(1 => '//', 2 => '#'),
1042      'COMMENT_MULTI' => array('/*' => '*/'),
1043      'CASE_KEYWORDS' => GESHI_CAPS_NO_CHANGE,
1044      'QUOTEMARKS' => array("'", '"'),
1045      'ESCAPE_CHAR' => '\\',
1046      'KEYWORDS' => array(
1047          1 => array(
1048              'include', 'require', 'include_once', 'require_once',
1049              'for', 'foreach', 'as', 'if', 'elseif', 'else', 'while', 'do', 'endwhile', 'endif', 'switch', 'case', 'endswitch',
1050              'return', 'break'
1051              ),
1052          2 => array(
1053              'null', '__LINE__', '__FILE__',
1054              'false', '&lt;?php', '?&gt;', '&lt;?',
1055              '&lt;script language=', '&lt;/script&gt;',
1056              'true', 'var', 'default',
1057              'function', 'class', 'new',
1058              '__FUNCTION__', '__CLASS__', '__METHOD__', 'PHP_VERSION',
1059              'PHP_OS', 'DEFAULT_INCLUDE_PATH', 'PEAR_INSTALL_DIR', 'PEAR_EXTENSION_DIR',
1060              'PHP_EXTENSION_DIR', 'PHP_BINDIR', 'PHP_LIBDIR', 'PHP_DATADIR', 'PHP_SYSCONFDIR',
1061              'PHP_LOCALSTATEDIR', 'PHP_CONFIG_FILE_PATH', 'PHP_OUTPUT_HANDLER_START', 'PHP_OUTPUT_HANDLER_CONT',
1062              'PHP_OUTPUT_HANDLER_END', 'E_ERROR', 'E_WARNING', 'E_PARSE', 'E_NOTICE',
1063              'E_CORE_ERROR', 'E_CORE_WARNING', 'E_COMPILE_ERROR', 'E_COMPILE_WARNING', 'E_USER_ERROR',
1064              'E_USER_WARNING', 'E_USER_NOTICE', 'E_ALL'
1065              ),
1066          3 => array(
1067              'zlib_get_coding_type','zend_version','zend_logo_guid','yp_order','yp_next',
1068              'yp_match','yp_master','yp_get_default_domain','yp_first','yp_errno','yp_err_string',
1069              'yp_cat','yp_all','xml_set_unparsed_entity_decl_handler','xml_set_start_namespace_decl_handler','xml_set_processing_instruction_handler','xml_set_object',
1070              'xml_set_notation_decl_handler','xml_set_external_entity_ref_handler','xml_set_end_namespace_decl_handler','xml_set_element_handler','xml_set_default_handler','xml_set_character_data_handler',
1071              'xml_parser_set_option','xml_parser_get_option','xml_parser_free','xml_parser_create_ns','xml_parser_create','xml_parse_into_struct',
1072              'xml_parse','xml_get_error_code','xml_get_current_line_number','xml_get_current_column_number','xml_get_current_byte_index','xml_error_string',
1073              'wordwrap','wddx_serialize_vars','wddx_serialize_value','wddx_packet_start','wddx_packet_end','wddx_deserialize',
1074              'wddx_add_vars','vsprintf','vprintf','virtual','version_compare','var_export',
1075              'var_dump','utf8_encode','utf8_decode','usort','usleep','user_error',
1076              'urlencode','urldecode','unserialize','unregister_tick_function','unpack','unlink',
1077              'unixtojd','uniqid','umask','uksort','ucwords','ucfirst',
1078              'uasort','trim','trigger_error','touch','token_name','token_get_all',
1079              'tmpfile','time','textdomain','tempnam','tanh','tan',
1080              'system','syslog','symlink','substr_replace','substr_count','substr',
1081              'strval','strtr','strtoupper','strtotime','strtolower','strtok',
1082              'strstr','strspn','strrpos','strrev','strrchr','strpos',
1083              'strncmp','strncasecmp','strnatcmp','strnatcasecmp','strlen','stristr',
1084              'stripslashes','stripcslashes','strip_tags','strftime','stream_wrapper_register','stream_set_write_buffer',
1085              'stream_set_timeout','stream_set_blocking','stream_select','stream_register_wrapper','stream_get_meta_data','stream_filter_prepend',
1086              'stream_filter_append','stream_context_set_params','stream_context_set_option','stream_context_get_options','stream_context_create','strcspn',
1087              'strcoll','strcmp','strchr','strcasecmp','str_word_count','str_shuffle',
1088              'str_rot13','str_replace','str_repeat','str_pad','stat','sscanf',
1089              'srand','sqrt','sql_regcase','sprintf','spliti','split',
1090              'soundex','sort','socket_writev','socket_write','socket_strerror','socket_shutdown',
1091              'socket_setopt','socket_set_timeout','socket_set_option','socket_set_nonblock','socket_set_blocking','socket_set_block',
1092              'socket_sendto','socket_sendmsg','socket_send','socket_select','socket_recvmsg','socket_recvfrom',
1093              'socket_recv','socket_readv','socket_read','socket_listen','socket_last_error','socket_iovec_set',
1094              'socket_iovec_free','socket_iovec_fetch','socket_iovec_delete','socket_iovec_alloc','socket_iovec_add','socket_getsockname',
1095              'socket_getpeername','socket_getopt','socket_get_status','socket_get_option','socket_create_pair','socket_create_listen',
1096              'socket_create','socket_connect','socket_close','socket_clear_error','socket_bind','socket_accept',
1097              'sleep','sizeof','sinh','sin','similar_text','shuffle',
1098              'show_source','shmop_write','shmop_size','shmop_read','shmop_open','shmop_delete',
1099              'shmop_close','shm_remove_var','shm_remove','shm_put_var','shm_get_var','shm_detach',
1100              'shm_attach','shell_exec','sha1_file','sha1','settype','setlocale',
1101              'setcookie','set_time_limit','set_socket_blocking','set_magic_quotes_runtime','set_include_path','set_file_buffer',
1102              'set_error_handler','session_write_close','session_unset','session_unregister','session_start','session_set_save_handler',
1103              'session_set_cookie_params','session_save_path','session_register','session_regenerate_id','session_name','session_module_name',
1104              'session_is_registered','session_id','session_get_cookie_params','session_encode','session_destroy','session_decode',
1105              'session_cache_limiter','session_cache_expire','serialize','sem_remove','sem_release','sem_get',
1106              'sem_acquire','rtrim','rsort','round','rmdir','rewinddir',
1107              'rewind','restore_include_path','restore_error_handler','reset','rename','register_tick_function',
1108              'register_shutdown_function','realpath','readlink','readgzfile','readfile','readdir',
1109              'read_exif_data','rawurlencode','rawurldecode','range','rand','rad2deg',
1110              'quotemeta','quoted_printable_decode','putenv','proc_open','proc_close','printf',
1111              'print_r','prev','preg_split','preg_replace_callback','preg_replace','preg_quote',
1112              'preg_match_all','preg_match','preg_grep','pow','posix_uname','posix_ttyname',
1113              'posix_times','posix_strerror','posix_setuid','posix_setsid','posix_setpgid','posix_setgid',
1114              'posix_seteuid','posix_setegid','posix_mkfifo','posix_kill','posix_isatty','posix_getuid',
1115              'posix_getsid','posix_getrlimit','posix_getpwuid','posix_getpwnam','posix_getppid','posix_getpid',
1116              'posix_getpgrp','posix_getpgid','posix_getlogin','posix_getgroups','posix_getgrnam','posix_getgrgid',
1117              'posix_getgid','posix_geteuid','posix_getegid','posix_getcwd','posix_get_last_error','posix_errno',
1118              'posix_ctermid','pos','popen','pi','phpversion','phpinfo',
1119              'phpcredits','php_uname','php_sapi_name','php_logo_guid','php_ini_scanned_files','pg_update',
1120              'pg_untrace','pg_unescape_bytea','pg_tty','pg_trace','pg_setclientencoding','pg_set_client_encoding',
1121              'pg_send_query','pg_select','pg_result_status','pg_result_seek','pg_result_error','pg_result',
1122              'pg_query','pg_put_line','pg_port','pg_ping','pg_pconnect','pg_options',
1123              'pg_numrows','pg_numfields','pg_num_rows','pg_num_fields','pg_meta_data','pg_lowrite',
1124              'pg_lounlink','pg_loreadall','pg_loread','pg_loopen','pg_loimport','pg_loexport',
1125              'pg_locreate','pg_loclose','pg_lo_write','pg_lo_unlink','pg_lo_tell','pg_lo_seek',
1126              'pg_lo_read_all','pg_lo_read','pg_lo_open','pg_lo_import','pg_lo_export','pg_lo_create',
1127              'pg_lo_close','pg_last_oid','pg_last_notice','pg_last_error','pg_insert','pg_host',
1128              'pg_getlastoid','pg_get_result','pg_get_pid','pg_get_notify','pg_freeresult','pg_free_result',
1129              'pg_fieldtype','pg_fieldsize','pg_fieldprtlen','pg_fieldnum','pg_fieldname','pg_fieldisnull',
1130              'pg_field_type','pg_field_size','pg_field_prtlen','pg_field_num','pg_field_name','pg_field_is_null',
1131              'pg_fetch_row','pg_fetch_result','pg_fetch_object','pg_fetch_assoc','pg_fetch_array','pg_fetch_all',
1132              'pg_exec','pg_escape_string','pg_escape_bytea','pg_errormessage','pg_end_copy','pg_delete',
1133              'pg_dbname','pg_copy_to','pg_copy_from','pg_convert','pg_connection_status','pg_connection_reset',
1134              'pg_connection_busy','pg_connect','pg_cmdtuples','pg_close','pg_clientencoding','pg_client_encoding',
1135              'pg_cancel_query','pg_affected_rows','pfsockopen','pclose','pathinfo','passthru',
1136              'parse_url','parse_str','parse_ini_file','pack','overload','output_reset_rewrite_vars',
1137              'output_add_rewrite_var','ord','openssl_x509_read','openssl_x509_parse','openssl_x509_free','openssl_x509_export_to_file',
1138              'openssl_x509_export','openssl_x509_checkpurpose','openssl_x509_check_private_key','openssl_verify','openssl_sign','openssl_seal',
1139              'openssl_public_encrypt','openssl_public_decrypt','openssl_private_encrypt','openssl_private_decrypt','openssl_pkey_new','openssl_pkey_get_public',
1140              'openssl_pkey_get_private','openssl_pkey_free','openssl_pkey_export_to_file','openssl_pkey_export','openssl_pkcs7_verify','openssl_pkcs7_sign',
1141              'openssl_pkcs7_encrypt','openssl_pkcs7_decrypt','openssl_open','openssl_get_publickey','openssl_get_privatekey','openssl_free_key',
1142              'openssl_error_string','openssl_csr_sign','openssl_csr_new','openssl_csr_export_to_file','openssl_csr_export','openlog',
1143              'opendir','octdec','ob_start','ob_list_handlers','ob_implicit_flush','ob_iconv_handler',
1144              'ob_gzhandler','ob_get_status','ob_get_level','ob_get_length','ob_get_flush','ob_get_contents',
1145              'ob_get_clean','ob_flush','ob_end_flush','ob_end_clean','ob_clean','number_format',
1146              'nl_langinfo','nl2br','ngettext','next','natsort','natcasesort',
1147              'mysql_unbuffered_query','mysql_thread_id','mysql_tablename','mysql_table_name','mysql_stat','mysql_selectdb',
1148              'mysql_select_db','mysql_result','mysql_real_escape_string','mysql_query','mysql_ping','mysql_pconnect',
1149              'mysql_numrows','mysql_numfields','mysql_num_rows','mysql_num_fields','mysql_listtables','mysql_listfields',
1150              'mysql_listdbs','mysql_list_tables','mysql_list_processes','mysql_list_fields','mysql_list_dbs','mysql_insert_id',
1151              'mysql_info','mysql_get_server_info','mysql_get_proto_info','mysql_get_host_info','mysql_get_client_info','mysql_freeresult',
1152              'mysql_free_result','mysql_fieldtype','mysql_fieldtable','mysql_fieldname','mysql_fieldlen','mysql_fieldflags',
1153              'mysql_field_type','mysql_field_table','mysql_field_seek','mysql_field_name','mysql_field_len','mysql_field_flags',
1154              'mysql_fetch_row','mysql_fetch_object','mysql_fetch_lengths','mysql_fetch_field','mysql_fetch_assoc','mysql_fetch_array',
1155              'mysql_escape_string','mysql_error','mysql_errno','mysql_dropdb','mysql_drop_db','mysql_dbname',
1156              'mysql_db_query','mysql_db_name','mysql_data_seek','mysql_createdb','mysql_create_db','mysql_connect',
1157              'mysql_close','mysql_client_encoding','mysql_affected_rows','mysql','mt_srand','mt_rand',
1158              'mt_getrandmax','move_uploaded_file','money_format','mktime','mkdir','min',
1159              'microtime','method_exists','metaphone','memory_get_usage','md5_file','md5',
1160              'mbsubstr','mbstrrpos','mbstrpos','mbstrlen','mbstrcut','mbsplit',
1161              'mbregex_encoding','mberegi_replace','mberegi','mbereg_search_setpos','mbereg_search_regs','mbereg_search_pos',
1162              'mbereg_search_init','mbereg_search_getregs','mbereg_search_getpos','mbereg_search','mbereg_replace','mbereg_match',
1163              'mbereg','mb_substr_count','mb_substr','mb_substitute_character','mb_strwidth','mb_strtoupper',
1164              'mb_strtolower','mb_strrpos','mb_strpos','mb_strlen','mb_strimwidth','mb_strcut',
1165              'mb_split','mb_send_mail','mb_regex_set_options','mb_regex_encoding','mb_preferred_mime_name','mb_parse_str',
1166              'mb_output_handler','mb_language','mb_internal_encoding','mb_http_output','mb_http_input','mb_get_info',
1167              'mb_eregi_replace','mb_eregi','mb_ereg_search_setpos','mb_ereg_search_regs','mb_ereg_search_pos','mb_ereg_search_init',
1168              'mb_ereg_search_getregs','mb_ereg_search_getpos','mb_ereg_search','mb_ereg_replace','mb_ereg_match','mb_ereg',
1169              'mb_encode_numericentity','mb_encode_mimeheader','mb_detect_order','mb_detect_encoding','mb_decode_numericentity','mb_decode_mimeheader',
1170              'mb_convert_variables','mb_convert_kana','mb_convert_encoding','mb_convert_case','max','mail',
1171              'magic_quotes_runtime','ltrim','lstat','long2ip','log1p','log10',
1172              'log','localtime','localeconv','linkinfo','link','levenshtein',
1173              'lcg_value','ksort','krsort','key_exists','key','juliantojd',
1174              'join','jewishtojd','jdtounix','jdtojulian','jdtojewish','jdtogregorian',
1175              'jdtofrench','jdmonthname','jddayofweek','is_writeable','is_writable','is_uploaded_file',
1176              'is_subclass_of','is_string','is_scalar','is_resource','is_real','is_readable',
1177              'is_object','is_numeric','is_null','is_nan','is_long','is_link',
1178              'is_integer','is_int','is_infinite','is_float','is_finite','is_file',
1179              'is_executable','is_double','is_dir','is_callable','is_bool','is_array',
1180              'is_a','iptcparse','iptcembed','ip2long','intval','ini_set',
1181              'ini_restore','ini_get_all','ini_get','ini_alter','in_array','import_request_variables',
1182              'implode','image_type_to_mime_type','ignore_user_abort','iconv_set_encoding','iconv_get_encoding','iconv',
1183              'i18n_mime_header_encode','i18n_mime_header_decode','i18n_ja_jp_hantozen','i18n_internal_encoding','i18n_http_output','i18n_http_input',
1184              'i18n_discover_encoding','i18n_convert','hypot','htmlspecialchars','htmlentities','html_entity_decode',
1185              'highlight_string','highlight_file','hexdec','hebrevc','hebrev','headers_sent',
1186              'header','gzwrite','gzuncompress','gztell','gzseek','gzrewind',
1187              'gzread','gzputs','gzpassthru','gzopen','gzinflate','gzgetss',
1188              'gzgets','gzgetc','gzfile','gzeof','gzencode','gzdeflate',
1189              'gzcompress','gzclose','gregoriantojd','gmstrftime','gmmktime','gmdate',
1190              'glob','gettype','gettimeofday','gettext','getservbyport','getservbyname',
1191              'getrusage','getrandmax','getprotobynumber','getprotobyname','getopt','getmyuid',
1192              'getmypid','getmyinode','getmygid','getmxrr','getlastmod','getimagesize',
1193              'gethostbynamel','gethostbyname','gethostbyaddr','getenv','getdate','getcwd',
1194              'getallheaders','get_resource_type','get_required_files','get_parent_class','get_object_vars','get_meta_tags',
1195              'get_magic_quotes_runtime','get_magic_quotes_gpc','get_loaded_extensions','get_included_files','get_include_path','get_html_translation_table',
1196              'get_extension_funcs','get_defined_vars','get_defined_functions','get_defined_constants','get_declared_classes','get_current_user',
1197              'get_class_vars','get_class_methods','get_class','get_cfg_var','get_browser','fwrite',
1198              'function_exists','func_num_args','func_get_args','func_get_arg','ftruncate','ftp_systype',
1199              'ftp_ssl_connect','ftp_size','ftp_site','ftp_set_option','ftp_rmdir','ftp_rename',
1200              'ftp_rawlist','ftp_quit','ftp_pwd','ftp_put','ftp_pasv','ftp_nlist',
1201              'ftp_nb_put','ftp_nb_get','ftp_nb_fput','ftp_nb_fget','ftp_nb_continue','ftp_mkdir',
1202              'ftp_mdtm','ftp_login','ftp_get_option','ftp_get','ftp_fput','ftp_fget',
1203              'ftp_exec','ftp_delete','ftp_connect','ftp_close','ftp_chdir','ftp_cdup',
1204              'ftok','ftell','fstat','fsockopen','fseek','fscanf',
1205              'frenchtojd','fread','fputs','fpassthru','fopen','fnmatch',
1206              'fmod','flush','floor','flock','floatval','filetype',
1207              'filesize','filepro_rowcount','filepro_retrieve','filepro_fieldwidth','filepro_fieldtype','filepro_fieldname',
1208              'filepro_fieldcount','filepro','fileperms','fileowner','filemtime','fileinode',
1209              'filegroup','filectime','fileatime','file_get_contents','file_exists','file',
1210              'fgetss','fgets','fgetcsv','fgetc','fflush','feof',
1211              'fclose','ezmlm_hash','extract','extension_loaded','expm1','explode',
1212              'exp','exif_thumbnail','exif_tagname','exif_read_data','exif_imagetype','exec',
1213              'escapeshellcmd','escapeshellarg','error_reporting','error_log','eregi_replace','eregi',
1214              'ereg_replace','ereg','end','easter_days','easter_date','each',
1215              'doubleval','dngettext','dl','diskfreespace','disk_total_space','disk_free_space',
1216              'dirname','dir','dgettext','deg2rad','defined','define_syslog_variables',
1217              'define','decoct','dechex','decbin','debug_zval_dump','debug_backtrace',
1218              'deaggregate','dcngettext','dcgettext','dba_sync','dba_replace','dba_popen',
1219              'dba_optimize','dba_open','dba_nextkey','dba_list','dba_insert','dba_handlers',
1220              'dba_firstkey','dba_fetch','dba_exists','dba_delete','dba_close','date',
1221              'current','ctype_xdigit','ctype_upper','ctype_space','ctype_punct','ctype_print',
1222              'ctype_lower','ctype_graph','ctype_digit','ctype_cntrl','ctype_alpha','ctype_alnum',
1223              'crypt','create_function','crc32','count_chars','count','cosh',
1224              'cos','copy','convert_cyr_string','constant','connection_status','connection_aborted',
1225              'compact','closelog','closedir','clearstatcache','class_exists','chunk_split',
1226              'chr','chown','chop','chmod','chgrp','checkdnsrr',
1227              'checkdate','chdir','ceil','call_user_method_array','call_user_method','call_user_func_array',
1228              'call_user_func','cal_to_jd','cal_info','cal_from_jd','cal_days_in_month','bzwrite',
1229              'bzread','bzopen','bzflush','bzerrstr','bzerror','bzerrno',
1230              'bzdecompress','bzcompress','bzclose','bindtextdomain','bindec','bind_textdomain_codeset',
1231              'bin2hex','bcsub','bcsqrt','bcscale','bcpow','bcmul',
1232              'bcmod','bcdiv','bccomp','bcadd','basename','base_convert',
1233              'base64_encode','base64_decode','atanh','atan2','atan','assert_options',
1234              'assert','asort','asinh','asin','arsort','array_walk',
1235              'array_values','array_unshift','array_unique','array_sum','array_splice','array_slice',
1236              'array_shift','array_search','array_reverse','array_reduce','array_rand','array_push',
1237              'array_pop','array_pad','array_multisort','array_merge_recursive','array_merge','array_map',
1238              'array_keys','array_key_exists','array_intersect_assoc','array_intersect','array_flip','array_filter',
1239              'array_fill','array_diff_assoc','array_diff','array_count_values','array_chunk','array_change_key_case',
1240              'apache_setenv','apache_response_headers','apache_request_headers','apache_note','apache_lookup_uri','apache_get_version',
1241              'apache_child_terminate','aggregation_info','aggregate_properties_by_regexp','aggregate_properties_by_list','aggregate_properties','aggregate_methods_by_regexp',
1242              'aggregate_methods_by_list','aggregate_methods','aggregate','addslashes','addcslashes','acosh',
1243              'acos','abs','_','echo', 'print', 'global', 'static', 'exit', 'array', 'empty', 'eval', 'isset', 'unset', 'die'
1244              )
1245          ),
1246      'SYMBOLS' => array(
1247          '(', ')', '[', ']', '{', '}', '!', '@', '%', '&', '*', '|', '/', '<', '>'
1248          ),
1249      'CASE_SENSITIVE' => array(
1250          GESHI_COMMENTS => false,
1251          1 => false,
1252          2 => false,
1253          3 => false,
1254          ),
1255      'STYLES' => array(
1256          'KEYWORDS' => array(
1257              1 => 'color: #b1b100;',
1258              2 => 'color: #000000; font-weight: bold;',
1259              3 => 'color: #000066;'
1260              ),
1261          'COMMENTS' => array(
1262              1 => 'color: #808080; font-style: italic;',
1263              2 => 'color: #808080; font-style: italic;',
1264              'MULTI' => 'color: #808080; font-style: italic;'
1265              ),
1266          'ESCAPE_CHAR' => array(
1267              0 => 'color: #000099; font-weight: bold;'
1268              ),
1269          'BRACKETS' => array(
1270              0 => 'color: #66cc66;'
1271              ),
1272          'STRINGS' => array(
1273              0 => 'color: #ff0000;'
1274              ),
1275          'NUMBERS' => array(
1276              0 => 'color: #cc66cc;'
1277              ),
1278          'METHODS' => array(
1279              0 => 'color: #006600;'
1280              ),
1281          'SYMBOLS' => array(
1282              0 => 'color: #66cc66;'
1283              ),
1284          'REGEXPS' => array(
1285              0 => 'color: #0000ff;'
1286              ),
1287          'SCRIPT' => array(
1288              0 => '',
1289              1 => '',
1290              2 => '',
1291              3 => ''
1292              )
1293          ),
1294      'URLS' => array(
1295          1 => '',
1296          2 => '',
1297          3 => 'http://www.php.net/{FNAME}',
1298          4 => ''
1299          ),
1300      'OOLANG' => true,
1301      'OBJECT_SPLITTER' => '-&gt;',
1302      'REGEXPS' => array(
1303          0 => "[\\$]{1,2}[a-zA-Z_][a-zA-Z0-9_]*"
1304          ),
1305      'STRICT_MODE_APPLIES' => GESHI_MAYBE,
1306      'SCRIPT_DELIMITERS' => array(
1307          0 => array(
1308              '<?php' => '?>'
1309              ),
1310          1 => array(
1311              '<?' => '?>'
1312              ),
1313          2 => array(
1314              '<%' => '%>'
1315              ),
1316          3 => array(
1317              '<script language="php">' => '</script>'
1318              )
1319          ),
1320      'HIGHLIGHT_STRICT_BLOCK' => array(
1321          0 => true,
1322          1 => true,
1323          2 => true,
1324          3 => true
1325          )
1326  );
1327  
1328  ?>
1329  
1330  If you're remotely familiar with PHP (or even if you're not), you can see that all that a language file consists of is a glorified variable assignment. Easy! All a language file does is assign a variable $language_data. Though still, there's a lot of indices to that array... but this section is here to break each index down and explain it to you.
1331  4.2: Language File Conventions
1332  Top | Contents | Next | Previous
1333  
1334  There are several conventions that are used in language files. For ease of use and readability, your language files should obey the following rules:
1335  
1336      * Indentation is in tabs, not spaces: Use tabs! There's no excuse for using spaces in this day and age, where almost every good editor allows you to change the tab width. Tabs also take up less space, and ensure proper alignment. When you indent, use tabs, and if your editor converts tabs to spaces, tell it not to.
1337      * Strings are in single quotes: Every string in a language file should be in single quotes ('), unless you are specifying a single quote as a quotemark or escape character, in which case they can be in double quotes for readability; or if you are specifying a REGEXP (see below)
1338      * Large arrays are multi-lined: An array with more than three or four values should be broken into multiple lines. In any case, lines should not be wider than a full-screen window (about 100 chars per line max).
1339      * Ending brackets for multi-lined arrays on a new line: Also with a comma after them, unless the array is the last one in a parent array. See the PHP language file for examples of where to use commas.
1340      * Use GeSHi's constants: For capatalisation, regular expressions etc. use the GeSHi constants, not their actual values.
1341  
1342  There are more notes on each convention where it may appear in the language file sections below.
1343  4.3: Language File Sections
1344  Top | Contents | Next | Previous
1345  
1346  This section will look at all the sections of a language file, and how they relate to the final highlighting result.
1347  4.3.1: The Header
1348  Top | Contents | Next | Previous
1349  
1350  The header of a language file is the first lines with the big comment and the start of the variable $language_data:
1351  
1352  <?php
1353  /*************************************************************************************
1354   * <name-of-language-file.php>
1355   * ---------------------------------
1356   * Author: <name> (<e-mail address>)
1357   * Copyright: (c) 2004 <name> (<website URL>)
1358   * Release Version: 1.0.0
1359   * CVS Revision Version: $Revision: 1195 $
1360   * Date Started: <date started>
1361   * Last Modified: $Date: 2008-06-08 19:44:08 +0200 (So, 08. Jun 2008) $
1362   *
1363   * <name-of-language> language file for GeSHi.
1364   *
1365   * <any-comments...>
1366   *
1367   * CHANGES
1368   * -------
1369   * <date-of-release> (1.0.0)
1370   *  -  First Release
1371   *
1372   * TODO (updated <date-of-release>)
1373   * -------------------------
1374   * <things-to-do>
1375   *
1376   *************************************************************************************
1377   *
1378   *     This file is part of GeSHi.
1379   *
1380   *   GeSHi is free software; you can redistribute it and/or modify
1381   *   it under the terms of the GNU General Public License as published by
1382   *   the Free Software Foundation; either version 2 of the License, or
1383   *   (at your option) any later version.
1384   *
1385   *   GeSHi is distributed in the hope that it will be useful,
1386   *   but WITHOUT ANY WARRANTY; without even the implied warranty of
1387   *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1388   *   GNU General Public License for more details.
1389   *
1390   *   You should have received a copy of the GNU General Public License
1391   *   along with GeSHi; if not, write to the Free Software
1392   *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
1393   *
1394   ************************************************************************************/
1395  
1396  $language_data = array (
1397  
1398  The parts in angle brackets are the parts that you change for your language file. Everything else *must* remain the same!
1399  
1400  Here are the parts you should change:
1401  
1402      * <name-of-language-file.php> - This should become the name of your language file. Language file names are in lower case and contain only alphanumeric characters, dashes and underscores. Language files end with .php (which you should put with the name of your language file, eg language.php)
1403      * <name> - Your name, or alias.
1404      * <e-mail address> - Your e-mail address. If you want your language file included with GeSHi you must include an e-mail address that refers to an inbox controlled by you.
1405      * <website> - A URL of a website of yours (perhaps to a page that deals with your contribution to GeSHi, or your home page/blog)
1406      * <date-started> - The date you started working on the language file. If you can't remember, guestimate.
1407      * <name-of-language> - The name of the language you made this language file for (probably similar to the language file name).
1408      * <any-comments> - Any comments you have to make about this language file, perhaps on where you got the keywords for, what dialect of the language this language file is for etc etc. If you don't have any comments, remove the space for them.
1409      * <date-of-release - The date you released the language file to the public. If you simply send it to me for inclusion in a new GeSHi and don't release it, leave this blank, and I'll replace it with the date of the GeSHi release that it is first added to.
1410  
1411  Everything should remain the same, including $Revision: 1195 $ and $Date: 2008-06-08 19:44:08 +0200 (So, 08. Jun 2008) $ (I know these may look funny but they have their purpose for those of you who don't know about SVN).
1412  
1413  Also: I'm not sure about the copyright on a new language file. I'm not a lawyer, could someone contact me about whether the copyright for a new language file should be exclusivly the authors, or joint with me (if included in a GeSHi release)?
1414  4.3.2: The First Indices
1415  Top | Contents | Next | Previous
1416  
1417  Here is an example from the php language file of the first indices:
1418  
1419      'LANG_NAME' => 'PHP',
1420      'COMMENT_SINGLE' => array(1 => '//', 2 => '#'),
1421      'COMMENT_MULTI' => array('/*' => '*/'),
1422      'CASE_KEYWORDS' => GESHI_CAPS_NO_CHANGE,
1423      'QUOTEMARKS' => array("'", '"'),
1424      'ESCAPE_CHAR' => '\\',
1425  
1426  The first indices are the first few lines of a language file before the KEYWORDS index. These indices specify:
1427  
1428      * 'LANG_NAME': The name of the language. This name should be a human-readable version of the name (e.g. HTML 4 (transitional) instead of html4trans)
1429      * 'COMMENT_SINGLE': An array of single-line comments in your language, indexed by integers starting from 1. A single line comment is a comment that starts at the marker and goes until the end of the line. These comments may be any length > 0, and since they can be styled individually, can be used for other things than comments (for example the Java language file defines "import" as a single line comment). If you are making a language that uses a ' (apostrophe) as a comment (or in the comment marker somewhere), use double quotes. e.g.: "'"
1430      * 'COMMENT_MULTI': Used to specify multiline comments, an array in the form 'OPEN' => 'CLOSE'. Unfortunately, all of these comments you add here will be styled the same way (an area of improvement for GeSHi 1.2.X). These comment markers may be any length > 0.
1431      * 'CASE_KEYWORDS': Used to set whether the case of keywords should be changed automatically as they are found. For example, in an SQL or BASIC dialect you may want all keywords to be upper case. The accepted values for this are:
1432            o GESHI_CAPS_UPPER: Convert the case of all keywords to upper case.
1433            o GESHI_CAPS_LOWER: Convert the case of all keywords to lower case.
1434            o GESHI_CAPS_NO_CHANGE: Don't change the case of any keyword.
1435      * 'QUOTEMARKS': Specifies the characters that mark the beginning and end of a string. This is another example where if your language includes the ' string delimiter you should use double quotes around it.
1436      * 'ESCAPE_CHAR': Specifies the escape character used in all strings. If your language does not have an escape character then make this the empty string (''). This is not an array! If found, any character after an escape character and the escape character itself will be highlighted differently, and the character after the escape character cannot end a string.
1437  
1438  4.3.3: Keywords
1439  Top | Contents | Next | Previous
1440  
1441  Keywords will make up the bulk of a language file. In this part you add keywords for your language, including inbuilt functions, data types, predefined constants etc etc.
1442  
1443  Here's a (shortened) example from the php language file:
1444  
1445      'KEYWORDS' => array(
1446          1 => array(
1447              'include', 'require', 'include_once', 'require_once',
1448              'for', 'foreach', 'as', 'if', 'elseif', 'else', 'while', 'do', 'endwhile', 'endif', 'switch', 'case', 'endswitch',
1449              'return', 'break'
1450              ),
1451          2 => array(
1452              'null', '__LINE__', '__FILE__',
1453              'false', '<?php', '?>', '<?',
1454              '<script language=', '</script>',
1455              'true', 'var', 'default',
1456              'function', 'class', 'new',
1457              '__FUNCTION__', '__CLASS__', '__METHOD__', 'PHP_VERSION',
1458              'PHP_OS', 'DEFAULT_INCLUDE_PATH', 'PEAR_INSTALL_DIR', 'PEAR_EXTENSION_DIR',
1459              'PHP_EXTENSION_DIR', 'PHP_BINDIR', 'PHP_LIBDIR', 'PHP_DATADIR', 'PHP_SYSCONFDIR',
1460              'PHP_LOCALSTATEDIR', 'PHP_CONFIG_FILE_PATH', 'PHP_OUTPUT_HANDLER_START', 'PHP_OUTPUT_HANDLER_CONT',
1461              'PHP_OUTPUT_HANDLER_END', 'E_ERROR', 'E_WARNING', 'E_PARSE', 'E_NOTICE',
1462              'E_CORE_ERROR', 'E_CORE_WARNING', 'E_COMPILE_ERROR', 'E_COMPILE_WARNING', 'E_USER_ERROR',
1463              'E_USER_WARNING', 'E_USER_NOTICE', 'E_ALL'
1464              ),
1465          3 => array(
1466              'zlib_get_coding_type','zend_version','zend_logo_guid','yp_order','yp_next',
1467              'yp_match','yp_master','yp_get_default_domain','yp_first','yp_errno','yp_err_string',
1468              'yp_cat','yp_all','xml_set_unparsed_entity_decl_handler','xml_set_start_namespace_decl_handler','xml_set_processing_instruction_handler','xml_set_object',
1469              'xml_set_notation_decl_handler','xml_set_external_entity_ref_handler','xml_set_end_namespace_decl_handler','xml_set_element_handler','xml_set_default_handler','xml_set_character_data_handler',
1470              'xml_parser_set_option','xml_parser_get_option','xml_parser_free','xml_parser_create_ns','xml_parser_create','xml_parse_into_struct'
1471              )
1472          ),
1473  
1474  You can see that the index 'KEYWORDS' refers to an array of arrays, indexed by positive integers. In each array, there are some keywords (in the actual php language file there is in fact many more keywords in the array indexed by 3). Here are some points to note about these keywords:
1475  
1476      * Indexed by positive integers: Use nothing else! I may change this in 1.2.X, but for the 1.0.X series, use positive integers only.
1477      * Keywords sorted in reverse: Keywords *should* be sorted in reverse order. I know that many of the language files I've made do not follow this rule, but that's because I made the files before I discovered the following issue with GeSHi: If you have two keywords, as and ascfor example, then when GeSHi encounters the "as" keyword it will be highlighted even if the "as" is part of "asc". I would get GeSHi to reverse-sort keyword arrays, but there's no harm in you doing this yourself and saving some processing time. At the least (and in fact this is sufficient) you should swap any keywords you come across that would be caught by this issue.
1478      * Keywords are case sensitive (sometimes): If your language is case-sensitive, the correct casing of the keywords is defined as the case of the keywords in these keyword arrays. If you check the java language file you will see that everything is in exact casing. So if any of these keyword arrays are case sensitive, put the keywords in as their correct case! (note that which groups are case sensitive and which are not is configurable, see later on)
1479      * Keywords must be in htmlentities() form: All keywords should be written as if they had been run through the php function htmlentities(). E.g, the keyword is &lt;foo&gt;, not <foo>
1480      * Don't use keywords to highlight symbols: Just don't. It doesn't work, and there will be seperate support for symbols later.
1481      * Markup Languages are special cases: Check the html4strict language file for an example: keywords have to be specified twice for opening tags and twice for each closing tag.
1482  
1483  4.3.4: Symbols and Case Sensitivity
1484  Top | Contents | Next | Previous
1485  
1486  So you've put all the keywords for your language in? Now for a breather before we style them :). Symbols define what symbols your language uses, these are things like colons, brackets/braces, and other such general punctuation, and case sensitivity alludes to the previous section: here you can set which keyword groups are case sensitive.
1487  
1488  As of GeSHi version 1.0.7.21 the symbols section is used in two ways:
1489  
1490      * Flat usage:
1491        This mode is the suggested way for existing language files and languages that only need few symbols where no further differentiation is needed or desired. You simply put all the characters in an array under symbols as shown in the first example below. All symbols in flat usage belong to symbol style group 0.
1492      * Group usage:
1493        This is a slightly more enhanced way to provide GeSHi symbol information. To use group you create several subarrays each containing only a subset of the symbols to highlight. Every array will need to have an unique index thus you can assign the appropriate styles later.
1494  
1495  Here's an example for flat symbol usage
1496  
1497      'SYMBOLS' => array(
1498          '(', ')', '[', ']', '{', '}', '!', '@', '|', '&', '+', '-', '*', '/', '%', '=', '<', '>'
1499          ),
1500      'CASE_SENSITIVE' => array(
1501          GESHI_COMMENTS => false,
1502          1 => false,
1503          2 => false,
1504          3 => false,
1505          ),
1506  
1507  which is not too different from the newly introduced group usage shown below:
1508  
1509      'SYMBOLS' => array(
1510          0 => array('(', ')', '[', ']', '{', '}'),
1511          1 => array('!', '@', '|', '&'),
1512          2 => array('+', '-', '*', '/', '%'),
1513          3 => array('=', '<', '>')
1514          ),
1515      'CASE_SENSITIVE' => array(
1516          GESHI_COMMENTS => false,
1517          1 => false,
1518          2 => false,
1519          3 => false,
1520          ),
1521  
1522      * 'SYMBOLS': An array of the symbols, or - as of 1.0.7.21 - an array of symbol groups, used in your language. Please note that versions before 1.0.7.21 will silently ignore this setting.
1523      * 'CASE_SENSITIVE': Note the GESHI_COMMENTS! This is used to set whether comments are case sensitive or not (for example, BASIC has the REM statement which while not being case sensitive is still alphanumeric, and as in the example given before about the Java language file using "import" as a single line comment, this can be useful sometimes. true if comments are case sensitive, false otherwise. All of the other indices correspond to indices in the 'KEYWORDS' section (see above).
1524  
1525  4.3.5: Styles for your Language File
1526  Top | Contents | Next | Previous
1527  
1528  This is the fun part! Here you get to choose the colours, fonts, backgrounds and anything else you'd like for your language file.
1529  
1530  Here's an example:
1531  
1532      'STYLES' => array(
1533          'KEYWORDS' => array(
1534              1 => 'color: #b1b100;',
1535              2 => 'color: #000000; font-weight: bold;',
1536              3 => 'color: #000066;'
1537              ),
1538          'COMMENTS' => array(
1539              1 => 'color: #808080; font-style: italic;',
1540              2 => 'color: #808080; font-style: italic;',
1541              'MULTI' => 'color: #808080; font-style: italic;'
1542              ),
1543          'ESCAPE_CHAR' => array(
1544              0 => 'color: #000099; font-weight: bold;'
1545              ),
1546          'BRACKETS' => array(
1547              0 => 'color: #66cc66;'
1548              ),
1549          'STRINGS' => array(
1550              0 => 'color: #ff0000;'
1551              ),
1552          'NUMBERS' => array(
1553              0 => 'color: #cc66cc;'
1554              ),
1555          'METHODS' => array(
1556              0 => 'color: #006600;'
1557              ),
1558          'SYMBOLS' => array(
1559              0 => 'color: #66cc66;'
1560              ),
1561          'REGEXPS' => array(
1562              0 => 'color: #0000ff;'
1563              ),
1564          'SCRIPT' => array(
1565              0 => '',
1566              1 => '',
1567              2 => '',
1568              3 => ''
1569              )
1570          ),
1571  
1572  Note that all style rules should end with a semi-colon! This is important: GeSHi may add extra rules to the rules you specify (and will do so if a user tries to change your styles on the fly), so the last semi-colon in any stylesheet rule is important.
1573  
1574  All strings here should contain valid stylesheet declarations (it's also find to have the empty string).
1575  
1576      * 'KEYWORDS': This is an array, from keyword index to style. The index you use is the index you used in the keywords section to specify the keywords belonging to that group.
1577      * 'COMMENTS': This is an array, from single-line comment index to style for that index. The index 'MULTI' is used for multiline comments (and cannot be an array)
1578      * 'ESCAPE_CHAR' down to 'SYMBOLS': These are arrays with only one index: 0. You cannot add other indices to these arrays.
1579      * 'REGEXPS':This is an array with a style for each matching regex. Also, since 1.0.7.21, you can specify the name of a function to be called, that will be given the text matched by the regex, each time a match is found. Note that my testing found that create_function would not work with this due to a PHP bug, so you have to put the function definition at the top of the language file. Be sure to prefix the function name with geshi_[languagename]_ as to not conflict with other functions!
1580      * 'SCRIPT': For languages that use script delimiters, this is where you can style each block of script. For example, HTML and XML have blocks that begin with < and end with > (i.e. tags) and blocks that begin with & and end with ; (i.e. character entities), and you can set a style to apply to each whole block. You specify the delimiters for the blocks below. Note that many languages will not need this feature.
1581  
1582  4.3.6: URLs for Functions
1583  Top | Contents | Next | Previous
1584  
1585  This section lets you specify a url to visit for each keyword group. Useful for pointing functions at their online manual entries.
1586  
1587  Here is an example:
1588  
1589      'URLS' => array(
1590          1 => '',
1591          2 => '',
1592          3 => 'http://www.php.net/{FNAME}',
1593          4 => ''
1594          ),
1595  
1596  The indices of this array correspond to the keyword groups you specified in the keywords section. The string {FNAME} marks where the name of the function is substituted in. So for the example above, if the keyword being highlighted is "echo", then the keyword will be a URL pointing to http://www.php.net/echo. Because some languages (Java!) don't keep a uniform URL for functions/classes, you may have trouble in creating a URL for that language (though look in the java language file for a novel solution to it's problem)
1597  4.3.7: Object Orientation Support
1598  Top | Contents | Next | Previous
1599  
1600  Now we're reaching the most little-used section of a language file, which includes such goodies as object orientation support and context support. GeSHi can highlight methods and data fields of objects easily, all you need to do is to tell it to do so and what the "splitter" is between object/method etc.
1601  
1602  Here's an example:
1603  
1604      'OOLANG' => true,
1605      'OBJECT_SPLITTER' => '->',
1606  
1607  If your language has object orientation, the value of 'OOLANG' is true, otherwise it is false. If it is object orientated, in the 'OBJECT_SPLITTER' value you put the htmlentities() version of the "splitter" between objects and methods/fields. If it is not, then make this the empty string.
1608  4.3.8: Using Regular Expressions
1609  Top | Contents | Next | Previous
1610  
1611  Regular expressions are a good way to catch any other lexic that fits certain rules but can't be listed as a keyword. A good example is variables in PHP: variables always start with either one or two "$" signs, then alphanumeric characters (a simplification). This is easy to catch with regular expressions.
1612  
1613  And new to version 1.0.2, there is an advanced way of using regular expressions to catch certain things but highlight only part of those things. This is particularly useful for languages like XML.
1614  Caution:
1615  
1616  Regular expressions use the PCRE syntax (perl-style), not the ereg() style!
1617  
1618  Here is an example (this time the PHP file merged with the XML file):
1619  
1620          0 => array(
1621              GESHI_SEARCH => '(((xml:)?[a-z\-]+))(=)',
1622              GESHI_REPLACE => '\\1',
1623              GESHI_MODIFIERS => '',
1624              GESHI_BEFORE => '',
1625              GESHI_AFTER => '\\4'
1626              ),
1627          1 => array(
1628              GESHI_SEARCH => '(>/?[a-z0-9]*(>)?)',
1629              GESHI_REPLACE => '\\1',
1630              GESHI_MODIFIERS => '',
1631              GESHI_BEFORE => '',
1632              GESHI_AFTER => ''
1633              ),
1634          2 => "[\\$]{1,2}[a-zA-Z_][a-zA-Z0-9_]*"
1635  
1636  As you can see there are two formats. One is the "simple" format used in GeSHi < 1.0.2, and the other is a more advanced syntax. Firstly, the simple syntax:
1637  
1638      * May be in double quotes: To make it easier for those who always place their regular expressions in double quotes, you may place any regular expression here in double quotes if you wish.
1639      * Don't use curly brackets where possible: If you want to use curly brackets (()) then by all means give it a try, but I'm not sure whether under some circumstances GeSHi may throw a wobbly. You have been warned! If you want to use brackets, it would be better to use the advanced syntax.
1640      * Don't use the "everything" regex: (That's the .*? regex). Use advanced syntax instead.
1641  
1642  And now for advanced syntax, which gives you much more control over exactly what is highlighted:
1643  
1644      * GESHI_SEARCH: This element specifies the regular expression to search for. If you plan to capture the output, use brackets (()). See how in the first example above, most of the regular expression is in one set of brackets (with the equals sign in other brackets). You should make sure that the part of the regular expression that is supposed to match what is highlighted is in brackets.
1645      * GESHI_REPLACE: This is what the stuff matched by the regular expression will be replaced with. If you've grouped the stuff you want highlighted into brackets in the GESHI_SEARCH element, then you can use \\number to match that group, where number is a number corresponding to how many open brackets are between the open bracket of the group you want highlighted and the start of the GESHI_SEARCH string + 1. This may sound confusing, and it probably is, but if you're familiar with how PHP's regular expressions work you should understand. In the example above, the opening bracket for the stuff we want highlighted is the very first bracket in the string, so the number of brackets before that bracket and the start of the string is 0. So we add 1 and get our replacement string of \\1 (whew!).
1646  
1647        If you didn't understand a word of that, make sure that there are brackets around the string in GESHI_SEARCH and use \\1 for GESHI_REPLACE ;)
1648      * GESHI_MODIFIERS: Specify modifiers for your regular expression. If your regular expression includes the everything matcher (.*?), then your modifiers should include "s" and "i" (e.g. use 'si' for this).
1649      * GESHI_BEFORE:Specifies a bracket group that should appear before the highlighted match (this bracketed group will not be highlighted). Use this if you had to match what you wanted by matching part of your regexp string to something before what you wanted to highlight, and you don't want that part to disappear in the highlighted result.
1650      * GESHI_AFTER:Specifies a bracket group that should appear after the highlighted match (this bracketed group will not be highlighted). Use this if you had to match what you wanted by matching part of your regexp string to something after what you wanted to highlight, and you don't want that part to disappear in the highlighted result.
1651  
1652  Is that totally confusing? Here's the test for if you're an android or not: If you found that perfectly understandable then you're an android ;). Here's a better example:
1653  
1654  Let's say that I'm making a language, and variables in this language always start with a dollar sign ($), are always written in lowercase letters and always end with an ampersand (&). eg:
1655  $foo& = 'bar'
1656  
1657  I want to highlight only the text between the $ and the &. How do I do that? With simple regular expressions I can't, but with advanced, it's relatively easy:
1658  
1659          1 => array(
1660              GESHI_SEARCH => '(\$)([a-z]+)(&)',   // search for a dollar sign, then one or more of the characters a-z, then an ampersand
1661              GESHI_REPLACE => '\\2',                  // we wanna highlight the characters, which are in the second bracketed group
1662              GESHI_MODIFIERS => '',                   // no modifiers, since we're not matching the "anything" regex
1663              GESHI_BEFORE => '\\1',                   // before the highlighted characters should be the first bracketed group (always a dollar sign in this example)
1664              GESHI_AFTER => '\\3'                     // after the highlighted characters should be the third bracketed group (always an ampersand in this example)
1665              ),
1666  
1667  So if someone tried to highlight using my language, all cases of $foo& would turn into:
1668  $<span style="color: blue;">foo</span>&
1669  
1670  (which would of course be viewed in a browser to get something like $foo&)
1671  4.3.9: Contextual Highlighting and Strict Mode
1672  Top | Contents | Next | Previous
1673  
1674  For languages like HTML, it's good if we can highlight a tag (like <a> for example). But how do we stop every single "a" in the source getting highlighted? What about for attributes? If I've got the word "colspan" in my text I don't want that highlighted! So how do you tell GeSHi not to highlight in that case? You do it with "Strict Blocks".
1675  
1676  Here is an example:
1677  
1678      'STRICT_MODE_APPLIES' => GESHI_MAYBE,
1679      'SCRIPT_DELIMITERS' => array(
1680          0 => array(
1681              '<?php' => '?>'
1682              ),
1683          1 => array(
1684              '<?' => '?>'
1685              ),
1686          2 => array(
1687              '<%' => '%>'
1688              ),
1689          3 => array(
1690              '<script language="php">' => '</script>'
1691              )
1692          ),
1693      'HIGHLIGHT_STRICT_BLOCK' => array(
1694          0 => true,
1695          1 => true,
1696          2 => true,
1697          3 => true
1698          )
1699  
1700  What is strict mode? Strict mode says that highlighting only occurs inside the blocks you specify. You can see from the example above that highlighting will only occur if the source is inside <?php ... ?> (though note the GESHI_MAYBE!). Here are some points about strict highlighting:
1701  
1702      * 'STRICT_MODE_APPLIES': This takes three values (all constants):
1703            o GESHI_ALWAYS: Strict mode always applies for all of the blocks you specify. Users of your language file cannot turn strict mode off. This should be used for markup languages.
1704            o GESHI_NEVER: Strict mode is never used. Users of your language file cannot turn strict mode on. Use this value if there is no such thing as a block of code that would not be highlighted in your language (most languages, like C, Java etc. use this because anything in a C file should be highlighted).
1705            o GESHI_MAYBE: Strict mode *sometimes* applies. It defaults to "off". Users can turn strict mode on if they please. If strict mode is off then everything in the source will be highlighted, even things outside the strict block markers. If strict mode is on the nothing outside strict block markers will be highlighted.
1706      * SCRIPT_DELIMITERS: This is an array of script delimiters, in the format of the above. The indices are use in the 'SCRIPT' part of the styles section for highlighting everything in a strict block in a certain way. For example, you could set up your language file to make the background yellow of any code inside a strict block this way. The delimiters are in the form 'OPEN' => 'CLOSE'. Delimiters can be of any length > 0. Delimiters are not formatted as if they were run through htmlentities()!
1707      * 'HIGHLIGHT_STRICT_BLOCK': specifies whether any highlighting should go on inside each block. Most of the time this should be true, but for example, in the XML language file highlighting is turned off for blocks beginning with <!DOCTYPE and ending with >. However, you can still style the overall block using the method described above, and the XML language file does just that.
1708  
1709  Note:
1710  
1711  The delimiters should be in reverse alphabetical order. Note that in the above example, <?php comes before <?.
1712  4.3.10: Tidying Up
1713  Top | Contents | Next | Previous
1714  
1715  All language files should end with:
1716  
1717  );
1718  
1719  ?>
1720  
1721  5: Method/Constant Reference
1722  Top | Contents | Next | Previous
1723  
1724  I'm afraid I have been lying for a little while about this now! Since 1.0.7 I have been including a phpdoc API for the sourcecode in the api directory, but have forgot to update the documentation! However, it is available, and may assist you in coding, especially for plugin coders.
1725  
1726  That's all, folks!
1727  
1728  I've improved the documentation greatly from version 1.0.1, but there may still be problems with it, or it may still be confusing for you. Or perhaps I was just plain wrong about one point! If so, contact me and I'll do my best to sort it out.
1729  
1730  In case you were wondering, I've finished development of the 1.0.X thread of GeSHi. The only releases I'll make in this thread will be of the bug-fix/add language files type. In particular, version 1.0.2 was a "concept" release - testing how far I could take the highlighting idea (as well as ideas from others).
1731  
1732  I'm planning a code rewrite for 1.2.X, which will be based on a new engine - a "psuedo-tokenizer" engine. Hopefully it will massively reduce the server load and time taken (by almost eliminating regexps), while providing superior highlighting. But fear not! The interface and method names should all remain the same ^_^ (though I can't say the same for language files!)
1733  
1734  And finally, a couple of people have been asking me: how did you generate that documentation? The amazing answer is: my brain. And yes, it took a long time, and I don't reccommend doing it this way. And yes, you can borrow the styles if you like, though flick me an e-mail if you do.
1735  
1736  Anyway, enough blather from me. Get GeSHi working for you already! :D
1737  
1738  Nigel McNie
1739  nigel@geshi.org
1740  http://qbnz.com/highlighter/
1741  

title

Description

title

Description

title

Description

title

title

Body