public static function add($function, $text, $sample = '', $params = '')
{
if ($sample) {
$sample = hyperlight($sample);
}
static::$docs[] = compact(array('function', 'text', 'sample', 'params'));
}
<link rel="stylesheet" type="text/css" href="../../colors/zenburn.css" id="theme"/>
</head>
<body>
<div id="head">
<div class="text">
<h1>Documentation</h1>
</div>
</div>
<div id="content">
<div id="swoosh"></div>
<div class="text">
<h2>Frequently Asked Questions</h2>
<dl>
<dt><h3>The PHP highligher is broken, right?</h3></dt>
<dd>
<p>Yes – unfortunately. This is by design. In our defence, <em>no</em> correct <acronym>PHP</acronym> highligher exists. To see why, consider the following code fragment, which is completely valid <acronym>PHP</acronym>:</p>
<?php
hyperlight('<p class="some-class<?php if (rand(0, 1) === 1) echo \'"\'; ?>>foo</p>', 'php');
?>
<p>(On a related note, this code fragment actually breaks the editor this text was written in.)</p>
<p>Executing this code <em>might</em> produce valid <acronym>HTML</acronym> – or it might not, depending on the outcome of the coinflip. The editor (or, in our case, highlighter) has no idea about the outcome without executing the code. And even then, the result changes with every subsequent execution. But even if the above code were more predictable, it would have to be executed in order to determine how to highlight the code. This is not done by Hyperlight or any other highlighting engine. The output is therefore wrong in a few cases. Fortunately, such cases should be relatively rare.</p>
</dd>
</dl>
</div>
</div>
</body>
</html>
<!-- vim:ft=html
-->
<script type="text/javascript">
// Add CSS to hyperlight dynamically, so not all pages get this.
$(function() {
$('head').append('<link rel="stylesheet" type="text/css" href="colors/lightness.css">');
});
</script>
<blockquote class="all-rounded ui-widget">
<?php
require dirname(__FILE__) . '/hyperlight/hyperlight.php';
hyperlight('
$BASE_PATH = dirname(__FILE__);
$DEPENDS_PATH = ".;".$BASE_PATH;
$DEPENDS_PATH .= ";".$BASE_PATH."/lib";
$DEPENDS_PATH .= ";".$BASE_PATH."/test";
ini_set("include_path", ini_get("include_path").";".$DEPENDS_PATH);
?>', 'php');
?>
</blockquote>
<div id="sql-test">
<?php
define("PARSER_LIB_ROOT", dirname(__FILE__) . "/sqlparserlib/");
require_once PARSER_LIB_ROOT . "sqlparser.lib.php";
function SQLFormatPHP($in)
{
return PMA_SQP_formatHtml(PMA_SQP_parse($in), 'text');
}
$sql = <<<EOB
/**
* Is the same as:
* <code>
* hyperlight(file_get_contents($filename), $lang, $tag, $attributes);
* </code>
* @see hyperlight()
*/
function hyperlight_file($filename, $lang = null, $tag = 'pre', array $attributes = array())
{
if ($lang == '') {
// Try to guess it from file extension.
$pos = strrpos($filename, '.');
if ($pos !== false) {
$ext = substr($filename, $pos + 1);
$lang = HyperLanguage::nameFromExt($ext);
}
}
hyperlight(file_get_contents($filename), $lang, $tag, $attributes);
}
}
} else {
$colorscheme = $default_colorscheme;
}
write_prolog('Hyperlight tests', $colorscheme, isset($_GET['debug']));
?>
<h2>A few small tests:</h2>
<p>Look, ma: Inline code. Start off by writing <?php
hyperlight('#include <iostream>', 'cpp', 'code');
?>
at the beginning of your newly-created <code>main.cpp</code> file.
Then you can insert the following code below:</p>
<?php
hyperlight('int main() {
std::cout << "Hello, world!" << std::endl;
}', 'cpp');
?>
<p>Next, let's compile this code and execute it. This is done easily on the console:</p>
<pre>$ g++ -Wall -pedantic -o main main.cpp
$ ./main
Hello, world!</pre>
Congratulations! You've just run your first C++ program.
<?php
$args = array_diff_key($_GET, array('debug' => '', 'style' => ''));
$args = array_keys($args);
$tests = empty($args) ? array() : explode(',', implode(',', $args));
if (!empty($tests)) {
echo '<p>Showing only test(s) <strong>' . implode(', ', $tests) . '</strong>.</p>';
}
hyperlight_test('python');
<p>The user guide aims to ease the first steps in using Hyperlight. Luckily, the interface is really easy to use, mainly because it’s also really small (remember: this is a <em>good</em> thing). Most of the configuration goes on behind the scenes or in the <acronym>CSS</acronym>.</p>
<p>The first part will focus on the end user. However, most users will probably want to customize behaviour in one way or another. We will therefore also discuss how to modify or create themes and syntax definitions. And so, without further ado …</p>
<a id="getting-started"></a><h3>Getting Started</h3>
<p>At this point, let’s assume that you have already downloaded and unzipped the package into its target location because let’s face it, who wants to have an umpteenth description of how to unzip an archive?</p>
<p>To use Hyperlight, all you have to do is to include the main file into your <acronym>PHP</acronym> source code and invoke the highlighting function. To highlight a source code, this is all you need to do:</p>
<?php
hy('hyperlight($code, $language);', 'iphp');
?>
<p>To put this in some more context, imagine that you want to highlight the current file. Our program might not be self-replicating or self-modifying but it sure is self-embellishing.</p>
<?php
hyf('code1.php');
?>
<p>It really can’t get much simpler than that.</p>
<p>Notice that we didn’t have to put special <acronym>HTML</acronym> tags around our code. <a href="../ref/#hyperlight-function"><code>hyperlight</code></a> does this for us. But don’t worry about lack of control. This function has two more optional arguments that you can use to control how these surrounding tags should look like. The first controls which surrounding tag to use and defaults to – what a surprise – <?php
hyperlight('<pre>', 'xml', 'code');
?>
. The second argument controls the attributes that the tag should have (in addition to the <code>class</code>). For a detailed description of how to use these arguments, read the reference entry on the <a href="../ref/#hyperlight-function"><code>hyperlight</code></a> function.</p>
<div class="notice">
<p>Regardless of the fourth argument, the <code>class</code> attribute is <strong>always</strong> present and can’t be removed – and shouldn’t be: it’s necessary for the <acronym>CSS</acronym> themes to work.</p>
</div>
<p><acronym>PHP</acronym> is something of a special case; it requires a <code><?php</code> to start a <acronym>PHP</acronym> block. However, when posting code, this is often omitted because only a short snippet is posted. That’s fine. Hyperlight offers a special language tag for this rather unique case: <code>iphp</code>.</p>
<?php
hy('hyperlight($code, \'iphp\');', 'iphp');
?>
<p>Another special case occurs when we want to highlight a file. Hyperlight provides a shortcut to do this: <a href="../ref/#hyperlight_file-function"><code>hyperlight_file</code></a>. As an added bonus, if you pass a regular file to this function, you don’t need to specify the file’s language explicitly. Hyperlight tries to figure the right language out by itself, based on the filename extension.</p>
<p>Now, that’s all there really is to it. Told you it was easy. ;-) But trust me, it gets more <em>interesting</em> once we want to create our own themes or language definitions.</p>
<a id="creating-themes"></a><h3>Creating Themes</h3>
<div class="text">
<ul id="switch-buttons">
<li><a href="" class="active" id="theme-zenburn">Zenburn</a></li>
<li><a href="" id="theme-vibrant-ink">Vibrant Ink</a></li>
</ul>
<?php
hyperlight('function preg_strip($expression) {
$regex = \'/^(.)(.*)\\\\1([imsxeADSUXJu]*)$/s\';
if (preg_match($regex, $expression, $matches) !== 1)
return false;
$delim = $matches[1];
$sub_expr = $matches[2];
if ($delim !== \'/\') {
// Replace occurrences by the escaped delimiter by its unescaped
// version and escape new delimiter.
$sub_expr = str_replace("\\\\$delim", $delim, $sub_expr);
$sub_expr = str_replace(\'/\', \'\\\\/\', $sub_expr);
}
$modifiers = $matches[3] === \'\' ?
array() : str_split(trim($matches[3]));
return array($sub_expr, $modifiers);
}', 'iphp');
?>
</div>
</div>
</body>
</html>
<!-- vim:ft=html
-->
<?php
require 'path/to/hyperlight.php';
?>
<html>
<head>
<title>Very simple test for Hyperlight</title>
<link rel="stylesheet" type="text/css" href="colors/zenburn.css">
</head>
<body>
<?php
hyperlight(file_get_contents(__FILE__), 'php');
?>
</body>
</html>
<hgroup role="banner">
<h1>Documentation</h1>
</hgroup>
<section id="content">
<?php
require PATH . 'includes/sidebar' . EXT;
?>
<div class="primary">
<h2>Requirements</h2>
<p>In order to remain lightweight, Anchor only supports recent versions of the languages it’s written in. As such, you will need:</p>
<ul>
<li>PHP 5.3 (or newer)</li>
<li>MySQL (and access to a database)</li>
</ul>
<p>If you’re not sure what version of PHP you have, create a new file, and paste the following in at the top of the page:</p>
<?php
hyperlight('<?php echo phpversion(); ?>');
?>
<p>This should print a number to your screen, which should be bigger than 5.3.</p>
<p>If you don’t have the necessary requirements, you will not be able to install Anchor, and should contact your webhost to upgrade.</p>
</div>
</section>
<p>This code creates a <code><pre></code> container around the code. This can be controlled with a third argument to the function.</p>
</li>
<li>
<p><strong>Easy to extend.</strong> The syntax definitions are written in PHP but only very basic language grasp is needed. Syntax definitions are concise and for most tasks, existing templates can be used and it’s enough to customize a basic set of features.</p>
</li>
<li>
<p><strong>Powerful.</strong> The syntax definitions use regular expressions but they support stateful parsing through a very simple mechanism. This makes implementing context free grammars effortless.</p>
</li>
<li>
<p><strong>Full <acronym>CSS</acronym> support.</strong> One single <acronym>CSS</acronym> file can be used for all languages to give a consistent look & feel. Elements may be nested for refinements (e.g. highlighting “TODO” items in comments):</p>
<?php
hyperlight(".comment { color: gray; }\n.comment .todo { font-weight: bold; }", 'css');
?>
<p>Further refinements are possible in order to differentiate similar elements. Consider the different classes of keywords:</p>
<?php
hyperlight(".keyword { color: #008; }\n.keyword.type { color: #088; }\n.keyword.operator { font-weight: bold; }", 'css');
?>
</li>
<li>
<p><strong>Colour schemes!</strong> – This is basically the same as “full <acronym>CSS</acronym> support” but it sounds <em>waaay</em> cooler. Since <acronym>CSS</acronym> support is naturally included in Hyperlight and syntax files can define appropriate mappings for their lexemes, usage and creation of professional colour schemes is effortless.</p>
</li>
</ul>
<h2>Why not use something else?</h2>
<p>Sure, there are alternatives. Unfortunately, they are surprisingly few for PHP:</p>
<h3>Geshi</h3>
<p>If you’re forced to work with PHP version < 5.0, sure, use Geshi. But be prepared that each syntax brings its own (ugly) style, lacking conventions make the use of one <acronym>CSS</acronym> for all languages impossible (because they use the same <acronym>CSS</acronym> class names for completely different things), a lot of badly-documented configuration is necessary to get the desired result, <acronym>HTML</acronym> garbage is produced and the <acronym>CSS</acronym> class names are gibberish.</p>
<p>Furthermore, many of the syntax definitions are badly realized and/or have bugs. Creating an own highlighting isn't trivial because the API is quite complicated, not very powerful and lacks documentation.</p>
<p>If that doesn't matter to you, Geshi is perhaps not such a bad choice.</p>
