Hyperlight Redux

This is a fork of Hyperlight, cloned from the original Google Code repository. The intent is to make it installable via composer. And modernize the codebase.

I'm doing this so I can propose using it in a few projects that I'm currently using that could use PHP-based code highlighting.

I believe @klmr is the originator of this repository. If you notice this, feel free to contact me about it. Also, if you are a user of Hyperlight and you'd like to help me out with this, please feel welcome to submit a pull request.

At some point, unless I start working with @klmr, I will have to rename this.

Warning, changes afoot

Until everything is done, expect the documentation to not keep up. I'll be actively moving things around and making it all Composer friendly, so until that's all I probably won't keep the documentation up-to-date. It should, however continue to work. That doesn't apply to the Wordpress plugin. I won't touch it until everything else is all done. And I imagine I'll have to make a few changes, since both Wordpress and Hyperlight will have changed by then.

Also, I'll probably push changes up to GitHub periodically that will change things significantly over previous changes. For instance, I fully expect the namespace to change a few times before it's all done. Especially since there isn't one right now.

And once that's all done, I'll probably do some static site generator plugins. I'm currently using Sculpin for my personal projects, so that will be the first, but I know there are at least one or two more that are active, so I'll work with them as well.

Why use Hyperlight?

• Easy to use. There’s no configuration. The following code will highlight your source code. Nothing more needs to be said or done.

  <?php hyperlight('// Create a new hyperlight instance and print the highlighted code.
  $highlighter = new HyperLight($code, \'cpp\');
  $highlighter->theResult();', 'iphp'); ?>

  Even easier, there’s a handy function hyperlight() for lightweight usage, especially in HTML templates:

  <?php hyperlight('<?php hyperlight($code, \'php\'); ?>', 'php'); ?>

  This code creates a <pre> container around the code. This can be controlled with a third argument to the function.

• Easy to extend. 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.

• Powerful. The syntax definitions use regular expressions but they support stateful parsing through a very simple mechanism. This makes implementing context free grammars effortless.

• Full CSS support. One single CSS 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):

  <?php hyperlight(".comment { color: gray; }
  .comment .todo { font-weight: bold; }", 'css'); ?>

  Further refinements are possible in order to differentiate similar elements. Consider the different classes of keywords:

  <?php hyperlight(".keyword { color: #008; }
  .keyword.type { color: #088; }
  .keyword.operator { font-weight: bold; }", 'css'); ?>

• Colour schemes. This is basically the same as “full CSS support” but it sounds waaay cooler. Since CSS 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.

Why not use something else?

Sure, there are alternatives. Unfortunately, they are surprisingly few for PHP:

Geshi

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 CSS for all languages impossible (because they use the same CSS class names for completely different things), a lot of badly-documented configuration is necessary to get the desired result, HTML garbage is produced and the CSS class names are gibberish.

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.

If that doesn't matter to you, Geshi is perhaps not such a bad choice.

Pear_TextHighlighter

Syntax definitions must be given as cumbersome XML files. Need I say more?