# parent: index
User's API reference
Introduction
This document gives a relatively high level overview of the user's API. For full API documentation, see the Doxygen HTML files in your distribution.The entirety of the public API is contained within a class called luminous. This is used as a namespace, the methods within are static, which means you can call them directly without instantiating the class. For those unfamiliar with the syntax or terminology, this just means that you call the functions as normal but place luminous:: in front of it. This is as it is shown on this page.
The functions in this namespace interact with a theoretically private singleton object called $luminous_. You should be aware of this if only to avoid overwriting it.
Basic Functions
The two main highlighting functions are:luminous::highlight($language, $source, $cache=true)
luminous::highlight_file($language, $path, $cache=true)
Note that $language can be a language code (open supported.php in a browser to see a list of what you have available), or your own instance of LuminousScanner.Since 0.6.2 you can ask Luminous to guess the language of a piece of source code with the function:
luminous::guess_language($src, $confidence=0.05, $default='plain')
This will return a valid language code for the most-probable language. $confidence and $default are related: if no scanner is willing to say with above 0.05 (5%) certainty that it owns the source code, then $default is returned. It's probably best to leave this at 0.05.warning: For obvious reasons, laguage guessing is inherently unreliable. Luminous will try to latch on to unique parts of the language, but this is difficult in languages like C, C# and Java, which are syntactically very similar.
luminous::head_html()
This will output several link and script tags. It tries to determine the correct path to the luminous/ directory relative to the document root, but may fail. In this case, you can override it to set it manually. The settings: 'theme', 'relative-root', 'include-javascript' and 'include-jquery' affect this.Themes
luminous::themes()
luminous::theme_exists($theme_name)
themes() returns a list of themes present in the style/ directory. Use this if you're building a theme selector.theme_exists() returns true if a theme exists in the style/ directory, else false.
Settings
luminous::set($name, $value)
Sets an internal setting to the given value. An exception is raised if the setting is unrecognised.Since 0.6.2, you can set the first argument as an array of $name => $value, and omit the second argument.
luminous::setting($name)
Returns the value currently set for the given setting. An exception is raised if the setting is unrecognised.List of observed settings
Note: What's listed here might not reflect your version. A definitive list of settings can be found in Doxygen (the LuminousOptions class) as of 0.6.2.As with php, setting an integer setting to 0 or -1 will disable it. As of 0.6.2 some validation is applied to these options and exceptions will be thrown if you try to do something nonsensical.
Misc
- cache-age (int): age (seconds) at which to remove cached files (age is determined by mtime -- cache hits trigger a 'touch', so this setting removes cached files which have not been accessed for the given time.), 0 or -1 to disable. (default: 777600 : 90 days)
- include-javascript (bool): controls whether luminous::head_html() outputs the javascript 'extras'.
- include-jquery (bool): controls whether luminous::head_html() outputs jquery; this is ignored if include-javascript is false.
- relative-root (str): luminous::head_html() has to know the location of the luminous directory relative to the location of the document root. It tries to figure this out, but may fail if you are using symlinks. You may override it here.
- theme: Sets the internal theme. The LaTeX and html-full formatters read this, and luminous::head_html observes this.
- sql-function: See the cache page.
Formatter
Formatting options relate to the display of highlighted output.- auto-link (bool): if the formatter supports hyperlinking, URIs will be linked
- html-strict (bool): Luminous uses the 'target' attribute of <a> tags. This is not valid for X/HTML4 strict, therefore it may be disabled. Note that this is purely academic: browsers don't care. Luminous produces valid HTML5 and HTML4 transitional output regardless.
- line-numbers (bool): If the formatter supports line numbering, lines are numbered. (default: true)
- max-height (int): if the formatter can control its height, it will constrain itself to this many pixels (you may specify this as a string with units) (default: 500)
- wrap-width (int): if the formatter supports line wrapping, lines will be wrapped at this number of characters (0 or -1 to disable) (default: -1)
- format (string): Controls the output format:
- 'html' (default): HTML. The HTML is contained in a <div> element. CSS must be included on the same page.
- 'html-full': A full HTML page. The page is a valid and self-contained HTML document and includes all necessary CSS.
- 'html-inline': This is a small variation on the HTML formatter which styles output for inline (in-text) display. The output is in an inline-block element, with line numbers and height constraints disabled. You probably want HTML.
- 'latex': LaTeX.
- 'none', null: the 'identity' formatter, i.e. no formatting is applied. The result is basically an XML fragment, the way Luminous embeds highlighting data in the string internally. This is implemented for debugging.