Docs For Class GeSHi

GeSHi

Description

The GeSHi Class.

Please refer to the documentation for GeSHi 1.0.X that is available at http://qbnz.com/highlighter/documentation.php for more information about how to use this class.

author: Nigel McNie <nigel@geshi.org>, Benny Baumann <BenBE@omorphia.de>
copyright: (C) 2004 - 2007 Nigel McNie, (C) 2007 - 2008 Benny Baumann

Located in /geshi.php (line 253)

Method Summary

GeSHi GeSHi ([string $source = ''], [string $language = ''], [string $path = ''])

void add_keyword (int $key, string $word)

void add_keyword_group (int $key, string $styles, [boolean $case_sensitive = true], [array $words = array()])

void disable_highlighting ()

void enable_classes ([boolean $flag = true])

void enable_highlighting ([boolean $flag = true])

void enable_ids ([boolean $flag = true])

void enable_important_blocks (boolean $flag)

void enable_inner_code_block (boolean $flag)

void enable_keyword_links ([boolean $enable = true])

void enable_line_numbers (int $flag, [int $nth_row = 5])

void enable_multiline_span (boolean $flag)

void enable_strict_mode ([boolean $mode = true])

string|false error ()

string get_language_name ()

void get_language_name_from_extension (string $extension, [array $lookup = array()])

bool get_multiline_span ()

int get_real_tab_width ()

string get_stylesheet ([boolean $economy_mode = true])

double get_time ()

void highlight_lines_extra (mixed $lines, [string $style = null])

void load_from_file (string $file_name, [array $lookup = array()])

void optimize_keyword_group (int $key)

void parse_code ()

void remove_keyword (int $key, string $word, [bool $recompile = true])

void remove_keyword_group (int $key)

void set_brackets_highlighting (boolean $flag)

void set_brackets_style (string $style, [boolean $preserve_defaults = false])

void set_case_keywords (int $case)

void set_case_sensitivity (int $key, boolean $case)

void set_code_style (string $style, [boolean $preserve_defaults = false])

void set_comments_highlighting (int $key, [boolean $flag = true])

void set_comments_style (int $key, string $style, [boolean $preserve_defaults = false])

void set_encoding (string $encoding)

void set_escape_characters_highlighting ([boolean $flag = true])

void set_escape_characters_style (string $style, [boolean $preserve_defaults = false])

void set_footer_content (string $content)

void set_footer_content_style (string $style)

void set_header_content (string $content)

void set_header_content_style (string $style)

void set_header_type (int $type)

void set_highlight_lines_extra_style (string $styles)

void set_important_styles (string $styles)

void set_keyword_group_highlighting (int $key, [boolean $flag = true])

void set_keyword_group_style (int $key, string $style, [boolean $preserve_defaults = false])

void set_language (string $language, [ $force_reset = false])

void set_language_path (string $path)

void set_line_ending (string $line_ending)

void set_line_style (string $style1, [string|boolean $style2 = ''], [boolean $preserve_defaults = false])

void set_link_styles (int $type, string $styles)

void set_link_target (string $target)

void set_methods_highlighting (boolean $flag)

void set_methods_style (int $key, string $style, [boolean $preserve_defaults = false])

void set_numbers_highlighting (boolean $flag)

void set_numbers_style (string $style, [boolean $preserve_defaults = false])

void set_overall_class (string $class)

void set_overall_id (string $id)

void set_overall_style (string $style, [boolean $preserve_defaults = false])

void set_regexps_highlighting (int $key, boolean $flag)

void set_regexps_style (string $key, boolean $style, [ $preserve_defaults = false])

void set_source (string $source)

void set_strings_highlighting (boolean $flag)

void set_strings_style (string $style, [boolean $preserve_defaults = false])

void set_symbols_highlighting (boolean $flag)

void set_symbols_style (string $style, [boolean $preserve_defaults = false], [int $group = 0])

void set_tab_width (int $width)

void set_url_for_keyword_group (int $group, string $url)

void set_use_language_tab_width (boolean $use)

void start_line_numbers_at (int $number)

Methods

Constructor GeSHi (line 591)

Creates a new GeSHi object, with source and language

since: 1.0.0

GeSHi GeSHi ([string $source = ''], [string $language = ''], [string $path = ''])

string $source: The source code to highlight
string $language: The language to highlight the source with
string $path: The path to the language file directory. This is deprecated! I've backported the auto path detection from the 1.1.X dev branch, so now it should be automatically set correctly. If you have renamed the language directory however, you will still need to set the path using this parameter or GeSHi->set_language_path()

add_keyword (line 1441)

Adds a keyword to a keyword group for highlighting

since: 1.0.0

void add_keyword (int $key, string $word)

int $key: The key of the keyword group to add the keyword to
string $word: The word to add to the keyword group

add_keyword_group (line 1487)

Creates a new keyword group

since: 1.0.0

void add_keyword_group (int $key, string $styles, [boolean $case_sensitive = true], [array $words = array()])

int $key: The key of the keyword group to create
string $styles: The styles for the keyword group
boolean $case_sensitive: Whether the keyword group is case sensitive ornot
array $words: The words to use for the keyword group

disable_highlighting (line 1288)

Disables all highlighting

deprecated: In favour of enable_highlighting
todo: Rewrite with array traversal
since: 1.0.0

void disable_highlighting ()

enable_classes (line 805)

Sets whether CSS classes should be used to highlight the source. Default is off, calling this method with no arguments will turn it on

since: 1.0.0

void enable_classes ([boolean $flag = true])

boolean $flag: Whether to turn classes on or not

enable_highlighting (line 1302)

Enables all highlighting

The optional flag parameter was added in version 1.0.7.21 and can be used to enable (true) or disable (false) all highlighting.

todo: Rewrite with array traversal
since: 1.0.0

void enable_highlighting ([boolean $flag = true])

boolean $flag: A flag specifying whether to enable or disable all highlighting

enable_ids (line 1652)

Whether CSS IDs should be added to each line

since: 1.0.2

void enable_ids ([boolean $flag = true])

boolean $flag: If true, IDs will be added to each line.

enable_important_blocks (line 1642)

Sets whether context-important blocks are highlighted

deprecated:
todo: REMOVE THIS SHIZ FROM GESHI!
since: 1.0.2

void enable_important_blocks (boolean $flag)

boolean $flag: Tells whether to enable or disable highlighting of important blocks

enable_inner_code_block (line 1581)

Sets whether to force a surrounding block around the highlighted code or not

since: 1.0.7.20

void enable_inner_code_block (boolean $flag)

boolean $flag: Tells whether to enable or disable this feature

enable_keyword_links (line 1756)

Turns linking of keywords on or off.

since: 1.0.2

void enable_keyword_links ([boolean $enable = true])

boolean $enable: If true, links will be added to keywords

enable_line_numbers (line 878)

Sets whether line numbers should be displayed.

Valid values for the first parameter are:

GESHI_NO_LINE_NUMBERS: Line numbers will not be displayed
GESHI_NORMAL_LINE_NUMBERS: Line numbers will be displayed
GESHI_FANCY_LINE_NUMBERS: Fancy line numbers will be displayed

For fancy line numbers, the second parameter is used to signal which lines are to be fancy. For example, if the value of this parameter is 5 then every 5th line will be fancy.

since: 1.0.0

void enable_line_numbers (int $flag, [int $nth_row = 5])

int $flag: How line numbers should be displayed
int $nth_row: Defines which lines are fancy

enable_multiline_span (line 896)

Sets wether spans and other HTML markup generated by GeSHi can span over multiple lines or not. Defaults to true to reduce overhead.

Set it to false if you want to manipulate the output or manually display the code in an ordered list.

since: 1.0.7.22

void enable_multiline_span (boolean $flag)

boolean $flag: Wether multiline spans are allowed or not

enable_strict_mode (line 1275)

Enables/disables strict highlighting. Default is off, calling this method without parameters will turn it on. See documentation for more details on strict mode and where to use it.

since: 1.0.0

void enable_strict_mode ([boolean $mode = true])

boolean $mode: Whether to enable strict mode or not

error (line 608)

Returns an error message associated with the last GeSHi operation, or false if no error has occured

return: An error message if there has been an error, else false
since: 1.0.0

string|false error ()

get_language_name (line 632)

Gets a human-readable language name (thanks to Simon Patterson for the idea :))

return: The name for the current language
since: 1.0.2

string get_language_name ()

get_language_name_from_extension (line 1329)

Given a file extension, this method returns either a valid geshi language name, or the empty string if it couldn't be found

todo: Re-think about how this method works (maybe make it private and/or make it a extension->lang lookup?)
todo: static?
since: 1.0.5

void get_language_name_from_extension (string $extension, [array $lookup = array()])

string $extension: The extension to get a language name for
array $lookup: A lookup array to use instead of the default one

get_multiline_span (line 906)

Get current setting for multiline spans, see GeSHi->enable_multiline_span().

see: GeSHi::enable_multiline_span()

bool get_multiline_span ()

get_real_tab_width (line 1258)

Returns the tab width to use, based on the current language and user preference

return: Tab width
since: 1.0.7.20

int get_real_tab_width ()

get_stylesheet (line 4177)

Returns a stylesheet for the highlighted code. If $economy mode is true, we only return the stylesheet declarations that matter for this code block instead of the whole thing

return: A stylesheet built on the data for the current language
since: 1.0.0

string get_stylesheet ([boolean $economy_mode = true])

boolean $economy_mode: Whether to use economy mode or not

get_time (line 3524)

Gets the time taken to parse the code

return: The time taken to parse the code
since: 1.0.2

double get_time ()

highlight_lines_extra (line 1670)

Specifies which lines to highlight extra

The extra style parameter was added in 1.0.7.21.

todo: Some data replication here that could be cut down on
since: 1.0.2

void highlight_lines_extra (mixed $lines, [string $style = null])

mixed $lines: An array of line numbers to highlight, or just a line number on its own.
string $style: A string specifying the style to use for this line. If null is specified, the default style is used. If false is specified, the line will be removed from special highlighting

load_from_file (line 1425)

Given a file name, this method loads its contents in, and attempts

to set the language automatically. An optional lookup table can be passed for looking up the language name. If not specified a default table is used

The language table is in the form

array(
   'lang_name' => array('extension', 'extension', ...),
   'lang_name' ...
 );

todo: Complete rethink of this and above method
since: 1.0.5

void load_from_file (string $file_name, [array $lookup = array()])

string $file_name: The filename to load the source from
array $lookup: A lookup array to use instead of the default one

optimize_keyword_group (line 1529)

compile optimized regexp list for keyword group

since: 1.0.8

void optimize_keyword_group (int $key)

int $key: The key of the keyword group to compile & optimize

parse_code (line 1992)

Returns the code in $this->source, highlighted and surrounded by the nessecary HTML.

This should only be called ONCE, cos it's SLOW! If you want to highlight the same source multiple times, you're better off doing a whole lot of str_replaces to replace the <span>s

since: 1.0.0

void parse_code ()

remove_keyword (line 1466)

Removes a keyword from a keyword group

since: 1.0.0

void remove_keyword (int $key, string $word, [bool $recompile = true])

int $key: The key of the keyword group to remove the keyword from
string $word: The word to remove from the keyword group
bool $recompile: Wether to automatically recompile the optimized regexp list or not. Note: if you set this to false and @see GeSHi->parse_code() was already called once, for the current language, you have to manually call @see GeSHi->optimize_keyword_group() or the removed keyword will stay in cache and still be highlighted! On the other hand it might be too expensive to recompile the regexp list for every removal if you want to remove a lot of keywords.

remove_keyword_group (line 1512)

Removes a keyword group

since: 1.0.0

void remove_keyword_group (int $key)

int $key: The key of the keyword group to remove

set_brackets_highlighting (line 1036)

Turns highlighting on/off for brackets

This method is DEPRECATED: use set_symbols_highlighting instead. This method will be remove in 1.2.X

deprecated: In favour of set_symbols_highlighting
since: 1.0.0

void set_brackets_highlighting (boolean $flag)

boolean $flag: Whether to turn highlighting for brackets on or off

set_brackets_style (line 1018)

Sets the styles for brackets. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

This method is DEPRECATED: use set_symbols_style instead. This method will be removed in 1.2.X

deprecated: In favour of set_symbols_style
since: 1.0.0

void set_brackets_style (string $style, [boolean $preserve_defaults = false])

string $style: The style to make the brackets
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_case_keywords (line 1216)

Sets the case that keywords should use when found. Use the constants:

GESHI_CAPS_NO_CHANGE: leave keywords as-is
GESHI_CAPS_UPPER: convert all keywords to uppercase where found
GESHI_CAPS_LOWER: convert all keywords to lowercase where found

since: 1.0.1

void set_case_keywords (int $case)

int $case: A constant specifying what to do with matched keywords

set_case_sensitivity (line 1202)

Sets whether a set of keywords are checked for in a case sensitive manner

since: 1.0.0

void set_case_sensitivity (int $key, boolean $case)

int $key: The key of the keyword group to change the case sensitivity of
boolean $case: Whether to check in a case sensitive manner or not

set_code_style (line 824)

Sets the style for the actual code. This should be a string

containing valid stylesheet declarations. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

Note: Use this method to override any style changes you made to the line numbers if you are using line numbers, else the line of code will have the same style as the line number! Consult the GeSHi documentation for more information about this.

since: 1.0.2

void set_code_style (string $style, [boolean $preserve_defaults = false])

string $style: The style to use for actual code
boolean $preserve_defaults: Whether to merge the current styles with the new styles

set_comments_highlighting (line 972)

Turns highlighting on/off for comment groups

since: 1.0.0

void set_comments_highlighting (int $key, [boolean $flag = true])

int $key: The key of the comment group to turn on or off
boolean $flag: Whether to turn highlighting for that group on or off

set_comments_style (line 957)

Sets the styles for comment groups. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_comments_style (int $key, string $style, [boolean $preserve_defaults = false])

int $key: The key of the comment group to change the styles of
string $style: The style to make the comments
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_encoding (line 1744)

Sets the encoding used for htmlspecialchars(), for international support.

NOTE: This is not needed for now because htmlspecialchars() is not being used (it has a security hole in PHP4 that has not been patched). Maybe in a future version it may make a return for speed reasons, but I doubt it.

since: 1.0.3

void set_encoding (string $encoding)

string $encoding: The encoding to use for the source

set_escape_characters_highlighting (line 1000)

Turns highlighting on/off for escaped characters

since: 1.0.0

void set_escape_characters_highlighting ([boolean $flag = true])

boolean $flag: Whether to turn highlighting for escape characters on or off

set_escape_characters_style (line 986)

Sets the styles for escaped characters. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_escape_characters_style (string $style, [boolean $preserve_defaults = false])

string $style: The style to make the escape characters
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_footer_content (line 1550)

Sets the content of the footer block

since: 1.0.2

void set_footer_content (string $content)

string $content: The content of the footer block

set_footer_content_style (line 1570)

Sets the style for the footer content

since: 1.0.2

void set_footer_content_style (string $style)

string $style: The style for the footer content

set_header_content (line 1540)

Sets the content of the header block

since: 1.0.2

void set_header_content (string $content)

string $content: The content of the header block

set_header_content_style (line 1560)

Sets the style for the header content

since: 1.0.2

void set_header_content_style (string $style)

string $style: The style for the header content

set_header_type (line 746)

Sets the type of header to be used.

If GESHI_HEADER_DIV is used, the code is surrounded in a "div".This means more source code but more control over tab width and line-wrapping. GESHI_HEADER_PRE means that a "pre" is used - less source, but less control. Default is GESHI_HEADER_PRE.

From 1.0.7.2, you can use GESHI_HEADER_NONE to specify that no header code should be outputted.

since: 1.0.0

void set_header_type (int $type)

int $type: The type of header to be used

set_highlight_lines_extra_style (line 1699)

Sets the style for extra-highlighted lines

since: 1.0.2

void set_highlight_lines_extra_style (string $styles)

string $styles: The style for extra-highlighted lines

set_important_styles (line 1630)

Sets styles for important parts of the code

since: 1.0.2

void set_important_styles (string $styles)

string $styles: The styles to use on important parts of the code

set_keyword_group_highlighting (line 942)

Turns highlighting on/off for a keyword group

since: 1.0.0

void set_keyword_group_highlighting (int $key, [boolean $flag = true])

int $key: The key of the keyword group to turn on or off
boolean $flag: Whether to turn highlighting for that group on or off

set_keyword_group_style (line 921)

Sets the style for a keyword group. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_keyword_group_style (int $key, string $style, [boolean $preserve_defaults = false])

int $key: The key of the keyword group to change the styles of
string $style: The style to make the keywords
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_language (line 659)

Sets the language for this object

since: 1.0.0
note: since 1.0.8 this function won't reset language-settings by default anymore! if you need this set $force_reset = true

void set_language (string $language, [ $force_reset = false])

string $language: The name of the language to use
$force_reset

set_language_path (line 703)

Sets the path to the directory containing the language files. Note that this path is relative to the directory of the script that included geshi.php, NOT geshi.php itself.

deprecated: The path to the language files should now be automatically detected, so this method should no longer be needed. The 1.1.X branch handles manual setting of the path differently so this method will disappear in 1.2.0.
since: 1.0.0

void set_language_path (string $path)

string $path: The path to the language directory

set_line_ending (line 1709)

Sets the line-ending

since: 1.0.2

void set_line_ending (string $line_ending)

string $line_ending: The new line-ending

set_line_style (line 844)

Sets the styles for the line numbers.

since: 1.0.2

void set_line_style (string $style1, [string|boolean $style2 = ''], [boolean $preserve_defaults = false])

string $style1: The style for the line numbers that are "normal"
string|boolean $style2: If a string, this is the style of the line numbers that are "fancy", otherwise if boolean then this defines whether the normal styles should be merged with the new normal styles or not
boolean $preserve_defaults: If set, is the flag for whether to merge the "fancy" styles with the current styles or not

set_link_styles (line 1606)

Sets styles for links in code

since: 1.0.2

void set_link_styles (int $type, string $styles)

int $type: A constant that specifies what state the style is being set for - e.g. :hover or :visited
string $styles: The styles to use for that state

set_link_target (line 1616)

Sets the target for links in code

since: 1.0.3

void set_link_target (string $target)

string $target: The target for links in the code, e.g. _blank

set_methods_highlighting (line 1162)

Turns highlighting on/off for methods

since: 1.0.0

void set_methods_highlighting (boolean $flag)

boolean $flag: Whether to turn highlighting for methods on or off

set_methods_style (line 1148)

Sets the styles for methods. $key is a number that references the

appropriate "object splitter" - see the language file for the language you are highlighting to get this number. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_methods_style (int $key, string $style, [boolean $preserve_defaults = false])

int $key: The key of the object splitter to change the styles of
string $style: The style to make the methods
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_numbers_highlighting (line 1131)

Turns highlighting on/off for numbers

since: 1.0.0

void set_numbers_highlighting (boolean $flag)

boolean $flag: Whether to turn highlighting for numbers on or off

set_numbers_style (line 1117)

Sets the styles for numbers. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_numbers_style (string $style, [boolean $preserve_defaults = false])

string $style: The style to make the numbers
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_overall_class (line 783)

Sets the overall classname for this block of code. This class can then be used in a stylesheet to style this object's output

since: 1.0.0

void set_overall_class (string $class)

string $class: The class name to use for this block of code

set_overall_id (line 794)

Sets the overall id for this block of code. This id can then be used in a stylesheet to style this object's output

since: 1.0.0

void set_overall_id (string $id)

string $id: The ID to use for this block of code

set_overall_style (line 767)

Sets the styles for the code that will be outputted when this object is parsed. The style should be a string of valid stylesheet declarations

since: 1.0.0

void set_overall_style (string $style, [boolean $preserve_defaults = false])

string $style: The overall style for the outputted code block
boolean $preserve_defaults: Whether to merge the styles with the current styles or not

set_regexps_highlighting (line 1191)

Turns highlighting on/off for regexps

since: 1.0.0

void set_regexps_highlighting (int $key, boolean $flag)

int $key: The key of the regular expression group to turn on or off
boolean $flag: Whether to turn highlighting for the regular expression group on or off

set_regexps_style (line 1176)

Sets the styles for regexps. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_regexps_style (string $key, boolean $style, [ $preserve_defaults = false])

string $key: The style to make the regular expression matches
boolean $style: Whether to merge the new styles with the old or just to overwrite them
$preserve_defaults

set_source (line 645)

Sets the source code for this object

since: 1.0.0

void set_source (string $source)

string $source: The source code to highlight

set_strings_highlighting (line 1103)

Turns highlighting on/off for strings

since: 1.0.0

void set_strings_highlighting (boolean $flag)

boolean $flag: Whether to turn highlighting for strings on or off

set_strings_style (line 1089)

Sets the styles for strings. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.0

void set_strings_style (string $style, [boolean $preserve_defaults = false])

string $style: The style to make the escape characters
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them

set_symbols_highlighting (line 1071)

Turns highlighting on/off for symbols

since: 1.0.0

void set_symbols_highlighting (boolean $flag)

boolean $flag: Whether to turn highlighting for symbols on or off

set_symbols_style (line 1051)

Sets the styles for symbols. If $preserve_defaults is true, then styles are merged with the default styles, with the user defined styles having priority

since: 1.0.1

void set_symbols_style (string $style, [boolean $preserve_defaults = false], [int $group = 0])

string $style: The style to make the symbols
boolean $preserve_defaults: Whether to merge the new styles with the old or just to overwrite them
int $group: Tells the group of symbols for which style should be set.

set_tab_width (line 1231)

Sets how many spaces a tab is substituted for

Widths below zero are ignored

since: 1.0.0

void set_tab_width (int $width)

int $width: The tab width

set_url_for_keyword_group (line 1594)

Sets the base URL to be used for keywords

since: 1.0.2

void set_url_for_keyword_group (int $group, string $url)

int $group: The key of the keyword group to set the URL for
string $url: The URL to set for the group. If {FNAME} is in the url somewhere, it is replaced by the keyword that the URL is being made for

set_use_language_tab_width (line 1247)

Sets whether or not to use tab-stop width specifed by language

since: 1.0.7.20

void set_use_language_tab_width (boolean $use)

boolean $use: Whether to use language-specific tab-stop widths

start_line_numbers_at (line 1728)

Sets what number line numbers should start at. Should be a positive integer, and will be converted to one.

Warning: Using this method will add the "start" attribute to the <ol> that is used for line numbering. This is not valid XHTML strict, so if that's what you care about then don't use this method. Firefox is getting support for the CSS method of doing this in 1.1 and Opera has support for the CSS method, but (of course) IE doesn't so it's not worth doing it the CSS way yet.

since: 1.0.2

void start_line_numbers_at (int $number)

int $number: The number to start line numbers at

Documentation generated on Thu, 25 Dec 2008 14:34:52 +0100 by phpDocumentor 1.4.2