blob: fff53476786f41461488ccf9020b6b5cd83a147b [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>GeSHi Documentation 1.0.8.3</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="keywords" content="GeSHi, syntax, highlighter, colorizer, beautifier, code, generic, php, sql, css, html, syntax, highlighting, documentation" />
<meta name="description" content="GeSHi - Generic Syntax Highlighter for PHP. Highlight many languages, including PHP, CSS, HTML, SQL, Java and C for XHTML compliant output using this easy PHP Class. Every aspect of the highlighting is customisable, from colours and other styles to case-sensitivity checking and more. GeSHi - the best syntax highlighter in the world!" />
<style type="text/css">
html {
background-color: #e6e6e6;
}
body {
font-family: Verdana, Arial, sans-serif;
margin: 10px;
border: 2px solid #d0d0d0;
background-color: #f6f6f6;
padding: 10px;
}
p, ul, ol, div, blockquote, dt, dd {
font-size: 80%;
line-height: 140%;
letter-spacing: 1px;
color: #002;
}
dt {
font-weight: bold;
}
acronym {
border-bottom: 1px dotted #303030;
cursor: help;
}
blockquote {
font-weight: bold;
}
pre, .geshicode {
border: 1px solid #c0e6ff;
background-color: #e0e8ef;
color: #002;
margin:0;
font-size: 12px;
width:100%;
}
table {
border-collapse:collapse;
}
.geshicode pre {
border:none;
background-color:inherit;
font-weight:bold;
}
.geshicode .li2 td {
background-color:#eee;
}
.geshicode .li1 td {
background-color:#fff;
}
.geshicode td td {
padding:0 2px;
}
.geshicode td, .geshicode table {
width: 100%;
}
.geshicode td.ln {
border-right:2px solid #e0e8ef;
}
.geshicode .head {
text-align:center;
font-weight:bold;
}
code, tt, kbd {
font-size: 125%;
font-weight:normal;
}
hr {
height: 0;
border: none;
border-top: 1px dotted #404040;
width: 75%;
}
var {
color: blue; font-style: normal; font-family: monospace;
}
li {
padding-top: 2px;
}
ul ul, ol ol, div ul, div ol {
font-size:100%;
}
.note {
border: 1px solid yellow;
background-color: #ffc;
color: #220;
padding: 5px;
margin: 1em 0 0 .75em;
}
.caution {
border: 6px double red;
background-color: #fcc;
color: #200;
padding: 5px;
margin: 1em 0 0 .75em;
}
.caution p:first-child, .note p:first-child {
margin-top: 0;
}
.caution-header {
border: 1px solid red;
border-width: 1px 2px 2px 1px;
margin-top: -1.6em;
background-color: #fcc;
width: 10%;
font-weight: bold;
text-align: center;
color: #600;
}
.note-header {
border: 1px solid #ff0;
border-width: 1px 2px 2px 1px;
margin-top: -1.2em;
background-color: #ffc;
width: 10%;
font-weight: bold;
text-align: center;
color: #660;
}
.nav {
font-size: 70%;
}
.nav a {
color: #707070;
border: 1px solid #a0a0a0;
border-width: 0 1px 1px 1px;
border-top: 1px dotted #c0c0c0;
text-decoration: none;
padding: 1px 2px;
background-color: #e0e0e0;
-moz-border-radius-bottomleft: 3px;
-moz-border-radius-bottomright: 3px;
}
h1, #contents {
margin-top: 0;
margin-bottom: 0;
text-align: center;
color: #404060;
}
#contents {
text-align:left;
background:none;
border:none;
}
h2 {
border-bottom: 1px dotted #b0b0b0;
margin-top: 2em;
border-top: 1px dotted #b0b0b0;
background-color: #ddd;
margin-bottom: 0;
}
h3 {
margin-top: 1.6em;
border-bottom: 1px dotted #c0c0c0;
margin-bottom: 0;
}
h4 {
border-bottom: 1px dotted #d0d0d0;
margin-top: 1.2em;
margin-bottom: 0;
}
h2, h3, h4 {
color: #707070;
font-weight: normal;
}
a {
color: #7777ff;
}
sup a {
text-decoration: none;
}
abbr {
cursor: help;
}
.header p {
text-align: center;
border-bottom: 1px dotted #d0d0d0;
}
.header dl {
background-color: #e0e8ef;
color: #002;
padding: 5px;
}
.header img {
float: right;
margin:2.5em 1em 0 0;
}
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for bash
* CSS class: , CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.bash .de1, .bash .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
.bash {font-family:monospace;}
.bash .imp {font-weight: bold; color: red;}
.bash li, .bash .li1 {font-weight: normal; vertical-align:top;}
.bash .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
.bash .li2 {font-weight: bold; vertical-align:top;}
.bash .kw1 {color: #000000; font-weight: bold;}
.bash .kw2 {color: #c20cb9; font-weight: bold;}
.bash .kw3 {color: #7a0874; font-weight: bold;}
.bash .co0 {color: #666666; font-style: italic;}
.bash .co1 {color: #800000;}
.bash .co2 {color: #cc0000; font-style: italic;}
.bash .co3 {color: #000000; font-weight: bold;}
.bash .es1 {color: #000099; font-weight: bold;}
.bash .es2 {color: #007800;}
.bash .es3 {color: #007800;}
.bash .es4 {color: #007800;}
.bash .es5 {color: #780078;}
.bash .es_h {color: #000099; font-weight: bold;}
.bash .br0 {color: #7a0874; font-weight: bold;}
.bash .sy0 {color: #000000; font-weight: bold;}
.bash .st0 {color: #ff0000;}
.bash .st_h {color: #ff0000;}
.bash .nu0 {color: #000000;}
.bash .re0 {color: #007800;}
.bash .re1 {color: #007800;}
.bash .re2 {color: #007800;}
.bash .re4 {color: #007800;}
.bash .re5 {color: #660033;}
.bash .ln-xtra, .bash li.ln-xtra, .bash div.ln-xtra {background-color: #ffc;}
.bash span.xtra { display:block; }
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for php
* CSS class: , CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.php .de1, .php .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
.php {font-family:monospace;}
.php .imp {font-weight: bold; color: red;}
.php li, .php .li1 {font-weight: normal; vertical-align:top;}
.php .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
.php .li2 {font-weight: bold; vertical-align:top;}
.php .kw1 {color: #b1b100;}
.php .kw2 {color: #000000; font-weight: bold;}
.php .kw3 {color: #990000;}
.php .kw4 {color: #009900; font-weight: bold;}
.php .co1 {color: #666666; font-style: italic;}
.php .co2 {color: #666666; font-style: italic;}
.php .co3 {color: #0000cc; font-style: italic;}
.php .co4 {color: #009933; font-style: italic;}
.php .coMULTI {color: #666666; font-style: italic;}
.php .es0 {color: #000099; font-weight: bold;}
.php .es1 {color: #000099; font-weight: bold;}
.php .es2 {color: #660099; font-weight: bold;}
.php .es3 {color: #660099; font-weight: bold;}
.php .es4 {color: #006699; font-weight: bold;}
.php .es5 {color: #006699; font-weight: bold; font-style: italic;}
.php .es6 {color: #009933; font-weight: bold;}
.php .es_h {color: #000099; font-weight: bold;}
.php .br0 {color: #009900;}
.php .sy0 {color: #339933;}
.php .sy1 {color: #000000; font-weight: bold;}
.php .st0 {color: #0000ff;}
.php .st_h {color: #0000ff;}
.php .nu0 {color: #cc66cc;}
.php .nu8 {color: #208080;}
.php .nu12 {color: #208080;}
.php .nu19 {color:#800080;}
.php .me1 {color: #004000;}
.php .me2 {color: #004000;}
.php .re0 {color: #000088;}
.php .ln-xtra, .php li.ln-xtra, .php div.ln-xtra {background-color: #ffc;}
.php span.xtra { display:block; }
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for html4strict
* CSS class: , CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.html4strict .de1, .html4strict .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
.html4strict {font-family:monospace;}
.html4strict .imp {font-weight: bold; color: red;}
.html4strict li, .html4strict .li1 {font-weight: normal; vertical-align:top;}
.html4strict .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
.html4strict .li2 {font-weight: bold; vertical-align:top;}
.html4strict .kw2 {color: #000000; font-weight: bold;}
.html4strict .kw3 {color: #000066;}
.html4strict .es0 {color: #000099; font-weight: bold;}
.html4strict .br0 {color: #66cc66;}
.html4strict .sy0 {color: #66cc66;}
.html4strict .st0 {color: #ff0000;}
.html4strict .nu0 {color: #cc66cc;}
.html4strict .sc-1 {color: #808080; font-style: italic;}
.html4strict .sc0 {color: #00bbdd;}
.html4strict .sc1 {color: #ddbb00;}
.html4strict .sc2 {color: #009900;}
.html4strict .ln-xtra, .html4strict li.ln-xtra, .html4strict div.ln-xtra {background-color: #ffc;}
.html4strict span.xtra { display:block; }
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for css
* CSS class: , CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.css .de1, .css .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
.css {font-family:monospace;}
.css .imp {font-weight: bold; color: red;}
.css li, .css .li1 {font-weight: normal; vertical-align:top;}
.css .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
.css .li2 {font-weight: bold; vertical-align:top;}
.css .kw1 {color: #000000; font-weight: bold;}
.css .kw2 {color: #993333;}
.css .co1 {color: #a1a100;}
.css .co2 {color: #ff0000; font-style: italic;}
.css .coMULTI {color: #808080; font-style: italic;}
.css .es0 {color: #000099; font-weight: bold;}
.css .br0 {color: #00AA00;}
.css .sy0 {color: #00AA00;}
.css .st0 {color: #ff0000;}
.css .nu0 {color: #cc66cc;}
.css .re0 {color: #cc00cc;}
.css .re1 {color: #6666ff;}
.css .re2 {color: #3333ff;}
.css .re3 {color: #933;}
.css .ln-xtra, .css li.ln-xtra, .css div.ln-xtra {background-color: #ffc;}
.css span.xtra { display:block; }
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for java
* CSS class: , CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.java .de1, .java .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
.java {font-family:monospace;}
.java .imp {font-weight: bold; color: red;}
.java li, .java .li1 {font-weight: normal; vertical-align:top;}
.java .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;}
.java .li2 {font-weight: bold; vertical-align:top;}
.java .kw1 {color: #000000; font-weight: bold;}
.java .kw2 {color: #000066; font-weight: bold;}
.java .kw3 {color: #003399;}
.java .kw4 {color: #000066; font-weight: bold;}
.java .co1 {color: #666666; font-style: italic;}
.java .co2 {color: #006699;}
.java .co3 {color: #008000; font-style: italic; font-weight: bold;}
.java .coMULTI {color: #666666; font-style: italic;}
.java .es0 {color: #000099; font-weight: bold;}
.java .br0 {color: #009900;}
.java .sy0 {color: #339933;}
.java .st0 {color: #0000ff;}
.java .nu0 {color: #cc66cc;}
.java .me1 {color: #006633;}
.java .me2 {color: #006633;}
.java .ln-xtra, .java li.ln-xtra, .java div.ln-xtra {background-color: #ffc;}
.java span.xtra { display:block; }
</style>
</head>
<body>
<h1 id="top"><abbr title="Generic Syntax Highlighter">GeSHi</abbr> Documentation</h1>
<div class="header">
<p>Version 1.0.8.3</p>
<p><img src="http://qbnz.com/highlighter/images/geshi.png" alt="The GeSHi Logo" /></p>
<dl>
<dt>Authors:</dt>
<dd>&copy; 2004 - 2007&#160;<a href="mailto:nigel@geshi.org">Nigel McNie</a></dd>
<dd>&copy; 2007 - 2009&#160;<a href="mailto:BenBE@omorphia.de">Benny Baumann</a></dd>
<dd>&copy; 2008 - 2009&#160;<a href="mailto:mail@milianw.de">Milian Wolff</a></dd>
<dt><abbr title="Generic Syntax Highlighter">GeSHi</abbr> Website:</dt>
<dd><a href="http://qbnz.com/highlighter">http://qbnz.com/highlighter</a></dd>
</dl>
</div>
<p>This is the documentation for <abbr title="Generic Syntax Highlighter">GeSHi</abbr> - Generic Syntax Highlighter.</p>
<p>The most modern version of this document is available on the web -
go to <a href="http://qbnz.com/highlighter/documentation.php">http://qbnz.com/highlighter/documentation.php</a> to view it.</p>
<p>Any comments, questions, confusing points? Please <a href="#feedback">get in contact</a> with the developers! We
need all the information we can get to make the use of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> and everything related to it (including this documentation)
a breeze.</p>
<h2 id="contents">Contents</h2>
<div id="toc"><ul>
<li><a href="#introduction">1 Introduction</a><ul>
<li><a href="#features">1.1 Features</a></li>
<li><a href="#about-geshi">1.2 About <abbr title="Generic Syntax Highlighter">GeSHi</abbr></a></li>
<li><a href="#credits">1.3 Credits</a></li>
<li><a href="#feedback">1.4 Feedback</a></li>
</ul></li>
<li><a href="#the-basics">2 The Basics</a><ul>
<li><a href="#getting-geshi">2.1 Getting <abbr title="Generic Syntax Highlighter">GeSHi</abbr> work</a><ul>
<li><a href="#requirements">2.1.1 Requirements</a></li>
<li><a href="#downloading-geshi">2.1.2 Downloading <abbr title="Generic Syntax Highlighter">GeSHi</abbr></a></li>
<li><a href="#extracting-geshi">2.1.3 Extracting <abbr title="Generic Syntax Highlighter">GeSHi</abbr></a></li>
<li><a href="#installing-geshi">2.1.4 Installing <abbr title="Generic Syntax Highlighter">GeSHi</abbr></a></li>
</ul></li>
<li><a href="#basic-usage">2.2 Basic Usage</a></li>
</ul></li>
<li><a href="#advanced-features">3 Advanced Features</a><ul>
<li><a href="#the-code-container">3.1 The Code Container</a></li>
<li><a href="#line-numbers">3.2 Line Numbers</a><ul>
<li><a href="#enabling-line-numbers">3.2.1 Enabling Line Numbers</a></li>
<li><a href="#styling-line-numbers">3.2.2 Styling Line Numbers</a></li>
<li><a href="#starting-line-numbers">3.2.3 Choosing a Start Number</a></li>
</ul></li>
<li><a href="#using-css-classes">3.3 Using <abbr title="Cascading Style Sheets">CSS</abbr> Classes</a><ul>
<li><a href="#enabling-css-classes">3.3.1 Enabling <abbr title="Cascading Style Sheets">CSS</abbr> Classes</a></li>
<li><a href="#setting-css-class-id">3.3.2 Setting the <abbr title="Cascading Style Sheets">CSS</abbr> class and ID</a></li>
<li><a href="#getting-stylesheet">3.3.3 Getting the stylesheet for your code</a></li>
<li><a href="#using-an-external-stylesheet">3.3.4 Using an External Stylesheet</a></li>
</ul></li>
<li><a href="#changing-styles">3.4 Changing Styles</a><ul>
<li><a href="#the-overall-styles">3.4.1 The Overall Styles</a></li>
<li><a href="#line-number-styles">3.4.2 Line Number Styles</a></li>
<li><a href="#setting-keyword-styles">3.4.3 Setting Keyword Styles</a></li>
<li><a href="#setting-comment-styles">3.4.4 Setting Comment Styles</a></li>
<li><a href="#setting-other-styles">3.4.5 Setting Other Styles</a></li>
</ul></li>
<li><a href="#case-caps">3.5 Case Sensitivity and Auto Casing</a><ul>
<li><a href="#auto-caps-nocaps">3.5.1 Auto-Caps/NoCaps</a></li>
<li><a href="#setting-case-sensitivity">3.5.2 Setting Case Sensitivity</a></li>
</ul></li>
<li><a href="#changing-config">3.6 Changing the Source, Language, Config Options</a><ul>
<li><a href="#changing-the-source">3.6.1 Changing the Source Code</a></li>
<li><a href="#changing-the-language">3.6.2 Changing the Language</a></li>
<li><a href="#changing-the-path">3.6.3 Changing the Language Path</a></li>
<li><a href="#changing-the-charset">3.6.4 Changing the Character Set</a></li>
</ul></li>
<li><a href="#error-handling">3.7 Error Handling</a></li>
<li><a href="#disabling-lexics">3.8 Disabling styling of some Lexics</a></li>
<li><a href="#setting-tab-width">3.9 Setting the Tab Width</a></li>
<li><a href="#using-strict-mode">3.10 Using Strict Mode</a></li>
<li><a href="#adding-removing-keywords">3.11 Adding/Removing Keywords</a><ul>
<li><a href="#adding-a-keyword">3.11.1 Adding a Keyword</a></li>
<li><a href="#removing-a-keyword">3.11.2 Removing a Keyword</a></li>
<li><a href="#adding-a-keyword-group">3.11.3 Adding a Keyword Group</a></li>
<li><a href="#removing-a-keyword-group">3.11.4 Removing a Keyword Group</a></li>
</ul></li>
<li><a href="#headers-and-footers">3.12 Headers and Footers for Your Code</a><ul>
<li><a href="#keyword-substitution">3.12.1 Keyword Substitution</a></li>
<li><a href="#setting-header-content">3.12.2 Setting Header Content</a></li>
<li><a href="#setting-footer-content">3.12.3 Setting Footer Content</a></li>
<li><a href="#styling-header-content">3.12.4 Styling Header Content</a></li>
<li><a href="#styling-footer-content">3.12.5 Styling Footer Content</a></li>
</ul></li>
<li><a href="#keyword-urls">3.13 Keyword URLs</a><ul>
<li><a href="#setting-a-url">3.13.1 Setting a URL for a Keyword Group</a></li>
<li><a href="#disabling-urls">3.13.2 Disabling a URL for a Keyword Group</a></li>
<li><a href="#disabling-all-urls">3.13.3 Disabling all URLs for Keywords</a></li>
<li><a href="#styling-links">3.13.4 Styling Links</a></li>
<li><a href="#using-targets">3.13.5 Setting the Link Target</a></li>
</ul></li>
<li><a href="#using-contextual-importance">3.14 Using Contextual Importance</a></li>
<li><a href="#highlighting-special-lines-extra">3.15 Highlighting Special Lines &#8220;Extra&#8221;</a><ul>
<li><a href="#specifying-lines-to-highlight-extra">3.15.1 Specifying the Lines to Highlight Extra</a></li>
<li><a href="#styles-for-highlighted-lines">3.15.2 Styles for the Highlighted Lines</a></li>
</ul></li>
<li><a href="#adding-ids-to-each-line">3.16 Adding IDs to Each Line</a></li>
<li><a href="#getting-the-time-of-styling">3.17 Getting the Time of Styling</a></li>
</ul></li>
<li><a href="#language-files">4 Language Files</a><ul>
<li><a href="#language-file-example">4.1 An Example Language File</a></li>
<li><a href="#language-file-conventions">4.2 Language File Conventions</a></li>
<li><a href="#language-file-sections">4.3 Language File Sections</a><ul>
<li><a href="#language-file-header">4.3.1 The Header</a></li>
<li><a href="#language-file-start-indices">4.3.2 The First Indices</a></li>
<li><a href="#language-file-keywords">4.3.3 Keywords</a></li>
<li><a href="#language-file-symbols-case">4.3.4 Symbols and Case Sensitivity</a></li>
<li><a href="#language-file-styles">4.3.5 Styles for your Language File</a></li>
<li><a href="#language-file-urls">4.3.6 URLs for Functions</a></li>
<li><a href="#language-file-numbers-support">4.3.7 Number Highlighting Support</a></li>
<li><a href="#language-file-oo-support">4.3.8 Object Orientation Support</a></li>
<li><a href="#language-file-regexps">4.3.9 Using Regular Expressions</a></li>
<li><a href="#language-file-strict-mode">4.3.10 Contextual Highlighting and Strict Mode</a></li>
<li><a href="#language-file-parser-control">4.3.11 Special Parser Settings (Experimental)</a></li>
<li><a href="#language-file-tidying-up">4.3.12 Tidying Up</a></li>
</ul></li>
<li><a href="#lang-validation">4.4 Validating your language file</a></li>
</ul></li>
<li><a href="#method-constant-reference">5 Method/Constant Reference</a></li>
</ul>
</div>
<h2 id="introduction">1 Introduction</h2><div class="nav"><a href="#features">Next</a></div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> is exactly what the acronym stands for: a <strong>Generic Syntax Highlighter</strong>. 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 - <abbr title="Generic Syntax Highlighter">GeSHi</abbr> can
highlight it! <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is extremely customisable - the same source can be highlighted
multiple times in multiple ways - the same source even with a different language.
<abbr title="Generic Syntax Highlighter">GeSHi</abbr> outputs XHTML strict compliant code<sup id="fnref:xhtml-strict"><a href="#fn:xhtml-strict" rel="footnote">1</a></sup>, and can
make use of <abbr title="Cascading Style Sheets">CSS</abbr> to save on the amount of output. And what is the cost for all of this? You need
<a href="http://php.net"><abbr title="PHP: HTML Preprocessor">PHP</abbr></a>. That&#8217;s all!</p>
<h3 id="features">1.1 Features</h3><div class="nav"><a href="#introduction">Previous</a> | <a href="#introduction">Top</a> | <a href="#about-geshi">Next</a></div>
<p>Here are some of the standout features of <abbr title="Generic Syntax Highlighter">GeSHi</abbr>:</p>
<dl>
<dt>Programmed in <abbr title="PHP: HTML Preprocessor">PHP</abbr>:</dt>
<dd><abbr title="Generic Syntax Highlighter">GeSHi</abbr> is coded entirely in <abbr title="PHP: HTML Preprocessor">PHP</abbr>. This means that where ever you have <abbr title="PHP: HTML Preprocessor">PHP</abbr>, you
can have <abbr title="Generic Syntax Highlighter">GeSHi</abbr>! Almost any free webhost supports <abbr title="PHP: HTML Preprocessor">PHP</abbr>, and <abbr title="Generic Syntax Highlighter">GeSHi</abbr> works fine with <abbr title="PHP: HTML Preprocessor">PHP</abbr> > 4.3.0<sup id="fnref:php-version-note"><a href="#fn:php-version-note" rel="footnote">2</a></sup>.</dd>
<dt>Support for many languages:</dt>
<dd><abbr title="Generic Syntax Highlighter">GeSHi</abbr> comes with more than <em>100</em> languages, including <abbr title="PHP: HTML Preprocessor">PHP</abbr>, <abbr title="Hypertext Markup Language">HTML</abbr>, <abbr title="Cascading Style Sheets">CSS</abbr>, Java, C, Lisp, <abbr title="Extensible Markup Language">XML</abbr>, Perl, Python,
<abbr title="Assembly language">ASM</abbr> and many more!</dd>
<dt>XHTML compliant output:</dt>
<dd><abbr title="Generic Syntax Highlighter">GeSHi</abbr> produces XHTML compliant output, using stylesheets, so you need not worry about
<abbr title="Generic Syntax Highlighter">GeSHi</abbr> ruining your claims to perfection in the standards department ;)</dd>
<dt>Highly customisable:</dt>
<dd><abbr title="Generic Syntax Highlighter">GeSHi</abbr> allows you to change the style of the output on the fly, use <abbr title="Cascading Style Sheets">CSS</abbr> classes or not, use an external
stylesheet or not, use line numbering, change the case of output keywords&#8230; the list goes on and on!</dd>
<dt>Flexible:</dt>
<dd>Unfortunately, <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is quite load/time intensive for large blocks of code. However, you want speed?
Turn off any features you don&#8217;t like, pre-make a stylesheet and use <abbr title="Cascading Style Sheets">CSS</abbr> classes to reduce the amount of output and more -
it&#8217;s easy to strike a balance that suits you.</dd>
</dl>
<p>This is just a taste of what you get with <abbr title="Generic Syntax Highlighter">GeSHi</abbr> - the best syntax highlighter for the web in the world!</p>
<h3 id="about-geshi">1.2 About <abbr title="Generic Syntax Highlighter">GeSHi</abbr></h3><div class="nav"><a href="#features">Previous</a> | <a href="#introduction">Top</a> | <a href="#credits">Next</a></div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> started as a mod for the <a href="http://phpbb.net"><abbr title="PHP Burning Board">phpBB</abbr></a> 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<sup id="fnref:phpbb-note"><a href="#fn:phpbb-note" rel="footnote">3</a></sup> - and hopefully for many forum systems, blogs and other web-based systems.</p>
<p>Several systems are using <abbr title="Generic Syntax Highlighter">GeSHi</abbr> now, including:</p>
<ul>
<li><a href="http://www.splitbrain.org/docuwiki/">Dokuwiki</a> - An advanced wiki engine</li>
<li><a href="http://gtk.php.net/">gtk.php.net</a> - Their manual uses <abbr title="Generic Syntax Highlighter">GeSHi</abbr> for syntax highlighting</li>
<li><a href="http://www.wordpress.org/">WordPress</a> - A powerful blogging system<sup id="fnref:plugin-only"><a href="#fn:plugin-only" rel="footnote">4</a></sup></li>
<li><a href="http://www.php-fusion.co.uk/"><abbr title="PHP: HTML Preprocessor">PHP</abbr>-Fusion</a> - A constantly evolving CMS</li>
<li><a href="http://cypreess.dione.cc/sqlm">SQL Manager</a> - A Postgres DBAL</li>
<li><a href="http://www.mamboserver.com/">Mambo</a> - A popular open source CMS</li>
<li><a href="http://www.mediawiki.org/">MediaWiki</a> - A leader in Wikis[^plugin-only]</li>
<li><a href="http://www.tikiwiki.org/">TikiWiki</a> - A megapowerful Wiki/CMS</li>
<li><a href="http://www.tikipro.org/">TikiPro</a> - Another powerful Wiki based on TikiWiki</li>
<li><a href="http://www.wikkawiki.org/">WikkaWiki</a> - A flexible and lightweight Wiki engine</li>
<li><a href="http://robloach.net/projects/phpscripts/rweb/">RWeb</a> - A site-building tool</li>
</ul>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> is the original work of <a href="mailto:nigel@geshi.org">Nigel McNie</a>. The project was later handed over to <a href="mailto:BenBE@omorphia.de">Benny Baumann</a>.
Others have helped with aspects of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> also, they&#8217;re mentioned in the <a href="THANKS"><code>THANKS</code></a> file.</p>
<h3 id="credits">1.3 Credits</h3><div class="nav"><a href="#about-geshi">Previous</a> | <a href="#introduction">Top</a> | <a href="#feedback">Next</a></div>
<p>Many people have helped out with <abbr title="Generic Syntax Highlighter">GeSHi</abbr>, whether by creating language files, submitting bug
reports, suggesting new ideas or simply pointing out a new idea or something I&#8217;d missed. All
of these people have helped to build a better <abbr title="Generic Syntax Highlighter">GeSHi</abbr>, you can see them in the <a href="THANKS"><code>THANKS</code></a>
file.</p>
<p>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&#8217;t get my head around, or suggest a new feature, or even port
<abbr title="Generic Syntax Highlighter">GeSHi</abbr> to anothe language? There&#8217;s lots you can do to help out, and I need it all :)</p>
<h3 id="feedback">1.4 Feedback</h3><div class="nav"><a href="#credits">Previous</a> | <a href="#introduction">Top</a> | <a href="#the-basics">Next</a></div>
<p>I need your feedback! <em>ANY</em>thing you have to say is fine, whether it be a query,
congratulations, a bug report or complaint, I don&#8217;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:</p>
<ul>
<li><strong>E-mail:</strong> <a href="mailto:nigel@geshi.org">Nigel McNie</a>, <a href="mailto:BenBE@omorphia.de">Benny Baumann</a> or better yet: use the <a href="http://lists.sourceforge.net/mailman/listinfo/geshi-users">geshi-users</a> mailinglist</li>
<li><strong>Forums:</strong> <a href="http://sourceforge.net/forum?group_id=114997">Sourceforge.net Forums</a></li>
<li><strong>IRC:</strong> <a href="irc://irc.freenode.net/geshi">#geshi</a> on <a href="http://freenode.net">Freenode</a></li>
</ul>
<p>Remember, any help I am grateful for :)</p>
<h2 id="the-basics">2 The Basics</h2><div class="nav"><a href="#feedback">Previous</a> | <a href="#getting-geshi">Next</a></div>
<p>In this section, you&#8217;ll learn a bit about <abbr title="Generic Syntax Highlighter">GeSHi</abbr>, how it works and what it uses, how to install it and how to use
it to perform basic highlighting.</p>
<h3 id="getting-geshi">2.1 Getting <abbr title="Generic Syntax Highlighter">GeSHi</abbr> work</h3><div class="nav"><a href="#the-basics">Previous</a> | <a href="#the-basics">Top</a> | <a href="#requirements">Next</a></div>
<p>If you&#8217;re reading this and don&#8217;t have <abbr title="Generic Syntax Highlighter">GeSHi</abbr>, that&#8217;s a problem ;). So, how do you get your hands on it?</p>
<h4 id="requirements">2.1.1 Requirements</h4><div class="nav"><a href="#getting-geshi">Previous</a> | <a href="#getting-geshi">Top</a> | <a href="#downloading-geshi">Next</a></div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> requires the following to be installable:</p>
<ul>
<li><strong><a href="http://php.net"><abbr title="PHP: HTML Preprocessor">PHP</abbr></a></strong>. It&#8217;s untested with anything other below 4.4.X. I hope to extend this range soon. I see no reason why
it won&#8217;t work with any version of <abbr title="PHP: HTML Preprocessor">PHP</abbr> above 4.3.0.</li>
<li><strong>Approximately 2 megabytes of space</strong>. The actual script is small - around 150K - but most of the size comes
from the large number of language files (over 100!). If you&#8217;re pushed for space, make sure you don&#8217;t upload to
your server the <code>docs/</code> or <code>contrib/</code> directory, and you may want to leave out any language files that don&#8217;t
take your fancy either.</li>
</ul>
<p>As you can see, the requirements are very small. If <abbr title="Generic Syntax Highlighter">GeSHi</abbr> does NOT work for you in a particular version of <abbr title="PHP: HTML Preprocessor">PHP</abbr>, let
me know why and I&#8217;ll fix it.</p>
<h4 id="downloading-geshi">2.1.2 Downloading <abbr title="Generic Syntax Highlighter">GeSHi</abbr></h4><div class="nav"><a href="#requirements">Previous</a> | <a href="#getting-geshi">Top</a> | <a href="#extracting-geshi">Next</a></div>
<p>There are several ways to get a copy of <abbr title="Generic Syntax Highlighter">GeSHi</abbr>. The first and easiest way of all is
visiting <a href="http://qbnz.com/highlighter/downloads.php">http://qbnz.com/highlighter/downloads.php</a> to obtain the latest version.
This is suitable especially when you plan on using <abbr title="Generic Syntax Highlighter">GeSHi</abbr> on an production website
or otherwise need a stable copy for flawless operation.</p>
<p>If you are somewhat more sophisticated or need a feature just recently implemented
you might consider getting <abbr title="Generic Syntax Highlighter">GeSHi</abbr> by downloading via SVN. There are multiple ways
for doing so and each one has its own advantages and disadvantages. Let&#8217;s cover
the various locations in the SVN you might download from:</p>
<ul>
<li><a href="https://geshi.svn.sourceforge.net/svnroot/geshi/tags/">https://geshi.svn.sourceforge.net/svnroot/geshi/tags/</a>:<br />
This directory holds all previous releases of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> each as a subdirectory. By downloading from here you can test your code with various old versions
in case something has been broken recently.</li>
<li><a href="https://geshi.svn.sourceforge.net/svnroot/geshi/branches/RELEASE_1_0_X_STABLE/geshi-1.0.X/src/">https://geshi.svn.sourceforge.net/svnroot/geshi/branches/RELEASE_1_0_X_STABLE/geshi-1.0.X/src/</a>:<br />
This directory is the right place for you if you want to have reasonably current versions of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> but need something that is stable. This directory
is updated once in a while between updates whenever there&#8217;s something new but which is already reasonably stable. This branch is used to form the
actual release once the work is done.</li>
<li><a href="https://geshi.svn.sourceforge.net/svnroot/geshi/trunk/geshi-1.0.X/src/">https://geshi.svn.sourceforge.net/svnroot/geshi/trunk/geshi-1.0.X/src/</a>:<br />
This directory is the working directory where every new feature, patch or improvement is committed to. This directory is updated regularly, but is not
guaranteed to be tested and stable at all times. With this version you&#8217;ll always get the latest version of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> out there, but beware of bugs! There
will be loads of them here! So this is absolutely <strong>not recommended</strong> for productive use!</li>
</ul>
<p>If you have choosen the right SVN directory for you do a quick
<code class="highlighted bash"><span class="kw2">svn</span> <span class="kw2">co</span> <span class="re1">$SVNPATH</span> geshi</code> where <code class="highlighted bash"><span class="re1">$SVNPATH</span></code> is one of the above paths and your desired version of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> will be
downloaded into an subdirectory called &#8220;geshi&#8221;. If you got a version of <abbr title="Generic Syntax Highlighter">GeSHi</abbr>
you can go on installing as shown below.</p>
<h4 id="extracting-geshi">2.1.3 Extracting <abbr title="Generic Syntax Highlighter">GeSHi</abbr></h4><div class="nav"><a href="#downloading-geshi">Previous</a> | <a href="#getting-geshi">Top</a> | <a href="#installing-geshi">Next</a></div>
<p>Packages come in <code>.zip</code>, <code>.tar.gz</code> and <code>.tar.bz2</code> format, so there&#8217;s no complaining about whether it&#8217;s available for
you. *nix users probably want <code>.tar.gz</code> or <code>.tar.bz2</code> and windows users probably want <code>.zip</code>.
And those lucky to download it directly from SVN don&#8217;t even need to bother extracting <abbr title="Generic Syntax Highlighter">GeSHi</abbr>.</p>
<p>To extract <abbr title="Generic Syntax Highlighter">GeSHi</abbr> in Linux (<code>.tar.gz</code>):</p>
<ol>
<li>Open a shell</li>
<li><code class="highlighted bash"><span class="kw3">cd</span></code> to the directory where the archive lies</li>
<li>Type <code class="highlighted bash"><span class="kw2">tar</span> <span class="re5">-xzvf</span> <span class="br0">&#91;</span>filename<span class="br0">&#93;</span></code> where <code>[filename]</code> is the name of the archive (typically <code>GeSHi-1.X.X.tar.gz</code>)</li>
<li><abbr title="Generic Syntax Highlighter">GeSHi</abbr> will be extracted to its own directory</li>
</ol>
<p>To extract <abbr title="Generic Syntax Highlighter">GeSHi</abbr> in Windows (<code>.zip</code>):</p>
<ol>
<li>Open Explorer</li>
<li>Navigate to the directory where the archive lies</li>
<li>Extract the archive. The method you use will depend on your configuration. Some people can right-click upon
the archive and select &#8220;Extract&#8221; from there, others may have to drag the archive and drop it upon an extraction program.</li>
</ol>
<p>To extract from <code>.zip</code> you&#8217;ll need an unzipping program - <code class="highlighted bash"><span class="kw2">unzip</span></code> in Linux, or 7-Zip, WinZip, WinRAR or similar for Windows.</p>
<h4 id="installing-geshi">2.1.4 Installing <abbr title="Generic Syntax Highlighter">GeSHi</abbr></h4><div class="nav"><a href="#extracting-geshi">Previous</a> | <a href="#getting-geshi">Top</a> | <a href="#basic-usage">Next</a></div>
<p>Installing <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is a snap, even for those most new to <abbr title="PHP: HTML Preprocessor">PHP</abbr>. There&#8217;s no tricks involved. Honest!</p>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> is nothing more than a <abbr title="PHP: HTML Preprocessor">PHP</abbr> class with related language support files. Those of you familiar with <abbr title="PHP: HTML Preprocessor">PHP</abbr> 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. <strong>Remember this path</strong> for later.</p>
<p>If you don&#8217;t know what an include path is, don&#8217;t worry. Simply copy <abbr title="Generic Syntax Highlighter">GeSHi</abbr> to your webserver. So for example, say your
site is at <code>http://mysite.com/myfolder</code>, you can copy <abbr title="Generic Syntax Highlighter">GeSHi</abbr> to your site so the directory structure is like this:</p>
<pre><code>http://mysite.com/myfolder/geshi/[language files]
http://mysite.com/myfolder/geshi.php
</code></pre>
<p>Or you can put it in any subdirectory you like:</p>
<pre><code>http://mysite.com/myfolder/includes/geshi/[language files]
http://mysite.com/myfolder/includes/geshi.php
</code></pre>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>When using <abbr title="Generic Syntax Highlighter">GeSHi</abbr> on a live site, the only directory required is the <code>geshi/</code> subdirectory. Both <code>contrib/</code> and <code>docs/</code> 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.</p>
</div>
<h3 id="basic-usage">2.2 Basic Usage</h3><div class="nav"><a href="#installing-geshi">Previous</a> | <a href="#the-basics">Top</a> | <a href="#advanced-features">Next</a></div>
<p>Use of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is very easy. Here&#8217;s a simple example:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span>9
<span class="xtra li2"><span class="de2">10</span></span>11
<span class="xtra li2"><span class="de2">12</span></span>13
<span class="xtra li2"><span class="de2">14</span></span>15
<span class="xtra li2"><span class="de2">16</span></span>17
<span class="xtra li2"><span class="de2">18</span></span>19
<span class="xtra li2"><span class="de2">20</span></span>21
<span class="xtra li2"><span class="de2">22</span></span>23
<span class="xtra li2"><span class="de2">24</span></span>25
<span class="xtra li2"><span class="de2">26</span></span>27
<span class="xtra li2"><span class="de2">28</span></span></pre></td><td class="de1"><pre class="de1"><span class="co1">//</span>
<span class="xtra li2"><span class="de2"><span class="co1">// Include the GeSHi library</span></span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2"><span class="kw1">include_once</span> <span class="st_h">'geshi.php'</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="co1">//</span></span></span><span class="co1">// Define some source to highlight, a language to use</span>
<span class="xtra li2"><span class="de2"><span class="co1">// and the path to the language files</span></span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$source</span> <span class="sy0">=</span> <span class="st_h">'$foo = 45;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">for ( $i = 1; $i &lt; $foo; $i++ )</span></span></span><span class="st_h">{</span>
<span class="xtra li2"><span class="de2"><span class="st_h"> &nbsp;echo &quot;$foo\n&quot;;</span></span></span><span class="st_h"> &nbsp;--$foo;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">}'</span><span class="sy0">;</span></span></span><span class="re0">$language</span> <span class="sy0">=</span> <span class="st_h">'php'</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2"><span class="co1">// Create a GeSHi object</span></span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="re0">$language</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2"><span class="co1">// And echo the result!</span></span></span><span class="co1">//</span>
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>As you can see, there&#8217;s only three really important lines:</p>
<p><code class="highlighted php"><span class="kw1">include_once</span><span class="br0">&#40;</span><span class="st_h">'geshi.php'</span><span class="br0">&#41;</span></code></p>
<p>This line includes the <abbr title="Generic Syntax Highlighter">GeSHi</abbr> class for use</p>
<p><code class="highlighted php"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="re0">$language</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>This line creates a new <abbr title="Generic Syntax Highlighter">GeSHi</abbr> object, holding the source and the language you want to use for highlighting.</p>
<p><code class="highlighted php"><span class="kw1">echo</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>This line spits out the result :)</p>
<p>So as you can see, simple usage of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is really easy. Just create a new <abbr title="Generic Syntax Highlighter">GeSHi</abbr> object and get the code!</p>
<p>Since version 1.0.2, there is a function included with <abbr title="Generic Syntax Highlighter">GeSHi</abbr> called <code>geshi_highlight</code>. This behaves exactly as the php
function <code class="highlighted php"><span class="kw3">highlight_string</span><span class="br0">&#40;</span><span class="br0">&#41;</span></code> 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:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span>9
<span class="xtra li2"><span class="de2">10</span></span>11
<span class="xtra li2"><span class="de2">12</span></span>13
<span class="xtra li2"><span class="de2">14</span></span>15
<span class="xtra li2"><span class="de2">16</span></span>17
<span class="xtra li2"><span class="de2">18</span></span>19
<span class="xtra li2"><span class="de2">20</span></span>21
</pre></td><td class="de1"><pre class="de1"><span class="co1">// Simply echo the highlighted code</span>
<span class="xtra li2"><span class="de2">geshi_highlight<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'php'</span><span class="sy0">,</span> <span class="re0">$path</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="co1">// Get the code back, for use later</span></span></span><span class="re0">$code</span> <span class="sy0">=</span> geshi_highlight<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'java'</span><span class="sy0">,</span> <span class="re0">$path</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// Check if there is an error with parsing this code</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><a href="http://www.php.net/ob_start"><span class="kw3">ob_start</span></a><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$result</span> <span class="sy0">=</span> geshi_highlight<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'perl'</span><span class="sy0">,</span> <span class="re0">$path</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span><span class="re0">$code</span> <span class="sy0">=</span> <a href="http://www.php.net/ob_get_contents"><span class="kw3">ob_get_contents</span></a><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><a href="http://www.php.net/ob_end_clean"><span class="kw3">ob_end_clean</span></a><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="kw1">if</span> <span class="br0">&#40;</span> <span class="sy0">!</span><span class="re0">$result</span> <span class="br0">&#41;</span></span></span><span class="br0">&#123;</span>
<span class="xtra li2"><span class="de2">&nbsp; &nbsp; <span class="co1">// There was an error with highlighting...</span></span></span><span class="br0">&#125;</span>
<span class="xtra li2"><span class="de2"><span class="kw1">else</span></span></span><span class="br0">&#123;</span>
<span class="xtra li2"><span class="de2">&nbsp; &nbsp; <span class="co1">// All OK :)</span></span></span><span class="br0">&#125;</span></pre></td></tr></tbody></table>
<p>However, these are really simple examples and doesn&#8217;t even begin to cover all the advanced features of <abbr title="Generic Syntax Highlighter">GeSHi</abbr>.
If you want to learn more, continue on to section 3: Advanced Features.</p>
<h2 id="advanced-features">3 Advanced Features</h2><div class="nav"><a href="#basic-usage">Previous</a> | <a href="#the-code-container">Next</a></div>
<p>This section documents the advanced features of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> - strict mode, using <abbr title="Cascading Style Sheets">CSS</abbr> classes, changing styles on the fly,
disabling highlighting of some things and more.</p>
<p>In this section there are many code snippets. For all of these, you should assume that the <abbr title="Generic Syntax Highlighter">GeSHi</abbr> library has been
included, and a <abbr title="Generic Syntax Highlighter">GeSHi</abbr> object has been created and is referenced by the variable <code class="highlighted php"><span class="re0">$geshi</span></code>. Normally, the
source, language and path used are arbitary.</p>
<h3 id="the-code-container">3.1 The Code Container</h3><div class="nav"><a href="#advanced-features">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#line-numbers">Next</a></div>
<p>The <strong>Code Container</strong> has a fundamental effect on the layout of your code before you even begin to style. What is the
Code Container? It&#8217;s the bit of markup that goes around your code to contain it. By default your code is surrounded
by a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code>, but you can also specify a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code>.</p>
<p>The <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> header is the default. If you&#8217;re familiar with <abbr title="Hypertext Markup Language">HTML</abbr> you&#8217;ll know that whitespace is rendered
&#8220;as is&#8221; by a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> element. The advantage for you is that if you use <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> the whitespace
you use will appear pretty much exactly how it is in the source, and what&#8217;s more <abbr title="Generic Syntax Highlighter">GeSHi</abbr> won&#8217;t have to add a whole
lot of <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">br</span> <span class="sy0">/</span>&gt;</span></code>&#8217;s and non-breaking spaces (<code class="highlighted html4strict"><span class="sc1">&amp;nbsp;</span></code>) to your code to indent it. This saves
you source code (and your valuable visitors waiting time and your bandwidth).</p>
<p>But if you don&#8217;t like <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> 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 <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> instead. A <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> will
result in more source - <abbr title="Generic Syntax Highlighter">GeSHi</abbr> will have to insert whitespace markup - but in return you can wrap long lines of code
that would otherwise have your browser&#8217;s horizontal scrollbar appear. Of course with <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> you can
<em>not</em> wrap lines if you please. The highlighter demo at the <a href="http://qbnz.com/highlighter"><abbr title="Generic Syntax Highlighter">GeSHi</abbr> home page</a> uses the <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code>
approach for this reason.</p>
<p>At this stage there isn&#8217;t an option to wrap the code in <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">code</span>&gt;</span></code> tags (unless you use the function
<code>geshi_highlight</code>), partly because of the inconsistent and unexpected ways stuff in <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">code</span>&gt;</span></code> tags is
highlighted. Besides, <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">code</span>&gt;</span></code> is an inline element. But this may become an option in future versions.</p>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.7.2 there is a new header type, that specifies that the code should not be wrapped in anything at all.</p>
<p>Another requested addition has been made in <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.7.20 to force <abbr title="Generic Syntax Highlighter">GeSHi</abbr> to create a block around the highlighted
source even if this wasn&#8217;t necessary, thus styles that are applied to the output of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> can directly influence
the code only even if headers and footers are present.</p>
<p>To change/set the header to use, you call the <strong><code class="highlighted php">set_header_type<span class="br0">&#40;</span><span class="br0">&#41;</span></code></strong> method. It has one required argument which
defines the container type. Available are:</p>
<dl>
<dt><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_header_type</span><span class="br0">&#40;</span>GESHI_HEADER_DIV<span class="br0">&#41;</span><span class="sy0">;</span></code></dt>
<dd>
<p>Puts a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> around both, code and linenumbers. Whitespace is converted to <code class="highlighted html4strict"><span class="sc1">&amp;nbsp;</span></code>
sequences (i.e. one whitespace and the html entity of a non-breaking whitespace) to keep your indendation level
in tact. Tabs are converted as well and you can manually <a href="#setting-tab-width">define the tab-width</a>. Lines are automatically wrapped.
Linenumbers are created using an ordered list.</p>
</dd>
<dt><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_header_type</span><span class="br0">&#40;</span>GESHI_HEADER_PRE<span class="br0">&#41;</span><span class="sy0">;</span></code></dt>
<dd>
<p>Wraps code and linenumbers in a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> container. This way whitespace is kept as-is and thus
this header produces less overhead then the <code>GESHI_HEADER_DIV</code> header type. Since linenumbers are still
created using an ordered list this header type produces <strong>invalid <abbr title="Hypertext Markup Language">HTML</abbr></strong>.</p>
</dd>
<dt><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_header_type</span><span class="br0">&#40;</span>GESHI_HEADER_PRE_VALID<span class="br0">&#41;</span><span class="sy0">;</span></code></dt>
<dd><em><small>Available since 1.0.8</small></em></dd>
<dd>
<p>When linenumbers are disabled, this behaves just like <code>GESHI_HEADER_PRE</code>. In the other case though, a
<code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> is used to wrap the code and linenumbers and the <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> is put inside the list
items (<code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">li</span>&gt;</span></code>). This means slightly larger <abbr title="Hypertext Markup Language">HTML</abbr> output compared to <code>GESHI_HEADER_PRE</code>, but the
output is <strong>valid <abbr title="Hypertext Markup Language">HTML</abbr></strong>.</p>
</dd>
<dt><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_header_type</span><span class="br0">&#40;</span>GESHI_HEADER_PRE_TABLE<span class="br0">&#41;</span><span class="sy0">;</span></code></dt>
<dd><em><small>Available since 1.0.8</small></em></dd>
<dd>
<p>Once again a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> tag wraps the output. This time though no ordered list is used to create an ordered list,
but instead we use a table with two cells in a single row. The left cell contains a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> tag which holds all
linenumbers. The second cell holds the highlighted code, also wrapped in a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> tag, just like with
<code>GESHI_HEADER_PRE</code>.</p>
</dd>
<dd>
<p>This produces <strong>valid <abbr title="Hypertext Markup Language">HTML</abbr></strong> and works around the nasty selection behaviour of Firefox and other Gecko based
browsers, see <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=1651996&amp;group_id=114997&amp;atid=670231">SF#1651996</a> for more information.</p>
</dd>
<dt><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_header_type</span><span class="br0">&#40;</span>GESHI_HEADER_NONE<span class="br0">&#41;</span><span class="sy0">;</span></code></dt>
<dd><em><small>Available since 1.0.7.2</small></em></dd>
<dd>
<p>No wrapper is added.</p>
</dd>
</dl>
<p>Those are the only arguments you should pass to <code class="highlighted php">set_header_type</code>. Passing anything else may cause inconsistencies
in what is used as the Code Container (although it <em>should</em> simply use a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code>). Better not to risk it.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>GESHI_HEADER_DIV, GESHI_HEADER_PRE, etc. are <em>constants</em>, so don&#8217;t put them in strings!</p>
</div>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>The default styles for the <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> and <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> <em>will be different</em>, especially if you use
line numbers!</p>
<p>I have found that a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> results in code that is smaller than for that of a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code>, you
should rectify this difference by using <strong><code class="highlighted php">set_overall_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code></strong> if you need to. But be aware of this
difference for if you are changing the header type!</p>
</div>
<h3 id="line-numbers">3.2 Line Numbers</h3><div class="nav"><a href="#the-code-container">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#enabling-line-numbers">Next</a></div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> has the ability to add line numbers to your code (see the demo available at <a href="http://qbnz.com/highlighter/demo.php">http://qbnz.com/highlighter/demo.php</a>
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.</p>
<p>There are multiple methods for highlighting line numbers, but none of them is perfect. Of the various ways to highlight
line numbers <abbr title="Generic Syntax Highlighter">GeSHi</abbr> itself implements 2 different approaches, but allows you
by the way it generates the code to do the line numbers yourself if necessary - but more on this case later.</p>
<p>The easiest approach is using the <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">ol</span>&gt;</span></code>-tag for generating the line numbers, but
even though this is the easiest one there&#8217;s a big drawback with this one when
using Gecko-engine based browsers like Firefox or Konqueror. In these browsers
this approach will select the line numbers along with the code or will include extra markup in the selection.</p>
<p>The other approach has been implemented in the 1.0.8 release of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> with the <code class="highlighted php">GESHI_HEADER_PRE_TABLE</code> header type.
When using this header type the line numbers are rendered apart from the source
in a table cell while the actual source is formatted as if the <code class="highlighted php">GESHI_HEADER_PRE</code> header had been used.
This approach works with Firefox and other Gecko-based browsers so far although extreme care
has to be taken when applying styles to your source as Windows has some fonts
where bold font is of different height than normal or italic text of the same fontface.</p>
<h4 id="enabling-line-numbers">3.2.1 Enabling Line Numbers</h4><div class="nav"><a href="#line-numbers">Previous</a> | <a href="#line-numbers">Top</a> | <a href="#styling-line-numbers">Next</a></div>
<p>To highlight a source with line numbers, you call the <code class="highlighted php">enable_line_numbers<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_line_numbers</span><span class="br0">&#40;</span><span class="re0">$flag</span><span class="br0">&#41;</span><span class="sy0">;</span></code>
Where <code class="highlighted php"><span class="re0">$flag</span></code> is one of the following:</p>
<ul>
<li><code>GESHI_NORMAL_LINE_NUMBERS</code> - Use normal line numbering</li>
<li><code>GESHI_FANCY_LINE_NUMBERS</code> - Use fancy line numbering</li>
<li><code>GESHI_NO_LINE_NUMBERS</code> - Disable line numbers (default)</li>
</ul>
<p>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 n<sup>th</sup> line number. You change the value of n (default 5):</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_line_numbers</span><span class="br0">&#40;</span>GESHI_FANCY_LINE_NUMBERS<span class="sy0">,</span> <span class="nu0">37</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>The second parameter is not used in any other mode. Setting it to <code>0</code> is the same as simply using normal line numbers.
Setting it to <code>1</code> applies the fancy style to every line number.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>The values above are CONSTANTS - so don&#8217;t put them in strings!</p>
</div>
<h4 id="styling-line-numbers">3.2.2 Styling Line Numbers</h4><div class="nav"><a href="#enabling-line-numbers">Previous</a> | <a href="#line-numbers">Top</a> | <a href="#starting-line-numbers">Next</a></div>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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 <abbr title="Hypertext Markup Language">HTML</abbr> involved. So think carefully about these things before you enable line numbers.</p>
<p>Now, onto how to style line numbers:</p>
<p>Styles are set for line numbers using the <code class="highlighted php">set_line_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'background: #fcfcfc;'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>If you&#8217;re using Fancy Line Numbers mode, you pass a second string for the style of the n<sup>th</sup> line number:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'background: #fcfcfc;'</span><span class="sy0">,</span> <span class="st_h">'background: #f0f0f0;'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>The second style will have no effect if you&#8217;re not using Fancy Line Numbers mode.</p>
<p>By default, the styles you pass overwrite the current styles. Add a boolean &#8220;true&#8221; after the styles you specify to combine them with the current styles:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'background: red;'</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// or, for fancy line numbers</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'background: red;'</span><span class="sy0">,</span> <span class="st_h">'background: blue;'</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<div class="note">
<div class="note-header">Note:</div>
<p>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&#8217;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 <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=1651996&amp;group_id=114997&amp;atid=670231">SF.net BugTracker Issue #1651996</a>. This will hopefully be fixed in <abbr title="Generic Syntax Highlighter">GeSHi</abbr> version 1.2
or as soon as Firefox provides webdevelopers with adequate ways to control this feature - whichever comes first!</p>
</div>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>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&#8217;ll have to call the <code class="highlighted php">set_code_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code>
method to rectify this problem.</p>
<p>Note also that you cannot apply background colours to line numbers unless you use <code class="highlighted php">set_overall_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code>.
Here&#8217;s how you&#8217;d style:</p>
<ol>
<li><p>Use <code class="highlighted php">set_overall_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> to style the overall code block. For example, you can set the border
style/colour, any margins and padding etc. using this method. <strong>In addition:</strong> set the background colour for
all the line numbers using this method.</p></li>
<li><p>Use <code class="highlighted php">set_line_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> 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.</p></li>
<li><p>Use <code class="highlighted php">set_code_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> to explicitly override the styles you set for line numbers using
<code class="highlighted php">set_line_style</code>. For example, if you&#8217;d set the line numbers to be bold (or even if you&#8217;d only set
the fancy line number style to be bold), and you didn&#8217;t actually want your code to be bold, you&#8217;d make sure
that <code class="highlighted css"><span class="kw1">font-weight</span><span class="sy0">:</span> <span class="kw2">normal</span><span class="sy0">;</span></code> was in the stylesheet rule you passed to <code class="highlighted php">set_code_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code>.</p>
<p>This is the one major change from <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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.</p></li>
</ol>
</div>
<h4 id="starting-line-numbers">3.2.3 Choosing a Start Number</h4><div class="nav"><a href="#styling-line-numbers">Previous</a> | <a href="#line-numbers">Top</a> | <a href="#using-css-classes">Next</a></div>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.2, you can now make the line numbers start at any number, rather than just 1. This feature is useful
if you&#8217;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 <code class="highlighted php">start_line_numbers_at<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">start_line_numbers_at</span><span class="br0">&#40;</span><span class="re0">$number</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p><code class="highlighted php"><span class="re0">$number</span></code> must be a positive integer (or zero). If it is not, <abbr title="Generic Syntax Highlighter">GeSHi</abbr> will convert it anyway.</p>
<p>If you have not enabled line numbers, this will have no effect.</p>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>Although I&#8217;d like <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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 <strong>start=&#8221;number&#8221;</strong> attribute of the <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">ol</span>&gt;</span></code> tag. Although <abbr title="Cascading Style Sheets">CSS</abbr> does provide a mechanism for
doing this, it is only supported in Opera versions 7.5 and above (not even Firefox supports this).</p>
</div>
<h3 id="using-css-classes">3.3 Using <abbr title="Cascading Style Sheets">CSS</abbr> Classes</h3><div class="nav"><a href="#starting-line-numbers">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#enabling-css-classes">Next</a></div>
<p>Using <abbr title="Cascading Style Sheets">CSS</abbr> 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 &#42;huge&#42; difference to those unlucky of us on modems!</p>
<h4 id="enabling-css-classes">3.3.1 Enabling <abbr title="Cascading Style Sheets">CSS</abbr> Classes</h4><div class="nav"><a href="#using-css-classes">Previous</a> | <a href="#using-css-classes">Top</a> | <a href="#setting-css-class-id">Next</a></div>
<p>By default, <abbr title="Generic Syntax Highlighter">GeSHi</abbr> doesn&#8217;t use the classes, so it&#8217;s easy just to whack out some highlighted code if you need without
worrying about stylesheets. However, if you&#8217;re a bit more organised about it, you should use the classes ;). To turn
the use of classes on, you call the <code class="highlighted php">enable_classes<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>If you want to turn classes OFF for some reason later:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="kw4">false</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>If classes are enabled when <code class="highlighted php">parse_code<span class="br0">&#40;</span><span class="br0">&#41;</span></code> is called, then the resultant source will use <abbr title="Cascading Style Sheets">CSS</abbr> 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&#8217;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).</p>
<div class="note">
<div class="note-header">Note:</div>
<p>There have been problems with inline styles and the Symbol Highlighting added in 1.0.7.21. If you can you should
therefore turn <abbr title="Cascading Style Sheets">CSS</abbr> classes ON to avoid those issues. Although latest reworks in 1.0.8 should fix most of those issues.</p>
</div>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>This should be the very first method you call after creating a new <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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.</p>
</div>
<h4 id="setting-css-class-id">3.3.2 Setting the <abbr title="Cascading Style Sheets">CSS</abbr> class and ID</h4><div class="nav"><a href="#enabling-css-classes">Previous</a> | <a href="#using-css-classes">Top</a> | <a href="#getting-stylesheet">Next</a></div>
<p>You can set an overall <abbr title="Cascading Style Sheets">CSS</abbr> 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 <code class="highlighted php">set_overall_class<span class="br0">&#40;</span><span class="br0">&#41;</span></code> and <code class="highlighted php">set_overall_id</code>
to accomplish this:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_overall_class</span><span class="br0">&#40;</span><span class="st_h">'mycode'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_overall_id</span><span class="br0">&#40;</span><span class="st_h">'dk48ck'</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>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&#8217;t have to call these methods too often.</p>
<p><abbr title="Cascading Style Sheets">CSS</abbr> 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&#8217;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).</p>
<div class="note">
<div class="note-header">Note:</div>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.8 the class name will always include the language name used for highlighting.</p>
</div>
<h4 id="getting-stylesheet">3.3.3 Getting the stylesheet for your code</h4><div class="nav"><a href="#setting-css-class-id">Previous</a> | <a href="#using-css-classes">Top</a> | <a href="#using-an-external-stylesheet">Next</a></div>
<p>The other half of using <abbr title="Cascading Style Sheets">CSS</abbr> classes is getting the stylesheet for use with the classes. <abbr title="Generic Syntax Highlighter">GeSHi</abbr> makes it very easy to
get a stylesheet for your code, with one easy method call:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span>9
<span class="xtra li2"><span class="de2">10</span></span>11
<span class="xtra li2"><span class="de2">12</span></span>13
<span class="xtra li2"><span class="de2">14</span></span>15
<span class="xtra li2"><span class="de2">16</span></span>17
</pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// Here we have code that will spit out a header for</span>
<span class="xtra li2"><span class="de2"><span class="co1">// a stylesheet. For example:</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="st_h">'&lt;html&gt;</span></span></span><span class="st_h">&lt;head&gt;&lt;title&gt;Code&lt;/title&gt;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">&lt;style type=&quot;text/css&quot;&gt;</span></span></span><span class="st_h">&lt;!--'</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="co1">// Echo out the stylesheet for this code block</span></span></span><span class="kw1">echo</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">get_stylesheet</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// And continue echoing the page</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="kw1">echo</span> <span class="st_h">'--&gt;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">&lt;/style&gt;&lt;/head&gt;</span></span></span><span class="st_h">&lt;body&gt;'</span><span class="sy0">;</span></pre></td></tr></tbody></table>
<p>The <code class="highlighted php">get_stylesheet<span class="br0">&#40;</span><span class="br0">&#41;</span></code> 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&#8217;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.</p>
<p>By default, <code class="highlighted php">get_stylesheet<span class="br0">&#40;</span><span class="br0">&#41;</span></code> tries to echo the least amount of code possible. Although currently it doesn&#8217;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
<abbr title="Cascading Style Sheets">CSS</abbr> will not be outputted. This may be a bad thing for you perhaps you&#8217;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&#8217;re
building an external stylesheet and want all lexics included. So to get around this problem, you do this:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">get_stylesheet</span><span class="br0">&#40;</span><span class="kw4">false</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>This turns economy mode off, and all of the stylesheet will be outputted regardless.</p>
<p>Now lets say you have several snippets of code, using the same language. In most of them you don&#8217;t mind if they&#8217;re
highlighted the same way (in fact, that&#8217;s exactly what you want) but in one of them you&#8217;d like the source to be
highlighted differently. Here&#8217;s how you can do that:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span>9
<span class="xtra li2"><span class="de2">10</span></span>11
<span class="xtra li2"><span class="de2">12</span></span>13
<span class="xtra li2"><span class="de2">14</span></span>15
<span class="xtra li2"><span class="de2">16</span></span>17
<span class="xtra li2"><span class="de2">18</span></span>19
<span class="xtra li2"><span class="de2">20</span></span>21
<span class="xtra li2"><span class="de2">22</span></span>23
<span class="xtra li2"><span class="de2">24</span></span>25
<span class="xtra li2"><span class="de2">26</span></span>27
<span class="xtra li2"><span class="de2">28</span></span>29
<span class="xtra li2"><span class="de2">30</span></span>31
<span class="xtra li2"><span class="de2">32</span></span>33
<span class="xtra li2"><span class="de2">34</span></span>35
<span class="xtra li2"><span class="de2">36</span></span>37
<span class="xtra li2"><span class="de2">38</span></span>39
<span class="xtra li2"><span class="de2">40</span></span>41
<span class="xtra li2"><span class="de2">42</span></span>43
<span class="xtra li2"><span class="de2">44</span></span>45
<span class="xtra li2"><span class="de2">46</span></span>47
<span class="xtra li2"><span class="de2">48</span></span></pre></td><td class="de1"><pre class="de1"><span class="co1">// assume path is the default &quot;geshi/&quot; relative to the current directory</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$geshi1</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source1</span><span class="sy0">,</span> <span class="re0">$lang</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi2</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source2</span><span class="sy0">,</span> <span class="re0">$lang</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="re0">$geshi3</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source3</span><span class="sy0">,</span> <span class="re0">$lang</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="co1">// Turn classes on for all sources</span></span></span><span class="re0">$geshi1</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$geshi2</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi3</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="co1">// Make $geshi3 unique</span></span></span><span class="re0">$geshi3</span><span class="sy0">-&gt;</span><span class="me1">set_overall_id</span><span class="br0">&#40;</span><span class="st_h">'different'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="co1">//</span></span></span><span class="co1">// Methods are called on $geshi3 to change styles...</span>
<span class="xtra li2"><span class="de2"><span class="co1">//</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="st_h">'&lt;html&gt;</span></span></span><span class="st_h">&lt;head&gt;&lt;title&gt;Code&lt;/title&gt;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="st_h">&lt;style type=&quot;text/css&quot;&gt;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">&lt;!--</span></span></span><span class="st_h">'</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// Get the nessecary stylesheets</span>
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="re0">$geshi1</span><span class="sy0">-&gt;</span><span class="me1">get_stylesheet</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="re0">$geshi3</span><span class="sy0">-&gt;</span><span class="me1">get_stylesheet</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="st_h">'--&gt;</span></span></span><span class="st_h">&lt;/style&gt;&lt;/head&gt;</span>
<span class="xtra li2"><span class="de2"><span class="st_h">&lt;body&gt;'</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="kw1">echo</span> <span class="st_h">'Code snippet 1:'</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="re0">$geshi1</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span><span class="kw1">echo</span> <span class="st_h">'Code snippet 2 (same highlighting as 1):'</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="kw1">echo</span> <span class="re0">$geshi2</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="st_h">'Code snippet 3 (DIFFERENT highlighting):'</span><span class="sy0">;</span></span></span><span class="kw1">echo</span> <span class="re0">$geshi3</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="st_h">'&lt;/body&gt;&lt;/html&gt;'</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>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.</p>
<h4 id="using-an-external-stylesheet">3.3.4 Using an External Stylesheet</h4><div class="nav"><a href="#getting-stylesheet">Previous</a> | <a href="#using-css-classes">Top</a> | <a href="#changing-styles">Next</a></div>
<p>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&#8217;s up to you to link it in to your document, normally with
the following <abbr title="Hypertext Markup Language">HTML</abbr>:</p>
<table class="html4strict geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">HTML code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
</pre></td><td class="de1"><pre class="de1"><span class="sc2">&lt;<a href="http://december.com/html/4/element/html.html"><span class="kw2">html</span></a>&gt;</span>
<span class="xtra li2"><span class="de2"><span class="sc2">&lt;<a href="http://december.com/html/4/element/head.html"><span class="kw2">head</span></a>&gt;</span></span></span><span class="sc2">&lt;<a href="http://december.com/html/4/element/link.html"><span class="kw2">link</span></a> <span class="kw3">rel</span><span class="sy0">=</span><span class="st0">&quot;stylesheet&quot;</span> <span class="kw3">type</span><span class="sy0">=</span><span class="st0">&quot;text/css&quot;</span> <span class="kw3">href</span><span class="sy0">=</span><span class="st0">&quot;url_to_stylesheet.css&quot;</span> <span class="sy0">/</span>&gt;</span></pre></td></tr></tbody></table>
<p>In your external stylesheet you put <abbr title="Cascading Style Sheets">CSS</abbr> declarations for your code. Then just make sure you&#8217;re using the correct class (use
<code class="highlighted php">set_overall_class<span class="br0">&#40;</span><span class="br0">&#41;</span></code> to ensure this) and this should work fine.</p>
<p>This method is great if you don&#8217;t mind the source always being highlighted the same (in particular, if you&#8217;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&#8217;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.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>As of version 1.0.2, <abbr title="Generic Syntax Highlighter">GeSHi</abbr> comes with a <code>contrib/</code> directory, which in it contains a &#8220;wizard&#8221; 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 (<abbr title="PHP: HTML Preprocessor">PHP</abbr> and <abbr title="Extensible Markup Language">XML</abbr> 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!</p>
</div>
<h3 id="changing-styles">3.4 Changing Styles</h3><div class="nav"><a href="#using-an-external-stylesheet">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#the-overall-styles">Next</a></div>
<p>One of the more powerful features of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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.</p>
<p>If you&#8217;re confused about &#8220;styles&#8221;, you probably want to have a quick tutorial in them so you know what you can do with
them. Checkout the homepage of <abbr title="Cascading Style Sheets">CSS</abbr> at <a href="http://www.w3.org/Style/CSS">http://www.w3.org/Style/CSS</a>.</p>
<h4 id="the-overall-styles">3.4.1 The Overall Styles</h4><div class="nav"><a href="#changing-styles">Previous</a> | <a href="#changing-styles">Top</a> | <a href="#line-number-styles">Next</a></div>
<p>The code outputted by <abbr title="Generic Syntax Highlighter">GeSHi</abbr> is either in a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> or a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> (see the section entitled &#8220;The
Code Container&#8221;), and this can be styled.</p>
<p><code>$geshi-&gt;set_overall_style('... styles ...');</code>
Where styles is a string containing valid <abbr title="Cascading Style Sheets">CSS</abbr> declarations. By default, these styles overwrite the current styles, but you can change this by adding a second parameter:</p>
<p><code>$geshi-&gt;set_overall_style('color: blue;', true);</code>
The default styles &#8220;shine through&#8221; wherever anything isn&#8217;t highlighted. Also, you can apply more advanced styles, like position: (fixed|relative) etc, because a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code>/<code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code> is a block level element.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>Remember that a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">div</span>&gt;</span></code> will by default have a larger font size than a <code class="highlighted html4strict"><span class="sc2">&lt;<span class="kw2">pre</span>&gt;</span></code>, as discussed in the section <a href="#the-code-container">&#8220;The Code Container&#8221;</a>.</p>
</div>
<h4 id="line-number-styles">3.4.2 Line Number Styles</h4><div class="nav"><a href="#the-overall-styles">Previous</a> | <a href="#changing-styles">Top</a> | <a href="#setting-keyword-styles">Next</a></div>
<p>You may wish to refer to the section [Styling Line Numbers][1] before reading this section.</p>
<p>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.</p>
<p>Line number styles are set by using the method <code class="highlighted php">set_line_style</code>:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="re0">$style1</span><span class="sy0">,</span> <span class="re0">$style2</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p><code class="highlighted php"><span class="re0">$style1</span></code> is the style of the line numbers by default, and <code class="highlighted php"><span class="re0">$style2</span></code> is the style of the fancy line numbers.</p>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>Things have changed since 1.0.1! This note is <strong>very</strong> important - please make sure you check this twice before
complaining about line numbers!</p>
<p>Because of the way that ordered lists are done in <abbr title="Hypertext Markup Language">HTML</abbr>, there really isn&#8217;t normally a way to style the actual
<em>numbers</em> in the list. I&#8217;ve cheated somewhat with <abbr title="Generic Syntax Highlighter">GeSHi</abbr> - I&#8217;ve made it possible to use <abbr title="Cascading Style Sheets">CSS</abbr> to style the <em>foreground</em> 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 <strong>must</strong> use <code class="highlighted php">set_overall_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> to do this, and use <code class="highlighted php">set_code_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code>
to style the actual code! This is explained in the section above: <a href="#styling-line-numbers">Styling Line Numbers</a>.</p>
<p>In addition, the styles for fancy line numbers <em>is now the difference between the normal styles and the styles you want
to achieve</em>. For example, in <abbr title="Generic Syntax Highlighter">GeSHi</abbr> prior to 1.0.2 you may have done this to style line numbers:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'color: red; font-weight: bold;'</span><span class="sy0">,</span> <span class="st_h">'color: green; font-weight: bold'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Now you instead can do this:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_line_style</span><span class="br0">&#40;</span><span class="st_h">'color: red; font-weight: bold;'</span><span class="sy0">,</span> <span class="st_h">'color: green;'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>The <code class="highlighted css"><span class="kw1">font-weight</span><span class="sy0">:</span> <span class="kw2">bold</span><span class="sy0">;</span></code> 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.</p>
</div>
<h4 id="setting-keyword-styles">3.4.3 Setting Keyword Styles</h4><div class="nav"><a href="#line-number-styles">Previous</a> | <a href="#changing-styles">Top</a> | <a href="#setting-comment-styles">Next</a></div>
<p>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&#8217;ll have to know what the set is called first. Sets are numbered from 1 up. Typically, set 1
contains keywords like <code>if</code>, <code>while</code>, <code>do</code>, <code>for</code>, <code>switch</code> etc, set 2 contains <code>null</code>, <code>false</code>, <code>true</code> etc, set 3
contains function inbuilt into the language (<code>echo</code>, <code>htmlspecialchars</code> etc. in <abbr title="PHP: HTML Preprocessor">PHP</abbr>) and set 4 contains data types and
similar variable modifiers: <code>int</code>, <code>double</code>, <code>real</code>, <code>static</code> 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.</p>
<p>To change the styles for a keyword set, call the <code class="highlighted php">set_keyword_group_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_keyword_group_style</span><span class="br0">&#40;</span><span class="re0">$group</span><span class="sy0">,</span> <span class="re0">$styles</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Where <code class="highlighted php"><span class="re0">$group</span></code> is the group to change the styles for and <code class="highlighted php"><span class="re0">$styles</span></code> is a string containing the styles
to apply to that group.</p>
<p>By default, the styles you pass overwrite the current styles. Add a boolean <code class="highlighted php"><span class="kw4">true</span></code> after the styles you specify to
combine them with the current styles:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_keyword_group_style</span><span class="br0">&#40;</span><span class="nu0">3</span><span class="sy0">,</span> <span class="st_h">'color: white;'</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<h4 id="setting-comment-styles">3.4.4 Setting Comment Styles</h4><div class="nav"><a href="#setting-keyword-styles">Previous</a> | <a href="#changing-styles">Top</a> | <a href="#setting-other-styles">Next</a></div>
<p>To change the styles for a comment group, call the <code class="highlighted php">set_comments_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_comments_style</span><span class="br0">&#40;</span><span class="re0">$group</span><span class="sy0">,</span> <span class="re0">$styles</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Where <code class="highlighted php"><span class="re0">$group</span></code> is either a number corresponding to a single-line comment, or the string <code class="highlighted php"><span class="st_h">'MULTI'</span></code> to
specify multiline comments:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_comments_style</span><span class="br0">&#40;</span><span class="nu0">1</span><span class="sy0">,</span> <span class="st_h">'font-style: italic;'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_comments_style</span><span class="br0">&#40;</span><span class="st_h">'MULTI'</span><span class="sy0">,</span> <span class="st_h">'display: hidden;'</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>By default, the styles you pass overwrite the current styles. Add a boolean <code class="highlighted php"><span class="kw4">true</span></code> after the styles you specify to
combine them with the current styles:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_comments_style</span><span class="br0">&#40;</span><span class="nu0">1</span><span class="sy0">,</span> <span class="st_h">'font-weight: 100;'</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<div class="note">
<div class="note-header">Note:</div>
<p>In 1.0.7.22 a new kind of Comments called &#8220;COMMENT_REGEXP&#8221; has been added. Those are handled by setting single
line comment styles.</p>
</div>
<h4 id="setting-other-styles">3.4.5 Setting Other Styles</h4><div class="nav"><a href="#setting-comment-styles">Previous</a> | <a href="#changing-styles">Top</a> | <a href="#case-caps">Next</a></div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
</pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_escape_characters_style</span><span class="br0">&#40;</span><span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_symbols_style</span><span class="br0">&#40;</span><span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_strings_style</span><span class="br0">&#40;</span><span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_numbers_style</span><span class="br0">&#40;</span><span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_methods_style</span><span class="br0">&#40;</span><span class="re0">$key</span><span class="sy0">,</span> <span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_regexps_style</span><span class="br0">&#40;</span><span class="re0">$key</span><span class="sy0">,</span> <span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span></pre></td></tr></tbody></table>
<p><code class="highlighted php"><span class="re0">$styles</span></code> is a string containing valid stylesheet declarations, while <code class="highlighted php"><span class="re0">$preserve_defaults</span></code> should be set
to <code class="highlighted php"><span class="kw4">true</span></code> if you want your styles to be merged with the previous styles. In the case of <code class="highlighted php">set_methods_style<span class="br0">&#40;</span><span class="br0">&#41;</span></code>,
you should select a group to set the styles of, check the language files for the number used for each &#8220;object splitter&#8221;.</p>
<p>Like this was possible for <code class="highlighted php">set_method_style</code> a new parameter has been introduced for
<code class="highlighted php">set_symbols_style</code> too which allows you to select the group of symbols for which you&#8217;d like to change your
style. <code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_symbols_style</span><span class="br0">&#40;</span><span class="re0">$styles</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$preserve_defaults</span><span class="br0">&#91;</span><span class="sy0">,</span> <span class="re0">$group</span><span class="br0">&#93;</span><span class="br0">&#93;</span><span class="br0">&#41;</span><span class="sy0">;</span></code> 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 <code class="highlighted php">set_bracket_style</code> is made.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>Since <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.8 multiple styles for strings and numbers are supported, though the API doesn&#8217;t provide full access yet.</p>
</div>
<h3 id="case-caps">3.5 Case Sensitivity and Auto Casing</h3><div class="nav"><a href="#setting-other-styles">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#auto-caps-nocaps">Next</a></div>
<p>Controlling the case of the outputted source is an easy job with <abbr title="Generic Syntax Highlighter">GeSHi</abbr>. You can control which keywords are converted in
case, and also control whether keywords are checked in a case sensitive manner.</p>
<h4 id="auto-caps-nocaps">3.5.1 Auto-Caps/NoCaps</h4><div class="nav"><a href="#case-caps">Previous</a> | <a href="#case-caps">Top</a> | <a href="#setting-case-sensitivity">Next</a></div>
<p>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&#8217;s capatalisation, and SQL is another
language well known for using caps for readability.</p>
<p>To change what case lexics are rendered in, you call the <code class="highlighted php">set_case_keywords<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_case_keywords</span><span class="br0">&#40;</span><span class="re0">$caps_modifier</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>The valid values to pass to this method are:</p>
<ul>
<li><code>GESHI_CAPS_NO_CHANGE</code> - Don&#8217;t change the case of any lexics, leave as they are found</li>
<li><code>GESHI_CAPS_UPPER</code> - Uppercase all lexics found</li>
<li><code>GESHI_CAPS_LOWER</code> - Lowercase all lexics found</li>
</ul>
<div class="caution">
<div class="caution-header">Caution:</div>
<p>When I say &#8220;lexic&#8221;, I mean &#8220;keywords&#8221;. <strong>Any</strong> keyword in <strong>any</strong> keyword array will be modified using this option!
This is one small area of inflexibility I hope to fix in 1.2.X.</p>
</div>
<p>I suspect this will only be used to specify <code>GESHI_CAPS_NO_CHANGE</code> to turn off autocaps for languages like SQL
and BASIC variants, like so:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'sql'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_case_keywords</span><span class="br0">&#40;</span>GESHI_CAPS_NO_CHANGE<span class="br0">&#41;</span><span class="sy0">;</span> <span class="co1">// don't want keywords capatalised</span></span></span></pre></td></tr></tbody></table>
<p>All the same, it can be used for some interesting effects:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'java'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="co1">// Anyone who's used java knows how picky it is about CapitalLetters...</span></span></span><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_case_keywords</span><span class="br0">&#40;</span>GESHI_CAPS_LOWER<span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="co1">// No *way* the source will look right now ;)</span></span></span></pre></td></tr></tbody></table>
<h4 id="setting-case-sensitivity">3.5.2 Setting Case Sensitivity</h4><div class="nav"><a href="#auto-caps-nocaps">Previous</a> | <a href="#case-caps">Top</a> | <a href="#changing-config">Next</a></div>
<p>Some languages, like <abbr title="PHP: HTML Preprocessor">PHP</abbr>, don&#8217;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 <code class="highlighted php">set_case_sensitivity<span class="br0">&#40;</span><span class="br0">&#41;</span></code>
to change the case sensitiveness of a particular keyword group from the default:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_case_sensitivity</span><span class="br0">&#40;</span><span class="re0">$key</span><span class="sy0">,</span> <span class="re0">$sensitivity</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Where <code class="highlighted php"><span class="re0">$key</span></code> is the key of the group for which you wish to change case sensitivness for (see the language file
for that language), and <code class="highlighted php"><span class="re0">$sensitivity</span></code> is a boolean value - <code class="highlighted php"><span class="kw4">true</span></code> if the keyword is case sensitive, and
<code class="highlighted php"><span class="kw4">false</span></code> if not.</p>
<h3 id="changing-config">3.6 Changing the Source, Language, Config Options</h3><div class="nav"><a href="#setting-case-sensitivity">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#changing-the-source">Next</a></div>
<p>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&#8217;ve created a <abbr title="Generic Syntax Highlighter">GeSHi</abbr> object? Well, that&#8217;s where these methods come in.</p>
<h4 id="changing-the-source">3.6.1 Changing the Source Code</h4><div class="nav"><a href="#changing-config">Previous</a> | <a href="#changing-config">Top</a> | <a href="#changing-the-language">Next</a></div>
<p>To change the source code, you call the <code class="highlighted php">set_source<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_source</span><span class="br0">&#40;</span><span class="re0">$newsource</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Example:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source1</span><span class="sy0">,</span> <span class="st_h">'php'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// Method calls to specify various options...</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$code1</span> <span class="sy0">=</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_source</span><span class="br0">&#40;</span><span class="re0">$source2</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="re0">$code2</span> <span class="sy0">=</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<h4 id="changing-the-language">3.6.2 Changing the Language</h4><div class="nav"><a href="#changing-the-source">Previous</a> | <a href="#changing-config">Top</a> | <a href="#changing-the-path">Next</a></div>
<p>What happens if you want to change the language used for highlighting? Just call <code class="highlighted php">set_language<span class="br0">&#40;</span><span class="br0">&#41;</span></code>:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_language</span><span class="br0">&#40;</span><span class="st_h">'newlanguage'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>Example:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span>5
<span class="xtra li2"><span class="de2">6</span></span>7
<span class="xtra li2"><span class="de2">8</span></span>9
<span class="xtra li2"><span class="de2">10</span></span></pre></td><td class="de1"><pre class="de1"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="re0">$source</span><span class="sy0">,</span> <span class="st_h">'php'</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="re0">$code</span> <span class="sy0">=</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2">&nbsp;</span></span><span class="co1">// Highlight GeSHi's output</span>
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_source</span><span class="br0">&#40;</span><span class="re0">$code</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span>&nbsp;
<span class="xtra li2"><span class="de2"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_language</span><span class="br0">&#40;</span><span class="st_h">'html4strict'</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">enable_classes</span><span class="br0">&#40;</span><span class="kw4">false</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="xtra li2"><span class="de2"><span class="kw1">echo</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">parse_code</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.5, you can use the method <code class="highlighted php">load_from_file<span class="br0">&#40;</span><span class="br0">&#41;</span></code> 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.</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">load_from_file</span><span class="br0">&#40;</span><span class="re0">$file_name</span><span class="sy0">,</span> <span class="re0">$lookup</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p><code class="highlighted php"><span class="re0">$file_name</span></code> is the file name to use, and <code class="highlighted php"><span class="re0">$lookup</span></code> is an optional parameter that contains a lookup
array to use for deciding which language to choose. You can use this to override <abbr title="Generic Syntax Highlighter">GeSHi</abbr>&#8217;s default lookup array, which
may not contain the extension of the file you&#8217;re after, or perhaps does have your extension but under a different
language. The lookup array is of the form:</p>
<table class="php geshicode" style="font-family:monospace;"><thead><tr><td colspan="2" class="head">PHP code</td></tr></thead><tbody><tr class="li1"><td class="ln"><pre class="de1">1
<span class="xtra li2"><span class="de2">2</span></span>3
<span class="xtra li2"><span class="de2">4</span></span></pre></td><td class="de1"><pre class="de1"><a href="http://www.php.net/array"><span class="kw3">array</span></a><span class="br0">&#40;</span>
<span class="xtra li2"><span class="de2">&nbsp; &nbsp;<span class="st_h">'lang_name'</span> <span class="sy0">=&gt;</span> <a href="http://www.php.net/array"><span class="kw3">array</span></a><span class="br0">&#40;</span><span class="st_h">'extension'</span><span class="sy0">,</span> <span class="st_h">'extension'</span><span class="sy0">,</span> <span class="sy0">...</span><span class="br0">&#41;</span><span class="sy0">,</span></span></span>&nbsp; &nbsp;<span class="st_h">'lang_name'</span> <span class="sy0">...</span>
<span class="xtra li2"><span class="de2"><span class="br0">&#41;</span><span class="sy0">;</span></span></span></pre></td></tr></tbody></table>
<p>Also, you can use the method <code class="highlighted php">get_language_name_from_extension<span class="br0">&#40;</span><span class="br0">&#41;</span></code> 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 <code class="highlighted php">load_from_file</code> it accepts an optional second parameter that contains a lookup array.</p>
<div class="note">
<div class="note-header">Note:</div>
<p>Names are case-insensitive - they will be converted to lower case to match a language file however. So if you&#8217;re
making a language file, remember it should have a name in lower case.</p>
</div>
<div class="note">
<div class="note-header">Note:</div>
<p>What you pass to this method is the name of a language file, minus the .php extension. If you&#8217;re writing a plugin
for a particular application, it&#8217;s up to you to somehow convert user input into a valid language name.</p>
</div>
<div class="note">
<div class="note-header">Note:</div>
<p>Since <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.8 this function does not reset language settings for an already loaded language. If you want
to highlight code in the same language with different settings add the optional
<code class="highlighted php"><span class="re0">$force_reset</span> parameter</code>:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_language</span><span class="br0">&#40;</span><span class="st_h">'language'</span><span class="sy0">,</span> <span class="kw4">true</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
</div>
<div class="caution">
<div class="caution-header">Caution:</div>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> <code class="highlighted php"><span class="kw1">include</span><span class="br0">&#40;</span><span class="br0">&#41;</span></code>s the language file, so be careful to make sure that users can&#8217;t pass some wierd
language name to include any old script! <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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.</p>
<p>At the very least, strip &#8220;/&#8221; characters out of a language name.</p>
</div>
<h4 id="changing-the-path">3.6.3 Changing the Language Path</h4><div class="nav"><a href="#changing-the-language">Previous</a> | <a href="#changing-config">Top</a> | <a href="#changing-the-charset">Next</a></div>
<p>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 <code class="highlighted php">set_language_path<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_language_path</span><span class="br0">&#40;</span><span class="re0">$newpath</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>It doesn&#8217;t matter whether the path has a trailing slash after it or not - only that it points to a valid folder.
If it doesn&#8217;t, that&#8217;s your tough luck ;)</p>
<h4 id="changing-the-charset">3.6.4 Changing the Character Set</h4><div class="nav"><a href="#changing-the-path">Previous</a> | <a href="#changing-config">Top</a> | <a href="#error-handling">Next</a></div>
<div class="note">
<div class="note-header">Note:</div>
<p>Although <abbr title="Generic Syntax Highlighter">GeSHi</abbr> itself does not require to know the exact charset of your source you
will need to set this option when processing sources where multi-byte characters can occur.
As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.7.18 internally a rewrite of <code class="highlighted php"><span class="kw3">htmlspecialchars</span></code> is used
due to a security flaw in that function that is unpatched in even the most recent PHP4 versions and in PHP5 &lt; 5.2.
Although this does no longer explicitely require the charset it is required again
as of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.8 to properly handle multi-byte characters (e.g. after an escape char).</p>
</div>
<div class="note">
<div class="note-header">Note:</div>
<p>As of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 1.0.8 the default charset has been changed to UTF-8.</p>
</div>
<p>As of version 1.0.3, you can use the method <code class="highlighted php">set_encoding<span class="br0">&#40;</span><span class="br0">&#41;</span></code> to specify the character set that your source
is in. Valid names are those names that are valid for the <abbr title="PHP: HTML Preprocessor">PHP</abbr> mbstring library:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">set_encoding</span><span class="br0">&#40;</span><span class="re0">$encoding</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p>There is a table of valid strings for <code class="highlighted php"><span class="re0">$encoding</span></code> 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.</p>
<h3 id="error-handling">3.7 Error Handling</h3><div class="nav"><a href="#changing-the-charset">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#disabling-lexics">Next</a></div>
<p>What happens if you try to highlight using a language that doesn&#8217;t exist? Or if <abbr title="Generic Syntax Highlighter">GeSHi</abbr> can&#8217;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. <abbr title="Generic Syntax Highlighter">GeSHi</abbr>
provides ways of finding out if <abbr title="Generic Syntax Highlighter">GeSHi</abbr> itself found anything wrong with what you tried to do. After highlighting,
you can call the <code class="highlighted php">error<span class="br0">&#40;</span><span class="br0">&#41;</span></code> method:</p>
<p><code class="highlighted php"><span class="re0">$geshi</span> <span class="sy0">=</span> <span class="kw2">new</span> GeSHi<span class="br0">&#40;</span><span class="st_h">'hi'</span><span class="sy0">,</span> <span class="st_h">'thisLangIsNotSupported'</span><span class="br0">&#41;</span><span class="sy0">;</span></code></p>
<p><code class="highlighted php"><span class="kw1">echo</span> <span class="re0">$geshi</span><span class="sy0">-&gt;</span><span class="me1">error</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span> <span class="co1">// echoes error message</span></code></p>
<p>The error message you will get will look like this:</p>
<blockquote>
<p><abbr title="Generic Syntax Highlighter">GeSHi</abbr> Error: <abbr title="Generic Syntax Highlighter">GeSHi</abbr> could not find the language thisLangIsNotSupported (using path geshi/) (code 2)</p>
</blockquote>
<p>The error outputted will be the last error <abbr title="Generic Syntax Highlighter">GeSHi</abbr> came across, just like how <code class="highlighted php"><span class="kw3">mysql_error</span><span class="br0">&#40;</span><span class="br0">&#41;</span></code> works.</p>
<h3 id="disabling-lexics">3.8 Disabling styling of some Lexics</h3><div class="nav"><a href="#error-handling">Previous</a> | <a href="#advanced-features">Top</a> | <a href="#setting-tab-width">Next</a></div>
<p>One disadvantage of <abbr title="Generic Syntax Highlighter">GeSHi</abbr> 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,
you can gain speed by disabling some of the highlighting options. This is done by using a
series of <code class="highlighted php">set_<span class="sy0">*</span>_highlighting</code> methods:</p>
<dl>
<dt><code class="highlighted php">set_keyword_group_highlighting<span class="br0">&#40;</span><span