PIKApp/plug-ins/script-fu/interpreter/README

# About script-fu-interpreter

It is PIKA's Scheme interpreter akin to any other language interpreter,
rather than a PIKA extension as is the plugin extension-script-fu.
This interpreter (like all the ScriptFu plugins) embeds a TinyScheme interpreter.

It is an executable program that is passed the name of a .scm file.
The combination defines one or more PDB procedures of type PLUGIN.

Differences from extension-script-fu
====================================

Since pika-script-fu-interpreter and extension-script-fu use the same
embedded interpreter (they both wrap TinyScheme)
there is no difference in the language interpreted.
Any differences are in the larger behavior of plugins.

### PDB Procedure type

Defines PDB procedure(s) of type PLUGIN.
Unlike for the scriptfu extension,
where a .scm file defines PDB procedure(s) of type TEMPORARY
(owned by the PDB procedure of type PLUGIN named extension-script-fu)

### Protocol

Uses protocol to PIKA like other interpreters e.g. Python
(query, create, and run phases.)
The protocol to PIKA is unlike the protocol to the PIKA extension extension-script-fu.

(Note that "extension" has many meanings.  It can denote: a protocol,
or "suffix of a filename", or "a resource that extends PIKA."
extension-script-fu is "a resource that extends PIKA" and it also uses
the "extension" protocol,
while pika-script-fu-interpreter is a "a resource that extends PIKA" but uses
the "plugin" protocol.)

### Process lifetimes

Executed many times, for many phases,
unlike extension-script-fu which stays executing and gets a remote procedure call
from PIKA to run a PDB procedure.

### Process concurrency

Each invocation of a plugin is in a separate process.
One plugin process crash does not affect others.
Unlike extension-script-fu, where a crash means the PIKA app must be restarted
to restart extension-script-fu.

### GUI concurrency

Each plugin can have its own GUI visible concurrently
with the GUI of other ScriptFu plugins.

For extension-script-fu, an open dialog
prevents other plugins in /scripts (implemented by extension-script-fu)
from opening a dialog.
Instead extension-script-fu opens such dialogs sequentially.

This difference is not very important,
since most users work sequentially.
Most dialogs for plugins do not do anything substantive
until a user closes the dialog with the OK button.

### Calls between scripts

In extension-script-fu, a call to another PDB procedure
implemented by TEMPORARY procedure owned by extension-script-fu
does not leave the process.

In pika-script-fu-interpreter, a call to another PDB procedure
implemented in another plugin file starts another process.

For other plugins, most calls to another PDB procedure starts another process.
The exception is when one plugin file implements many PDB procedures.
One common case is when one plugin file implements its own TEMPORARY PDB procedures that
exist only for the duration of the plugin's lifetime.

Naming
======

script-fu-interpreter is the informal name.

Source is located in /plug-ins/script-fu/interpreter

Filename of the executable is pika-script-fu-interpreter-3.0.
The name is versioned by a number corresponding to the API
and the major version of PIKA (when script-fu-interpreter was introduced).
We expect plugin authors to be insulated from changes to script-fu-interpreter,
for the duration of the PIKA 3 version.


About .scm scripts for script-fu-interpreter
============================================

The contents of a .scm file queried by script-fu-interpreter
are the same as those handled by extension-script-fu
except for the addition of a shebang:

    #!/usr/bin/env pika-script-fu-interpreter-3.0
    (define (script-fu-test img  drawable)
    ...
    (script-fu-register "script-fu-test"
    ...

### Query of scripts

As for other interpreters, a plugin script file must have certain attributes
to be queried by PIKA.  But a queried file may define many PDB procedures.

A .scm file queried by script-fu-interpreter:

- must have permission to execute.
- must be in a directory names the same as the file's base name (less suffix.)

A directory containing an .scm file queried by script-fu-interpreter
is usually a subdirectory of one of the /plug-ins directories,
unlike for extension-script-fu, where the .scm files are in a /scripts dir.

A plugin directory should contain only one queriable .scm file:
only one file can have the same base name as the directory and
PIKA will query that file.

### Defining many PDB procedures per directory

When PIKA queries, script-fu-interpreter will load *ALL* the .scm files
in the same directory (regardless of shebang or execute permission.)
Any of the .scm files can declare and register a PDB procedure.
Any single  .scm file can declare and register many PDB procedures.

Similarly, when PIKA runs a named PDB procedure defined in an .scm file,
script-fu-interpreter will actually load *ALL* the .scm files
in the same directory, but run only the define run function so named.

A plugin directory that contains many .scm files having a shebang
will also work, since only one can be named the same as the parent directory,
and PIKA will only query it,
but find the other .scm files with a shebang.

### Requery of scripts

As with other plugins, PIKA caches plugin definitions between sessions.
PIKA queries plugin files at startup.
PIKA will not requery any plugin files which have not changed since cached.
PIKA will not query a plugin file that is added to the file system
until PIKA is restarted.
(Filters>Development>ScriptFu>Refresh Scripts  will not requery script files
handled by pika-script-fu-interpreter, only those handled by extension-script-fu.)

### Errors during query

Most errors occurring during query appear only in the console.
If you are a plugin author, you should start PIKA in a console
so you can see such errors.

A script may be malformed because it does not define
a "run" function having the same name as the PDB procedure name declared
in the call to script-fu-register().
Formerly, such a malformed script was successfully queried but
the script would throw a "undefined variable" error at run time.
Now, such a malformed script is not queried successfully,
but throws a warning to the console:
"Run function not defined, or does not match PDB procedure name:"



Test scripts
============

Small test scripts for pika-script-fu-interpreter
are located in /plug-ins/script-fu/scripts/test

The script ts-helloworld.scm,
formerly installed in /scripts and handled by extension-script-fu,
is now installed in /plug-ins/ts-helloworld/ts-helloworld.scm
and is now handled by pika-script-fu-interpreter.
It appears as "Filters>Development>Script-Fu>Test>Hello World..."