PIKApp/devel-docs/PIKA3-plug-in-porting-guide/porting_scriptfu_scripts.md

## About this document

This describes *some* changes needed to port a Scriptfu script to PIKA 3:
- changes in types
- changes in PDB signatures for multi-layer support
- changes in error messages
- changes in logging

It does *not* document:
- PDB procedures whose names have changed (see pdb-calls.md)
- PDB procedures that have been removed (see removed_functions.md)
- PDB procedures that have been added
- other changes in signature where arguments are reordered or changed in number

## Changes in types of PDB signatures

Calls from a script to PIKA are calls to PDB procedures.
PDB procedures are documented in terms of C and GLib types.

This table summarizes the changes:

| Purpose        | Old C type            | New C type            | Old Scheme type | New Scheme type       |
| ---------------|-----------------------|-----------------------| ----------------|-----------------------|
| Pass file name | gchar*, gchar*        | GFile                 | string string   | string                |
| Recv file name | gchar*                | GFile                 | string          | string                |
| pass drawable  | PikaDrawable          | gint, PikaObjectArray | int   (an ID)   | int (a length) vector |
| Pass obj array | gint, PikaInt32Array  | gint, PikaObjectArray | int  vector     | int vector            |
| Recv obj array | gint, PikaInt32Array  | gint, PikaObjectArray | int  vector     | int vector            |
| Pass set of str | gint, PikaStringArray | GStrv                 | int  list       | list                  |
| Recv set of str | gint, PikaStringArray | GStrv                 | int  list       | list                  |

(Where "obj" means an object of a PIKA type such as PikaDrawable or similar.)

### Use one string for a filename instead of two.

Formerly a PDB procedure taking a filename (usually a full path) required two strings (two gchar* .)
Now such PDB procedures require a GFile.

In Scheme, where formerly you passed two strings, now pass one string.

Formerly a script passed the second string for a URI, to specify a remote file.
Formerly, in most cases you passed an empty second string.
Now, the single string in a script can be either a local file path or a remote URI.

Example:

(pika-file-load RUN-NONINTERACTIVE "/tmp/foo" "")
=> (pika-file-load RUN-NONINTERACTIVE "/tmp/foo")


### PDB procedures still return a string for a filename

All PDB procedures returning a filename return a single string to Scheme scripts.
That is unchanged.

Formerly a PDB signature for a procedure returning a filename
specifies a returned type gchar*, but now specifies a returned type GFile.
But a Scheme script continues to receive a string.

The returned string is either a local file path or a URI.


### Use a vector of drawables for PDB procedures that now take an array of drawables

Formerly, some PDB procedures took a single PikaDrawable,
but now they take an array of PikaDrawable ( type PikaObjectArray.)
(Formerly, no PDB procedure took an array of drawables.
Some that formerly took a single drawable still take a single drawable.
See the list below. )

For such PDB procedures, in Scheme pass a numeric length and a vector of numeric drawable ID's.

These changes support a user selecting multiple layers for an operation.

Example:

(pika-edit-copy drawable)  => (pika-edit-copy 1 (vector drawable))

(pika-edit-copy 2)  => (pika-edit-copy 1 '#(2))

### The PDB procedures which formerly took single Drawable and now take PikaObjectArray

- Many of the file load/save procedures.
- pika-color-picker
- pika-edit-copy
- pika-edit-cut
- pika-edit-named-copy
- pika-edit-named-cut
- pika-file-save
- pika-image-pick-color
- pika-selection-float
- pika-xcf-save


### Receiving an array of drawables

Formerly a PDB procedure returning an array of drawables (or other PIKA objects)
had a signature specifying a returned gint and PikaInt32Array.
Now the signature specifies a returned gint and PikaObjectArray.
A script receives an int and a vector.
The elements of the vector are numeric ID's,
but are opaque to scripts
(a script can pass them around, but should not for example use arithmetic on them.)

No changes are needed to a script.


Example:

(pika-image-get-layers image)

Will return a list whose first element is a length,
and whose second element is a vector of drawables (Scheme numerics for drawable ID's)

In the ScriptFu console,

(pika-image-get-layers (car (pika-image-new 10 30 1)))

would print:

(0 #())

Meaning a list length of zero, and an empty vector.
(Since a new image has no layers.)

### Passing or receiving a set of strings

Formerly, you passed an integer count of strings, and a list of strings.
Now you only pass the list.
ScriptFu converts to/from the C type GStrv
(which is an object knowing its own length.)
An example is the PDB procedure file-gih-save.

Formerly, you received an integer count of strings, and a list of strings.
Now you only receive the list
(and subsequently get its length using "(length list)").
Examples are the many PDB procedures whose name ends in "-list".
Remember that the result of a call to the PDB is a list of values,
in this case the result is a list containing a list,
and for example you get the list of strings like "(car (pika-fonts-get-list ".*"))"

## Changes in error messages

ScriptFu is now more forgiving.

Formerly, ScriptFu would not accept a call construct where the argument count was wrong,
except for the case when you provided one argument to a PDB procedure
that took zero arguments (sometimes called a nullary function.)

Now, when a script has the wrong count of arguments to a PDB procedure:

- too many actual arguments: ScriptFu will give a warning to the console
  and call the PDB procedure with a prefix of the actual arguments.
  This is now true no matter how many arguments the PDB procedure takes.
  Extra arguments in the script are ignored by Scriptfu,
  not evaluated and not passed to the PDB.

- too few actual arguments: ScriptFu will give a warning to the console
  and call the PDB procedure with the given actual arguments.
  The warning will say the expected Scheme formal type of the first missing actual argument.
  Usually the PDB procedure will fail and return its own error message.

When you suspect errors in a script,
it is now important to run PIKA from a console to see warnings.


## ScriptFu logging

ScriptFu now does some logging using GLib logging.
When you define in the environment "G_MESSAGES_DEBUG=scriptfu"
ScriptFu will print many messages to the console.

This is mostly useful for PIKA developers.