Eskil

Eskil provides a plugin system where a plugin can preprocess data
before being compared and displayed.

The command line options for plugins are:
  -plugin plugin     : Use plugin
  -plugininfo info   : Pass info to plugin (plugin specific)
  -plugindump plugin : Dump plugin source to stdout
  -pluginlist        : List known plugins
  -pluginallow       : Allow full access for a plugin.
A plugin may further define command line options that it accepts.

A plugin is a Tcl script that must follow a specific format.
Dump one of the included plugins to see what it looks like.
The plugin is executed in a safe interpreter and thus cannot do any
damage. You can turn this safety off with -pluginallow.

A plugin is set up with these global variables filled in:

<title>Changes</title>

Upcoming changes (not yet released):

  *  New [./table.wiki | table] view, activated by -table, when comparing tables.
  *  Mercurial support for Directory Diff, Commit, Revert and Log.
  *  Plugins can define command line options they accept.
  *  Plugins can read ::argv to know the given command line.
  *  New plugin for binary files
  *  New plugin for CSV files
  *  Added option -sep, to set a separator that makes input be interpreted
     in a table like manner.
  *  New plugin for PDF files
  *  Added option -pluginallow to run plugins in a standard interpreter instead
     of a safe one. Thus a plugin could use e.g. exec.
  *  Allow plugins to yield if Eskil is run in Tcl 8.6 or newer.

<h1>Usage</h1>

The command line options for plugins are:
  *  -plugin plugin     : Use plugin
  *  -plugininfo info   : Pass info to plugin (plugin specific)
  *  -plugindump plugin : Dump plugin source to stdout
  *  -pluginlist        : List known plugins
  *  -pluginallow       : Allow full access for a plugin.

A plugin may further define command line options that it accepts.

<h1>General Format</h1>

A plugin is a Tcl script file that must start with the verbatim sequence
"##Eskil Plugin :". A plugin is sourced and used in its own safe
interpreter and thus have free access to its own global space. Hookup
points are defined by declaring specifically named procedures as specified

A plugin is set up with these global variables filled in:
  *  ::WhoAmI : The name of the plugin
  *  ::Info   : The contents of -plugininfo parameter
  *  ::Pref   : A copy if Eskil's internal preferences array.
  *  ::argv   : A copy of the command line from Eskil's invocation

<h2>Additional options</h2>
A plugin can declare command line options that should be accepted by Eskil.
They will be passed on to the plugin through the ::argv list.
If the initial "##Eskil" line is followed by comments formatted as below,
it adds options. Any empty line will end parsing for such lines.

A line like "## Option -<option>" declares an option that takes a value and
a line lile "## Flag -<option>" declares an option without value. The rest of
the line after the option name is ignored and can be used for comments.

<h1>File plugin</h1>

To process the files being compared, the following procedure should be
defined in the plugin file:

<pre>proc PreProcess {side chi cho} {...}</pre>

The FileCompare procedure can give the following return values:

  *  0 : Files are not equal
  *  1 : Files are equal
  *  2 : Files are equal as far as the channels have been read.
         Let the normal comparison finish the job.

##Eskil Plugin : Compare binary files, in hex
## Option -binsep : A set of chars to be used as "newline"

# Example file for a plugin.
# A plugin must start exactly like this one.
# The text after : is the summary you can get at the command line

# A plugin may declare command line options that should be allowed through
# to ::argv

# This plugin converts files to hex to be able to compare binary files.
# A set of chars can be defined to be used as "newline". Default "0 10 13".
# Example usage:
# eskil -plugin binary -binsep "0 10 13 32" f1 f2

# A plugin must define this procedure to do the job.
# side: left or right
# chi:  An input channel for reading the original file.
# cho:  An output channel for writing the processed file.
proc PreProcess {side chi cho} {


    set delimitL [list 0 10 13]

    if {[llength $::Info] > 0} {
        set delimitL $::Info
    }
    set i [lsearch -exact $::argv -binsep]
    if {$i >= 0} {
        incr i
        set delimitL [lindex $::argv $i]
    }
    if {[catch {llength $delimitL}]} {
        puts $cho "Binary plugin needs parameter to be a list"
        return 1
    }

    # Build an RE that matches the given chars
    set REm "\["
    set REi "\[^"
    foreach code $delimitL {
        set c [format %c $code]

    set opts(-csvignore) ""
    set opts(-csvkey) ""
    set opts(-csvheader) 0
    foreach opt {-sep -csvignore -csvkey} {
        set i [lsearch -exact $::argv $opt]
        if {$i >= 0} {
            incr i

            set opts($opt) [lindex $::argv $i]
        }
    }
    set opts(-sep) [subst -nocommands -novariables $opts(-sep)]
    set i [lsearch -exact $::argv "-csvheader"]
    if {$i >= 0} {
        set opts(-csvheader) 1
    }

##Eskil Plugin : Compare after filtering lines
## Option -grepre : Regexp to filter on

# Example file for a plugin.
# A plugin must start exactly like this one.
# The text after : is the summary you can get at the command line

# A plugin may declare command line options that should be allowed through
# to ::argv

# This plugin only compares lines that match a pattern.
# Example usage:
# eskil -plugin grep -grepre "<t>" f1 f2

# A plugin must define this procedure to do the job.
# side: left or right
# chi:  An input channel for reading the original file.
# cho:  An output channel for writing the processed file.
proc PreProcess {side chi cho} {
    if {[catch {llength $::Info}]} {
        puts $cho "Grep plugin needs -plugininfo parameter to be a list"
        return 1
    }
    # Look for parameters in info string
    set opts(-re) "."
    foreach {opt val} $::Info {
        set opts($opt) $val
    }
    # And on command line
    set i [lsearch -exact $::argv -grepre]
    if {$i >= 0} {
        incr i
        set opts(-re) [lindex $::argv $i]
    }
    while {[gets $chi line] >= 0} {
        if {[regexp -- $opts(-re) $line]} {
            puts $cho $line
        }
    }
    # Signal that the file after processing should be used both
    # for comparison and for displaying.
    return 1
}