Fork me on GitHub
Documentation: Index > User API Reference

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, $options=array())
luminous::highlight_file($language, $path, $options=array())
Note: in versions prior to 0.7, the third parameter was a boolean flag to switch on/off caching. This behaviour is preserved in 0.7 - you can still use a boolean flag instead of the options array. For options, keep reading this page.

$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.

Since 0.6.6:

luminous::cache_errors()
Returns a list of cache errors encountered for the most recent highlight, or FALSE if the cache was not enabled. See the cache page.

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.

Cache

Misc

Formatter

Formatting options relate to the display of highlighted output.