Beautifier Plugin

Provides the %CODE% and %ENDCODE% macros to display code fragments with formatting and syntax highlighting for improved readbility in wiki topics.

Related topics: dp.SyntaxHighlighter

Introduction

Use the %CODE% and %ENDCODE% macros to enclose fragments of code in your topic that you wish to have displayed with appropriate syntax hightlighting and formatting for better readability and presentation.

This plugin was derived from Mike Jewell's popular Beautifier: Flexible Syntax Highlighter package. The original PHP code of the Beautifier library has been ported to Perl for use with Foswiki and this plugin.

Syntax

  • Syntax: %CODE%%ENDCODE% or %CODE{…}%%ENDCODE%
  • %CODE%%ENDCODE% encapsulates a code fragment to be displayed using the default language syntax and CSS styling
  • %CODE{…}%%ENDCODE% encapsulates a code fragment to be displayed allowing the language syntax and CSS styling to be overridden according to any parameters supplied
  • Supported parameters:
    Parameter: Description: Default
    "language" The language syntax identifier "cpp"
    css="URL" The URL of a CSS stylesheet that extends the plugin's default styling for code fragments  
  • Supported language syntaxes:
    Language: Identifier: Language: Identifier: Language: Identifier:
    bash "bash"   Lua "lua"   Scheme "scheme"
    C++ "cpp"   Makefile "makefile"   TCL "tcl"
    C# "csharp"   Perl "perl"   Verilog "verilog"
    HTML "html"   PHP3 "php3"   VHDL "vhdl"
    Java "java"   PL/SQL "plsql"   XML "xml"
    JavaScript "javascript"   Python "python"      
    • The Beautifier package supports many, many more language syntaxes but only the languages above have been ported to Foswiki at this point. If you need support for an additional syntax, please open an Enhancement Request to request the syntax you require.
  • DOM Structure: The beautified code fragment is encapsulated within a <pre> element which, in turn, is encapulated within a <div> element which has two CSS class selectors, "fragment" and the language syntax identifier, which is itself encapsulated within a <div> element with the CSS class selector "BeautifierPlugin" as illustrated below.
    • <div class="BeautifierPlugin">
      • <div class=" language fragment">
        • <pre>
          • … beautified code fragment …
        • </pre>
      • </div>
    • </div>
    • Language-specific CSS styling can be applied to the beautified code fragment using CSS selectors of the form div.BeautifierPlugin div.language.fragment
    • Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.

Examples

The following examples illustrate the basic operation of the plugin and the %CODE% and %ENDCODE% macros.

Current default settings:
  • BEAUTIFIERPLUGIN_LANGUAGE is: cpp
  • BEAUTIFIERPLUGIN_CSS is: /fw/pub/Main/SitePreferences/style_extension_With.css

C++ Syntax

This example illustrates the basic use of the plugin to beautify a code fragment. The default language syntax is assumed to be C++ unless otherwise specified by the %CODE% macro or the BEAUTIFIERPLUGIN_LANGUAGE preference setting.

For the following code fragment:

%CODE{"cpp"}%
#include 

/**
    @brief Advance the simulation by one timeslice.
*/
void nWorld::StepSim()
{
    // Iterate simulation loop
    for (node = entityList.GetHead(); node != NULL && j == 53; node = node→GetSucc())
    {
        entity = (nEntity*)node→GetPtr();
        entity→Trigger(this, this→stepSize);
    }
}
%ENDCODE%
  

You would get (simulated):

#include <nworld.h>

/**
@brief Advance the simulation by one timeslice.
*/
void nWorld::StepSim()
{
        // Iterate simulation loop
        for (node = entityList.GetHead(); node != NULL; node = node→GetSucc())
        {
                entity = (nEntity*)node→GetPtr();
                entity→Trigger(this, this→stepSize);
        }
}

You would get (actual):

#include <nworld.h>

/**
@brief Advance the simulation by one timeslice.
*/
void nWorld::StepSim()
{
        // Iterate simulation loop
        for (node = entityList.GetHead(); node != NULL && j == 53; node = node→GetSucc())
        {
                entity = (nEntity*)node→GetPtr();
                entity→Trigger(this, this→stepSize);
        }
}

Lua Syntax With Custom CSS Styling

This example illustrates using the Lua syntax highlighting rules and also demonstrates how to modify the styling of display elements to define additional language-specific styling of the beautified code fragment. The URL of a custom stylesheet may be specified by the css paraemter of %CODE% macro or the BEAUTIFIERPLUGIN_CSS preference setting.

The extension stylesheet adds the following CSS styling rules to alter the outer border from pale yellow to pale pink and to make any colorized text bold.

div.BeautifierPlugin div.lua.fragment {
        background: #FFCCFF;
}
div.BeautifierPlugin div.lua.fragment font {
        font-weight: bold;
}

For the following code fragment:

%CODE{"lua" css="%ATTACHURL%/style_extension.css"}%
Account = {}
Account.__index = Account

function Account.create(balance)
   local acnt = {}             -- our new object
   setmetatable(acnt,Account)  -- make Account handle lookup
   acnt.balance = balance      -- initialize our object
   return acnt
end

function Account:withdraw(amount)
   self.balance = self.balance - amount
end

-- create and use an Account
acc = Account.create(1000)
acc:withdraw(100)
%ENDCODE%
  

You would get (simulated):

Account = {}
Account.__index = Account

function Account.create(balance)
   local acnt = {}             -- our new object
   setmetatable(acnt,Account)  -- make Account handle lookup
   acnt.balance = balance      -- initialize our object
   return acnt
end

function Account:withdraw(amount)
   self.balance = self.balance - amount
end

-- create and use an Account
acc = Account.create(1000)
acc:withdraw(100)

You would get (actual):

Account = {}
Account.__index = Account

function Account.create(balance)
   local acnt = {}             -- our new object
   setmetatable(acnt,Account)  -- make Account handle lookup
   acnt.balance = balance      -- initialize our object
   return acnt
end

function Account:withdraw(amount)
   self.balance = self.balance - amount
end

-- create and use an Account
acc = Account.create(1000)
acc:withdraw(100)

Unknown Syntax

If a language syntax is specified that the plugin doesn't know how to handle, it will simply display an error message and display the code fragment without any additional formatting or highighting applied.

For the following code fragment:

%CODE{"klingon"}%
	Heghlu'meH QaQ jajvam
%ENDCODE%
  

You would get (simulated):

bomb Language 'klingon' not supported

	Heghlu'meH QaQ jajvam

You would get (actual):

bomb Language 'klingon' not supported

	Heghlu'meH QaQ jajvam

Preference Settings

The default expansion of the %CODE% macro may be altered by setting Foswiki preference settings. These settings can be placed in your wiki's Site Preferences topic, your web's Web Preferences topic, your own User Preferences topic, or the topic in which the %CODE% macro is used.

Setting Description Default
CSS The URL of an optional CSS stylesheet to use for styling display elements generated by the plugin  
DEBUG Enable/disable logging of debug traces to the Foswiki Debug Log off
LANGUAGE The default language syntax to use when beautifying a code fragment cpp

Note: In the table above, the "BEAUTIFIERPLUGIN_" prefix has been omitted from each of the setting names for brevity. In order to make use of a setting, you must use the full name of the setting including the prefix (e.g., "BEAUTIFIERPLUGIN_CSS").

warning Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.

Setting Plugin Preferences

Use TML assignment statements in the body content or the topic preferences of a topic to set the value of a plugin preference. You can copy one or more of the example assignment statements below to set the desired preference value.

   * Set BEAUTIFIERPLUGIN_CSS = %ATTACHURL%/style.css
   * Set BEAUTIFIERPLUGIN_DEBUG = off
   * Set BEAUTIFIERPLUGIN_LANGUAGE = cpp

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the site administrator who installs the extension on the server.

warning Warning! This plugin and the dp.SyntaxHighlighter plugin conflict and are not compatible as they both implement the %CODE% and %ENDCODE% macros.

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Manual Installation

This plugin may be installed manually by downloading the distribution package attached to the Foswiki:Extensions.BeautifierPlugin topic.
  1. Install/upgrade any packages listed in Dependencies below
  2. Download the .zip or .tgz distribution package and place it in the root directory of your Foswiki installation.
  3. Unpack the distribution package
  4. Using the Foswiki configuration utility, enable the plugin. (If using an accellerator such as mod_perl, it may be necessary to restart your server before your configuration changes will take effect.)
  5. Set any default preference values in Site, Web, and User Preference topics as desired.

Installation Test

#include <nworld.h>

/**
@brief Advance the simulation by one timeslice.
*/
void nWorld::StepSim()
{
        // Iterate simulation loop
        for (node = entityList.GetHead(); node != NULL && j == 53; node = node→GetSucc())
        {
                entity = (nEntity*)node→GetPtr();
                entity→Trigger(this, this→stepSize);
        }
}

Manifest

File: Description:
data/System/BeautifierPlugin.txt Plugin documentation topic
data/System/VarCODE.txt Syntax summary for the CODE macro
data/System/VarENDCODE.txt Syntax summary for the ENDCODE macro
pub/System/BeautifierPlugin/style.css Code fragment stylesheet
pub/System/BeautifierPlugin/style_extension.css Code fragment stylesheet extension
lib/Foswiki/Plugins/BeautifierPlugin.pm Plugin module
lib/Foswiki/Plugins/BeautifierPlugin/LICENSE GNU GPLv2
lib/Foswiki/Plugins/BeautifierPlugin/ANSI.pm  
lib/Foswiki/Plugins/BeautifierPlugin/Context.pm  
lib/Foswiki/Plugins/BeautifierPlugin/Core.pm  
lib/Foswiki/Plugins/BeautifierPlugin/DocBook.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HTML.pm  
lib/Foswiki/Plugins/BeautifierPlugin/Magic.pm  
lib/Foswiki/Plugins/BeautifierPlugin/MagicConfig.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_bash.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_cpp.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_csharp.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_html.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_java.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_javascript.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_lua.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_makefile.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_perl.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_php3.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_plsql.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_python.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_scheme.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_tcl.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_verilog.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_vhdl.pm  
lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_xml.pm  

Plugin Info

Author: TWiki:Main.LingLo, Foswiki:Main.WillNorris, & Foswiki:Main.BryanThale
Copyright: © 2010, Foswiki Contributors
License: GPL (GNU General Public License, Version 2)
Release: 1.0
Version: 7136 (2010-04-09)
Home: Foswiki:Extensions.BeautifierPlugin
Support: Foswiki:Support.BeautifierPlugin
Dependencies:
NameVersionDescription
CGI>=0Required, CPAN:CGI
Change History:  
09 Apr 2010 (1.0): Foswikitask:Item8844 - Port to Foswiki
20 May 2007: added JavaScript language file, removed legacy CODE_lang construct
30 Apr 2007: warnings cleanup; no functional changes
27 Apr 2007: automatically adds CSS for formatting code fragments
01 Jan 2006 (Dakar): upgraded to TWiki::Func::extractNameValuePair for better parameter parsing, upgraded TWiki:Plugins.BuildContrib support
26 Jul 2003: Syntax fixes from TWiki:Main/WillNorris
10 Feb 2003 (Beijing): Syntax fix from TWiki:Main/JoshMore
28 Dec 2002: Accepts mixed case language names
20 Dec 2002: Changed syntax to allow for simpler addition of new languages
16 Oct 2002: Added nebula nodes and links to Python scripts, but it doesn't work since the node names are usually in strings
30 Jul 2002: Added nebula nodes and links to TCL scripts
30 Jul 2002: Changed Beautifier::Core to use 'linkscripts'
28 Jul 2002 (Athens): Created

Related Topics: dp.SyntaxHighlighter
Topic attachments
I Attachment Action Size Date Who Comment
style.csscss style.css manage 182 bytes 28 Apr 2007 - 13:01 ProjectContributor CSS to format code fragments
style_extension.csscss style_extension.css manage 99 bytes 28 Apr 2007 - 13:01 ProjectContributor Example of an extension to the base CSS for code fragments
Topic revision: r1 - 09 Apr 2010, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback