179 lines
6.6 KiB
Plaintext
179 lines
6.6 KiB
Plaintext
# 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..."
|
