f92f7d425c
This syntax is now the official syntax for non-core PDB procedures.
I.e. that while core procedures will still use ordered arguments (e.g.:
`(gimp-image-get-layers 1)`), plug-in PDB procedures called from
Script-Fu will have named arguments in any order.
Say for instance that you want to call python-fu-foggify from Script-Fu.
Whereas we used to run:
> (python-fu-foggify RUN-NONINTERACTIVE 1 (car (gimp-image-get-layers 1)) "Clouds" '(50 4 4) 1.0 50.0)
Now we should call:
> (python-fu-foggify #:image 1 #:drawables (car (gimp-image-get-layers 1)) #:opacity 50.0 #:color '(50 4 4))
Now we can note:
* Every argument is preceded by a #:label which is the argument name.
This makes these calls much more readable (some plug-in procedures can
have dozen of arguments and these end up as list of integers, floats
and strings, which are hard to read and hard to debug) and semantic.
* Order doesn't matter anymore. For instance here, I put #:opacity
before #:color.
* As a direct consequence, we can drop any argument which we wish to
keep with default value. E.g. in the old style, we had to put the
#:run-mode, #:name ("Clouds") and #:turbulence (1.0) because we were
changing the last argument #:opacity (50.0). Now we can drop all 3
default arguments.
Having non-ordered argument is in fact the starter of this feature,
because it is already the case for calling PDB procedures in the libgimp
API (and therefore in all GIR bindings). By saying that the order of PDB
procedures is not part of the API, we actually allow to add arguments
and even to reorder them in the future without breaking existing scripts
in the 3.0 series.
This became even more serious when I was considering to make the generic
metadata arguments public. Since they are appended to the end, after all
plug-in-specific arguments, if I do this, adding any argument in an
export plug-in would break order. It won't matter anymore!
Note that it doesn't matter for core PDB procedures (where this syntax
is not used) because these are also C functions and therefore order and
number of arguments matter anyway. Also these don't have dozens of
arguments.
As a helper for Script-Fu developer, in particular as we already
released 2 RCs and therefore some people already started to port their
scripts, the old syntax will still work yet will produce a warning
showing how to call the same thing with the new syntax. For instance,
with the above first call, the warning will be:
> (script-fu:2059912): scriptfu-WARNING **: 22:54:47.507: Calling Plug-In PDB procedures with arguments as an ordered list is deprecated.
> Please use named arguments: (python-fu-foggify #:run-mode 1 #:image 1 #:drawables (2) #:name "Clouds" #:color '(50 4 4) #:turbulence 1.000000 #:opacity 50.000000)
Note that the argument name syntax is coming from the Racket scheme
variant: https://docs.racket-lang.org/arguments/index.html
Common Lisp has a similar syntax, either with just a colon, or also a
sharp + colon (it's unclear to me the difference, something about
interned vs. uninterned symbols).
After discussion with Liam on IRC, we decided to go with the #: syntax
of Racket.
|
||
|---|---|---|
| .. | ||
| ftx | ||
| tinyscheme | ||
| meson.build | ||
| README | ||
| scheme-marshal-return.c | ||
| scheme-marshal-return.h | ||
| scheme-marshal.c | ||
| scheme-marshal.h | ||
| scheme-wrapper.c | ||
| scheme-wrapper.h | ||
| script-fu-arg.c | ||
| script-fu-arg.h | ||
| script-fu-color.c | ||
| script-fu-color.h | ||
| script-fu-command.c | ||
| script-fu-command.h | ||
| script-fu-compat.c | ||
| script-fu-compat.h | ||
| script-fu-dialog.c | ||
| script-fu-dialog.h | ||
| script-fu-enums.h | ||
| script-fu-errors.c | ||
| script-fu-errors.h | ||
| script-fu-interface.c | ||
| script-fu-interface.h | ||
| script-fu-intl.h | ||
| script-fu-lib.c | ||
| script-fu-lib.h | ||
| script-fu-proc-factory.c | ||
| script-fu-proc-factory.h | ||
| script-fu-progress.c | ||
| script-fu-progress.h | ||
| script-fu-regex.c | ||
| script-fu-regex.h | ||
| script-fu-register.c | ||
| script-fu-register.h | ||
| script-fu-resource.c | ||
| script-fu-resource.h | ||
| script-fu-run-func.c | ||
| script-fu-run-func.h | ||
| script-fu-script.c | ||
| script-fu-script.h | ||
| script-fu-scripts.c | ||
| script-fu-scripts.h | ||
| script-fu-types.h | ||
| script-fu-utils.c | ||
| script-fu-utils.h | ||
| script-fu-version.c | ||
| script-fu-version.h | ||
| script-fu-widgets-custom.c | ||
| script-fu-widgets-custom.h | ||
| script-fu.def | ||
About libscriptfu libscriptfu is part of GIMP. It is not generally useful except by GIMP. The libscriptfu library is used by plugin executables, and the PDB procedures they create, all part of the "ScriptFu" machinery. The libscriptfu library is not intended for third-party developers, only for core GIMP developers. Headers for libscriptfu might not be installed. This directory contains three libraries: libscriptfu, tinyscheme, and ftx. The tinyscheme library contains a TinyScheme interpreter. The ftx library extends the TinyScheme interpreter, adding file functions to the Scheme language. The libscriptfu library contains both the tinyscheme and ftx libraries. The libscriptfu library wraps the TinyScheme interpreter, specializing it for GIMP. The script-fu executable uses the libscriptfu library, to interpret Scheme scripts that GIMP users refer to as "plug-ins." These libraries depend on other libraries, e.g. math, libgimp, glib, etc. Coupling between the executables and the libraries should be in one direction: source for the inner libs should not include headers from the outer executables. This lets you more easily update the inner libraries (which originated elsewhere and might be maintained elsewhere), and change the outer executables (which are subject to change by GIMP developers.) Example (which may change): The script-fu executable is a plugin file that implements PDB procedures: extension-script-fu, script-fu-console, script-fu-text-console, script-fu-eval, and script-fu-server. Each of those PDB procedures runs as a separate process. Each of those processes uses libscriptfu. The main PDB procedure is extension-script-fu, which is a long-lived process. It is a PDB procedure of PDBProcedureType EXTENSION. It interprets the Scheme scripts that user's call "plug-ins." Rarely two of the PDB procedure processes run concurrently. When they do, and libscriptfu is built as a shared library, the read-only, code portion of the library is only loaded in memory once.