Eskil

2016-04-08
 Allow GUI to set privilege for plugins.
 Better search for pdftotext in pdf plugin.

2015-11-22
 Bumped revision to 2.7.1
 Allow plugins to define command line options.

2015-11-20
 Rebuilt command line option handling.

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 privilege 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:
::WhoAmI     : The name of the plugin
::WhoAmIFull : The full path to the plugin source
::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

Example plugins are included in the kit.

A plugin may give a result that has a line-by-line correspondence to
the original, in which case the preprocessed data is used for comparing
while the original is used for displaying.  The main plugin procedure
returns 0 to signify this case.

<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 privilege 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
below, and apart from those, a plugin can define and do whatever within
the limits of a safe interpreter.

In addition to the standard safe interpreter environment, a plugin has
access to stdout as well. By using the command line option -pluginallow,
the plugin is run in a standard interpreter and may e.g. do exec to utilize
external tools.

A plugin is set up with these global variables filled in:
  *  ::WhoAmI     : The name of the plugin
  *  ::WhoAmIFull : The full path to the plugin source
  *  ::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 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 {[info commands exec] eq ""} {
        puts $cho "PDF plugin must be run with privilege to be able\
                   to execute pdftotext"
        return 1
    }
    set cands [auto_execok pdftotext]
    lappend cands [file join $::WhoAmIFull pdftotext]
    lappend cands [file join $::WhoAmIFull .. pdftotext]
    lappend cands [file join $::WhoAmIFull .. .. pdftotext]
    set found 0
    foreach cand $cands {
        if {[file exists $cand]} {
            set found 1
            break
        }
        if {[file exists $cand.exe]} {
            set cand $cand.exe
            set found 1
            break
        }
    }

    if {!$found} {
        puts $cho "PDF plugin needs external tool 'pdftotext' to run"
        return 1
    }
    if {[catch {llength $::Info}]} {
        puts $cho "PDF plugin needs -plugininfo parameter to be a list"
        return 1
    }
    if {[catch {exec $cand {*}$::Info - - <@ $chi >&@ $cho}]} {
        puts $cho "**************************************"
        puts $cho "PDF plugin got an error from pdftotext"
    }

    # Signal that the file after processing should be used both
    # for comparison and for displaying.
    return 1

  -printColorOld <RGB>    : Color for old text (0.7 1.0 0.7)
  -printColorNew <RGB>    : Color for new text (0.8 0.8 1.0)

  -plugin <name>       : Preprocess files using plugin.
  -plugininfo <info>   : Pass info to plugin (plugin specific)
  -pluginlist          : List known plugins
  -plugindump <plugin> : Dump plugin source to stdout
  -pluginallow         : Allow full access privilege for a plugin.

  -limit <lines> : Do not process more than <lines> lines.

To list all options matching a prefix, run 'eskil --query prefix'.
In tcsh use this line to get option completion:
complete eskil 'C/-/`eskil --query -`/'}
}

            # This should not happen since the validator should handle it
            puts "Bad plugin: $plugin"
            printPlugins
            exit
        }
        set opts(plugin) $pinterp
        set opts(pluginname) $plugin
        set opts(pluginallow) $pluginallow
        set opts(plugininfo) $plugininfo
        set opts(pluginpinfo) $pinfo
    }

    # Store the command line given opts
    set ::eskil(defaultopts) [array get opts]

    } else {
        set pi [interp create -safe]
        $pi invokehidden -global source $src
    }

    # Setup info
    $pi eval [list set ::WhoAmI [file rootname [file tail $src]]]
    $pi eval [list set ::WhoAmIFull [file normalize $src]]
    $pi eval [list set ::Info $info]
    interp share {} stdout $pi

    # Expose needed commands
    if {!$allow} {
        interp expose $pi fconfigure ;# ??
        interp hide $pi close

            if {![file readable $file]} continue

            set done($file) 1
            set ch [open $file r]
            set data [read $ch 200]
            if {[regexp {^\#\#Eskil Plugin :(.*?)(\n|$)} $data -> descr]} {
                set root [file rootname [file tail $file]]
                dict set result $root "descr" $descr
                dict set result $root "file" 0
                dict set result $root "dir"  0
                # Load it all for inspection
                append data [read $ch]
                if {[string first "proc PreProcess " $data] >= 0} {
                    dict set result $root "file" 1
                }

    }
    if {![info exists ::eskil($top,pluginname)]} {
        set ::eskil($top,pluginname) ""
    }
    if {![info exists ::eskil($top,plugininfo)]} {
        set ::eskil($top,plugininfo) ""
    }
    if {![info exists ::eskil($top,pluginallow)]} {
        set ::eskil($top,pluginallow) 0
    }
    set ::eskil($top,edit,pluginname) $::eskil($top,pluginname)
    set ::eskil($top,edit,plugininfo) $::eskil($top,plugininfo)
    set ::eskil($top,edit,pluginallow) $::eskil($top,pluginallow)
    set t 0
    foreach {plugin info} $plugins {
        set descr [dict get $info descr]
        if {$dirdiff && ![dict get $info dir]} continue
        ttk::radiobutton $w.rb$t -variable ::eskil($top,edit,pluginname) \
                -value $plugin -text $plugin
        ttk::label $w.l$t -text $descr -anchor "w"
        grid $w.rb$t $w.l$t -sticky we -padx 3 -pady 3
        incr t
    }
    ttk::radiobutton $w.rb$t -variable ::eskil($top,edit,pluginname) \
            -value "" -text "No Plugin"
    grid $w.rb$t -sticky we -padx 3 -pady 3


    ttk::label $w.li -text "Info" -anchor "w"
    addBalloon $w.li "Info passed to plugin. Plugin specific."
    ttk::entry $w.ei -textvariable ::eskil($top,edit,plugininfo)
    grid $w.li $w.ei -sticky we -padx 3 -pady 3

    ttk::checkbutton $w.cb -text "Privilege" \
            -variable ::eskil($top,edit,pluginallow)
    addBalloon $w.cb "Run plugin with raised privileges"
    grid $w.cb - -sticky w -padx 3 -pady 3

    ttk::frame $w.fb -padding 3
    ttk::button $w.fb.b1 -text "Ok"   \
            -command [list EditPrefPluginsOk $top $w]
    ttk::button $w.fb.b2 -text "Show" \
            -command "ShowPlugin $w \$::eskil($top,edit,pluginname)"
    addBalloon $w.fb.b2 "Show plugin source code."
    ttk::button $w.fb.b3 -text "Cancel" -command [list destroy $w]
    set ::widgets($top,prefPluginsOk) $w.fb.b1

    grid $w.fb.b1 x $w.fb.b2 x $w.fb.b3 -sticky we
    grid columnconfigure $w.fb {0 2 4} -uniform a
    grid columnconfigure $w.fb {1 3} -weight 1

    grid $w.fb - -sticky we
    grid columnconfigure $w 1 -weight 1
}

proc EditPrefPluginsOk {top w} {
    destroy $w
    set ::eskil($top,pluginname) $::eskil($top,edit,pluginname)
    set ::eskil($top,plugininfo) $::eskil($top,edit,plugininfo)
    set ::eskil($top,pluginallow) $::eskil($top,edit,pluginallow)
    if {$::eskil($top,pluginname) ne ""} {
        set pinterp [createPluginInterp $::eskil($top,pluginname) \
                             $::eskil($top,plugininfo) \
                             $::eskil($top,pluginallow) pinfo]
    } else {
        set pinterp ""
        set pinfo ""
    }
    set ::eskil($top,plugin) $pinterp
    set ::eskil($top,pluginpinfo) $pinfo
}