• Added support for line numbers (boolean option: lineNumbers)
• Added a selection helper for Internet Explorer and Mozilla
• Improved the PHP recipe for working fine with Safari too
• Improved crossbrowser support

Links

• download
• start page

Repeat Something n Times

/**
 * Repeat something n times
 */
$.repeat = function( n ) {
	return {
		times: function( something ) {
			for( var i = 0; i < n; i++ ) {
				something( i );
			}
			return this;
		}
	}
};

/*
 * Example: hip hip hurrah
 */
$.repeat(3).times( function( i ) { 
	$( 'body' ).append( '<span>' + (i < 2 ? "hip" : "hurrah") + ' </span>' );
} );

New Date Value (unique id)

/**
 * Return a new date value
 * 
 * Each call returns a value greater than the previous call
 */
$.newDateValue = (function() {
	var current = 0;
	return function() {
		do {
			var d = Number(new Date());
		} 
		while( current == d );
		return (current = d);
	}
})();

/*
 * Example: 4 unique ids, and 4 not unique
 */
$.repeat(4)
	.times( function( i ) {
		$( 'body' ).append( '<div>' + i + ': ' + $.newDateValue() + '</div>' );
	} )
	.times( function( i ) {
		$( 'body' ).append( '<div>' + i + ': ' + Number(new Date()) + '</div>' );
	} );

Counter

/**
 * Return a counter with three methods: next, current, and init
 */
$.counter = function() {
	var current = 0;
	var increment = 1;
	return {
		/**
		 * Initialize current value and increment
		 */
		  init: function( c, i ) {
			var newCurrent = parseInt( c, 10 ); 
			if (! isNaN( newCurrent )) {
				current = newCurrent;
			}
			var newIncrement = parseInt( i, 10 ); 
			if (! isNaN( newIncrement )) {
				increment = newIncrement;
			}
			return this;
		}
		/**
		 * Get the next value
		 */
		, next: function() { 
			return current += increment; 
		}
		/**
		 * Get the current value
		 */
		, current: function() { 
			return current; 
		}
	}
};

/*
 * Example: 1 2 3 3 1 -1 -3
 */
var k = $.counter();

$.repeat(3).times( function() {
	$( 'body' ).append( '<span>' + k.next() + ' </span>' );
} );

$.repeat(1).times( function() {
	$( 'body' ).append( '<span>' + k.current() + ' </span>' );
} );

k.init( null, -2 );

$.repeat(3).times( function() {
	$( 'body' ).append( '<span>' + k.next() + ' </span>' );
} );

If you want to match a large text, these expressions are not the best. I’ve prepared a simple test page where the GeSHi’s engine file, which is almost 120KB, is going to be matched by the regular expression you input.

In Firefox 2 the performance is quite good, about 100 ms on my PC, but in Internet Explorer 7 it takes more than 7 minutes !!!

The best catch-all regular expression is [\w\W]*, which employs about 50 ms in FF2, and 0 ms in IE7 !!! (yes, zero milliseconds)

Changes

• added support for a much better recipe format
• optimized regular expressions for speed
• moved project hosting to Google Code: jquery-chili-js
• removed support for the previous recipe format
• removed support for metaobjects
• removed support for nearly obsolete features
  

Links

• download
• start page

A new recipe format

Chili 2.0 supports a new recipe format which is a bit more structured than the old one and will make hard-to-highlight languages a thing of the past. BTW, old recipes won’t be accepted by Chili 2.0. (although a simple manual conversion is possible)

How to convert old recipes to the new format

First of all let’s see an example of how to convert a recipe in the old format to the new one.

What follows is a piece of recipe (for JavaScript) in the old format

{
	  ignoreCase: false
	, steps: {
		  ml_comment: { 
			exp: /\/\*[^*]*\*+(?:[^\/][^*]*\*+)*\//
		}
		, sl_comment: { 
			exp: /\/\/.*/
		}
		//...
	}
}

And here is the same piece in the new format

{
	  _name: 'js'
	, _case: true
	, _main: {
		  ml_comment: { 
			  _match: /\/\*[^*]*\*+(?:[^\/][^*]*\*+)*\//
			, _style: 'color: gray;'
		}
		, sl_comment: { 
			  _match: /\/\/.*/
			, _style: 'color: green;'
		}
		//...
	}
}

As you see, they are very similar. Here are all the differences:

1. property names beginning with an underscore are reserved words
2. _name didn’t exist before
3. _case replaces the old ignoreCase; _case is TRUE if the language is case sensitive, and FALSE otherwise; _case defaults to FALSE
4. _main replaces the old steps
5. _match replaces the old exp
6. _style didn’t exist before

_style makes a big difference with respect to the past: CSS styles can now be embedded into the recipe. Separate stylesheets are no longer supported by the autoloading engine, but you can load them by yourself, if you prefer to keep them apart.

Another important difference about CSS is that now Chili builds the class associated to a step, by prefixing the _name to the step name, separated by __ (a double underscore). So, for example, the class for the multiline comment will be js__ml_comment.

More expressive power with the new recipe format

Besides the minor changes described in the previous section, the new format is much more powerful thanks to the major improvement I’m going to describe here.

The old recipe format supported an optional replacement property of a step, by means of which you could customize how the highlighting was applied to the matched text. Such a feature was useful when you captured subexpressions and wanted to highlight them separately.

Now _replace replaces replacement (sic) and it’s still optional.

As before, if you don’t specify a _replace property, Chili will default to <span class=”$0″>$$</span>, where $0 and $$ refer to the name of the current step and the matched text respectively.

As before, _replace can also be a different string expression, like in the following step, extracted from the MySQL recipe

variable: { 
	  _match: /@([$.\w]+|([`\"\'])(?:(?:[^\2\\\r\n]*?(?:\2\2|\\.))*[^\2\\\r\n]*?)\2)/
	, _replace: '<span class="keyword">@</span><span class="variable">$1</span>'
	, _style: { keyword: 'color: navy;', variable: 'color: blue;' }
}

What to note in the above example:

1. you can specify a style for each of the involved classes, by using properties of an object
2. you must use a span for applying style to a text run

A big improvement

In Chili 2.0, _replace can also be a function, like in the following step, extracted from the new HTML recipe

// matches a starting tag of an element (with attrs)
// like "<div ... >" or "<img ... />"
, tag_start: { 
	  _match: /(<\w+)((?:\w|[?%]>|\W)*?)(\/>|>)/ 
	, _replace: function( all, open, content, close ) { 
		  return "<span class='tag_start'>" + this.x( open ) + "</span>" 
			  + this.x( content, '/tag_attrs' ) 
			  + "<span class='tag_start'>" + this.x( close ) + "</span>";
	}
	, _style: "color: navy; font-weight: bold;"
}

What to note in the above example:

1. when _replace is a function, it receives match and submatches as arguments, and inside
2. there is a valid this object which contains a magic x method, by which
3. a string can be escaped for HTML (like open and close), or
4. a string can be transformed by an expression (like content)

Chili 2.0 recipes are modular

A Chili 2.0 recipe contains blocks (like _main), which contain steps (like tag_start). An expression can be built for referencing each module, be it a recipe, a block, or a step. For example, /tag_attrs is the tag_attrs block in the current recipe.

One method to highlight them all

The JavaScript code inside a _replace function can use the x method of this.

x takes two arguments: a subject to process, and an optional module to use.

x returns the subject escaped for HTML if no module is given, or the module is not available, else it returns the result of applying the module to the subject using Chili 2.0.

If the ChiliBook option recipeLoading is true, any unavailable module will be automatically loaded.

The new HTML recipe

As an example, here is the new HTML recipe

{
	  _name: 'html'
	, _case: false
	, _main: {
		  doctype: { 
			  _match: /<!DOCTYPE\b(?:\w|\W)*?>/ 
			, _style: "color: #CC6600;"
		}
		, ie_style: {
			  _match: /(<!--\[[^\]]*\]>)((?:\w|\W)*?)(<!\[[^\]]*\]-->)/
			, _replace: function( all, open, content, close ) {
				return "<span class='ie_style'>" + this.x( open ) + "</span>" 
					  + this.x( content, '//style' ) 
					  + "<span class='ie_style'>" + this.x( close ) + "</span>";
			}
			, _style: "color: DarkSlateGray; font-weight: bold;"
		}
		, comment: { 
			  _match: /<!--(?:\w|\W)*?-->/ 
			, _style: "color: #4040c2;"
		}
		, script: { 
			  _match: /(<script\s+[^>]*>)((?:\w|\W)*?)(<\/script\s*>)/
			, _replace: function( all, open, content, close ) { 
				  return this.x( open, '//tag_start' ) 
					  + this.x( content, 'js' ) 
					  + this.x( close, '//tag_end' );
			} 
		}
		, style: { 
			  _match: /(<style\s+[^>]*>)((?:\w|\W)*?)(<\/style\s*>)/
			, _replace: function( all, open, content, close ) { 
				  return this.x( open, '//tag_start' ) 
					  + this.x( content, 'css' ) 
					  + this.x( close, '//tag_end' );
			} 
		}
		// matches a starting tag of an element (with attrs)
		// like "<div ... >" or "<img ... />"
		, tag_start: { 
			  _match: /(<\w+)((?:\w|[?%]>|\W)*?)(\/>|>)/ 
			, _replace: function( all, open, content, close ) { 
				  return "<span class='tag_start'>" + this.x( open ) + "</span>" 
					  + this.x( content, '/tag_attrs' ) 
					  + "<span class='tag_start'>" + this.x( close ) + "</span>";
			}
			, _style: "color: navy; font-weight: bold;"
		} 
		// matches an ending tag
		// like "</div>"
		, tag_end: { 
			  _match: /<\/\w+\s*>|\/>/ 
			, _style: "color: navy;"
		}
		, entity: { 
			  _match: /&\w+?;/ 
			, _style: "color: blue;"
		}
	}
	, tag_attrs: {
		// matches a name/value pair
		attr: {
			// before in $1, name in $2, between in $3, value in $4
			  _match: /(\W*?)([\w-]+)(\s*=\s*)((?:\'[^\']*(?:\\.[^\']*)*\')|(?:\"[^\"]*(?:\\.[^\"]*)*\"))/ 
			, _replace: "$1<span class='attr_name'>$2</span>$3<span class='attr_value'>$4</span>"
			, _style: { attr_name:  "color: green;", attr_value: "color: maroon;" }
		}
	}
}

What to note in the above example:

1. a _replace function can be used for applying a recipe to a text run inside another recipe, like the script an style steps, where highlighting of script and style elements is delegated to js and css recipes respectively
2. a _replace function can be used for isolating the parsing of a text run, like the tag_attrs step, where highlighting of name/value pairs happens only in the context of tag attributes

Module paths

A module path is an expression that identifies a Chili 2.0 module. A path has three components (though some can be hidden) separated by a / (forward slash), each with a specific meaning: recipe / block / step. (white space added for clarity)

Here is a list of all the combinations in a module path:

• recipe
  a module path like css refers to the entire css recipe
• recipe / block
  a module path like css/definition refers to the definition block of the css recipe
• recipe / block / step
  a module path like css/definition/property refers to the property step of the definition block of the css recipe
• / block
  a module path like /definition refers to the definition block of the current recipe
• / block / step
  a module path like /definition/property refers to the property step of the definition block of the current recipe
• / / step
  a module path like //property refers to the property step of the current block of the current recipe

As you see, leading slashes have a meaning.

Remember

• a recipe module invocation tries to match all the steps of the _main block
• a block module invocation tries to match all its steps
• a step module invocation tries to match just itself

Help request

I think that Chili 2.0 is pretty good at highlighting, but it needs more fine recipes to succeed. For this release I’ve rewritten some from scratch, and converted some others. I’m not a good programmer in languages other than the ones for which I rewrote a recipe. But if you are and have time and will, then you could write a Chili 2.0 recipe for your favorite language, together with a couple of working samples, and send all to me. I’d be very happy to add your contributed recipes to the project as soon as they are available.

Rewritten

• CSS
• HTML
• JavaScript
• PHP

Converted

• C++
• C#
• Delphi
• Java
• LotusScript
• MySQL

Setup and Examples

Here is the start page for Chili 2.0 where you’ll find setup instructions and some examples.

Head hooks

When building up a page, just before the closing tag of the head element, a theme should call actions hooked on wp-head. Those actions only need to output what they want to include into the head element, like script files.

What if a theme does not do that? Well, I’d include it into the so called “known issues”. For example, my last WordPress plugin, won’t work in this case. I think it’s better not to find a workaround, so that theme authors understand that they must follow WordPress standards.

On the other hand, there is also an admin-head hook, which is the wp-head hook counterpart when building up admin pages. For example, you could use the following function.

<?php


function load_into_head() { 
	$ADMIN_VIEW = "alert( 'Hello Admin!' );";
	$USERS_VIEW = "alert( 'Hello World!' );";
	?>
<script type="text/javascript">
	<?php

		if( is_admin() ) { echo $ADMIN_VIEW; }
		else             { echo $USERS_VIEW; } 
	?>
</script>
	<?php 
}

add_action( is_admin() ? 'admin_head' : 'wp_head', 'load_into_head' );

?>

Script API

WordPress provides also a good Script API that will let you do anything you want with script files, following WordPress standards. These are the main functions:

1. wp_deregister_script
2. wp_register_script
3. wp_enqueue_script
4. wp_print_scripts (action hook)
5. print_scripts_array (filter hook)

The general idea is that you write a function for loading your scripts using wp_deregister_script, wp_register_script, and wp_enqueue_script, and hook it on wp_print_scripts. If you also need to fine tune the order in which files are loaded or if they have to be loaded at all, then you can write another function and hook it on print_scripts_array.

deregister, register, and enqueue

wp_register_script let’s you create an alias and define dependencies for each script file. If a script file with the same alias was already registered, then your registration is ignored. This is a policy for conflict resolution (the first registration wins) that may help you, if you know it.

wp_deregister_script let’s you remove an alias. If the alias you give doesn’t exist, nothing happens. Tipically you use this function for forcing a new registration of an already registered alias: first you deregister and then register again.

wp_enqueue_script prepares the loading of a script. If the script was registered with some dependencies, this function automatically prepares their loading too, recursively, making sure each script will be loaded only once and before any script depending on it.

For example, jQuery 1.2.3 is registered by WordPress 2.5, but let’s say that you want to always download the latest version. You could use the following function.

<?php


function load_with_api() {
	wp_deregister_script( 'jquery' );
	wp_register_script( 'jquery', 'http://code.jquery.com/jquery-latest.pack.js', false, '' );

	//keep jQuery and Prototype compatible
	$url = get_bloginfo('wpurl').'/wp-content/plugins/my-plugin';
	wp_register_script( 'jquery_no_conflict', $url . '/jquery_no_conflict.js', array( 'jquery' ), '' );	
	wp_enqueue_script( 'jquery_no_conflict' );
}

add_action( 'wp_print_scripts', 'myOwnTheme_init' );

?>

Keeping jQuery and Prototype compatible is a needed functionality, because WordPress uses both and they both use $ as a global symbol. In fact, the jQuery file packed with WordPress includes the compatibility setting.

Fine tuning

If you want your scripts to be loaded in a particular order, with one script before or after another, maybe with respect to one that was registered by WordPress itself, or by other plugins, then you can write a function for the print_scripts_array filter.

For example, to load the jquery_no_conflict file just after the jquery file, you can use the following function.

<?php


function jquery_no_conflict_follows_jquery( $js_array ) {
	if ( false === $jquery = array_search( 'jquery', $js_array ) )
		return $js_array;

	if ( false === $jquery_no_conflict = array_search( 'jquery_no_conflict', $js_array ) )
		return $js_array;

	if ( $jquery_no_conflict == $jquery + 1 )
		return $js_array;

	array_splice( $js_array, $jquery + 1, 0, 'jquery_no_conflict' );

	unset($js_array[$jquery_no_conflict + ($jquery_no_conflict < $jquery ? 0 : 1)]);

	return $js_array;
}

add_filter( 'print_scripts_array', 'jquery_no_conflict_follows_jquery' );

?>

My Own Theme

If you want to see all this in action, you can install the My Own Theme plugin.

Really it’s very useful and simple to undestand and use for flat properties.

jQuery.extend( 
  { a:1, b:'2' }, 
  { a:'1', c:3 } 
) == 
  { a:'1', b:'2', c:3 }

On the contrary, if the involved objects have object properties, jQuery.extend is less intuitive and less useful too.

jQuery.extend( 
  { a:{ x:1 }, b:'2' }, 
  { a:{ y:'1' }, c:3 } 
) == 
  { a:{ y:'1' }, b:'2', c:3 }

Luckily, an undocumented feature (deep) makes jQuery.extend recurr object properties.

jQuery.extend( true, 
  { a:{ x:1 }, b:'2' }, 
  { a:{ y:'1' }, c:3 } 
) == 
  { a:{ x:1, y:'1' }, b:'2', c:3 }

Unluckily, deep only works for the first level. (not really a ‘bug’)

jQuery.extend( true, 
  { a:{ x:1, z:{ m: '' } }, b:'2' }, 
  { a:{ y:'1', z:{ n: 0 } }, c:3 } 
) == 
  { a:{ x:1, y:'1', z:{ n:0 } }, b:'2', c:3 }

If you need deep recursion use jQuery.extend_deep instead.

jQuery.extend_deep( true, 
  { a:{ x:1, z:{ m: '' } }, b:'2' }, 
  { a:{ y:'1', z:{ n: 0 } }, c:3 } 
) == 
  { a:{ x:1, y:'1', z:{ m:'', n:0 } }, b:'2', c:3 }

Here is the jQuery.extend_deep plugin:

/**
 * Implement deep object extension 
 * by replacing the line 599 of jQuery-1.2.3.js
 * (commented out in this function)
 */
jQuery.extend_deep = function() {
	var target = arguments[0] || {}, i = 1, length = arguments.length, deep = false, options;

	if ( target.constructor == Boolean ) {
		deep = target;
		target = arguments[1] || {};
		i = 2;
	}

	if ( typeof target != "object" && typeof target != "function" )
		target = {};

	if ( length == 1 ) {
		target = this;
		i = 0;
	}

	for ( ; i < length; i++ )
		if ( (options = arguments[ i ]) != null )
			for ( var name in options ) {
				if ( target === options[ name ] )
					continue;

				if ( deep && options[ name ] && typeof options[ name ] == "object" && target[ name ] && !options[ name ].nodeType )
//					target[ name ] = jQuery.extend( target[ name ], options[ name ] );
					target[ name ] = jQuery.extend_deep( true, target[ name ], options[ name ] );

				else if ( options[ name ] != undefined )
					target[ name ] = options[ name ];

			}

	return target;
};

• Added support for easy namespacing
• Added support for jQuery 1.2.3 cache
• Rewritten the manual from scratch

Download

You can download metaobjects from Google Code

Although it’s easy to use WP Chili out of the box, WordPress does have some limitations, like the following:

• you need to change to the Code editor before adding a snippet to your post
• you need to make your snippet postable yourself, escaping all HTML entities
• even if snippets are very short, they are intermingled with their explanations and it’s tricky to concentrate on writing the best post with so many distractions in between

Using WP Chili & Enzymes

Now I’ll show you a better approach by using together WP Chili 1.0 and Enzymes 2.2.
All you need to be up and running is the classical roundtrip: download, unzip, upload, and activate.

How to highlight code snippets

You can start by writing a simple enzyme for automating things, like the following hilite custom field:

return 
'<pre><code class="' . $this->substrate . '">'
. htmlspecialchars( $this->pathway ) 
. '</code></pre>';

hilite can be used with the following patterns:

1. {[ =snippet= | .hilite( =language= ) ]}
2. {[ .snippet | .hilite( =language= ) ]}

The first pattern comes in handy when you want to highlight some very short and naive snippet
{[ =echo htmlentities( $name );= | .hilite( =php= ) ]} renders

echo htmlentities( $name );

So far, so good, but if the snippet has a character that WP texturizes, then hilite seems to fail. In fact
{[ =$welcome \= “Hello “.$name;= | .hilite( =php= ) ]} renders

$welcome = “Hello “.$name;

The above issue is not a hilite’s bug but it could be fixed by adding new code to it, or with new enzymes along the pathway, like the following requote custom field:

$from = array( '‘', '’', '“', '”' );
$to = array( "'", "'", '"', '"' );
return str_replace( $from, $to, $this->pathway );

which makes that
{[ =$welcome \= “Hello “.$name;= | .requote() | .hilite( =php= ) ]} renders

$welcome = "Hello ".$name;

The best option is to add another custom field for hosting your snippet and use the second pattern: in fact hilite’s snippet has been rendered by {[ .hilite | .hilite( =php= ) ]} and requote’s one by {[ .requote | .hilite( =php= ) ]}.

How to highlight code files

Sometimes you have a file that you want to show in its entirety, and having to copy it into a custom field is annoying or maybe not an option, if the file is alive, for example.

In such cases you can use an enzyme like the following file custom field:

return file_get_contents( $this->substrate );

It’s use is again very simple and very similar to the above patterns:
{[ .file( =blog/wp-content/plugins/hello.php= ) | .hilite( =php= ) ]} renders

<?php
/*
Plugin Name: Hello Dolly
Plugin URI: http://wordpress.org/#
Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.
Author: Matt Mullenweg
Version: 1.5
Author URI: http://photomatt.net/
*/

// These are the lyrics to Hello Dolly
$lyrics = "Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
So, take her wrap, fellas
Find her an empty lap, fellas
Dolly'll never go away again
Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
Golly, gee, fellas
Find her a vacant knee, fellas
Dolly'll never go away
Dolly'll never go away
Dolly'll never go away again";

// Here we split it into lines
$lyrics = explode("\n", $lyrics);
// And then randomly choose a line
$chosen = wptexturize( $lyrics[ mt_rand(0, count($lyrics) - 1) ] );

// This just echoes the chosen line, we'll position it later
function hello_dolly() {
	global $chosen;
	echo "<p id='dolly'>$chosen</p>";
}

// Now we set that function up to execute when the admin_footer action is called
add_action('admin_footer', 'hello_dolly');

// We need some CSS to position the paragraph
function dolly_css() {
	echo "
	<style type='text/css'>
	#dolly {
		position: absolute;
		top: 2.3em;
		margin: 0;
		padding: 0;
		right: 10px;
		font-size: 16px;
		color: #d54e21;
	}
	</style>
	";
}

add_action('admin_head', 'dolly_css');

?>

After activating WP Chili, it’s just a matter of wrapping your snippets into code or pre-code elements, with the programming language of the snippet as a class, like in the following example:

<pre><code class="php">
echo &quot;Hello $name&quot;;
</code></pre>

When the post reaches your readers, the snippet is unescaped by their browser and highlighted by Chili 1.9 (downloaded from your server). Your readers will see the example rendered as:

echo "Hello $name";

• Added the new feature for transcluding a value, rather than a post/key reference to it (which is still available). This comes in handy when you have a “normal” value and it’s a bit annoying to define a custom field just for that.

For example, let’s say that you have a template called mark-template.php with the following code:

<span style="background-color:<?php echo $this->enzyme; ?>;">
	<?php 
		echo $this->pathway; 
		$this->pathway = ''; 
	?>
</span>

Then you could use it {[ =like this= | =cyan= \mark-template.php ]} to get something like this

Download

This version is available for download from wordpress.org