2021-04-30 13:51:04 -04:00
|
|
|
/* GIMP - The GNU Image Manipulation Program
|
|
|
|
|
* Copyright (C) 1995 Spencer Kimball and Peter Mattis
|
|
|
|
|
*
|
|
|
|
|
* This program is free software: you can redistribute it and/or modify
|
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
|
* the Free Software Foundation; either version 3 of the License, or
|
|
|
|
|
* (at your option) any later version.
|
|
|
|
|
*
|
|
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
|
* GNU General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
|
* along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#ifndef __SCHEME_MARSHAL_H__
|
|
|
|
|
#define __SCHEME_MARSHAL_H__
|
|
|
|
|
|
2023-12-11 15:54:22 -05:00
|
|
|
pointer marshal_ID_to_item (scheme *sc,
|
2021-04-30 13:51:04 -04:00
|
|
|
pointer a,
|
|
|
|
|
gint id,
|
|
|
|
|
GValue *value);
|
|
|
|
|
|
2023-12-11 15:54:22 -05:00
|
|
|
pointer marshal_vector_to_item_array (scheme *sc,
|
2021-04-30 13:51:04 -04:00
|
|
|
pointer a,
|
plug-ins: new named argument syntax in Script-Fu.
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.
2025-01-19 22:21:54 +01:00
|
|
|
GValue *value,
|
|
|
|
|
gchar **strvalue);
|
2021-04-30 13:51:04 -04:00
|
|
|
|
|
|
|
|
void marshal_path_string_to_gfile (scheme *sc,
|
|
|
|
|
pointer a,
|
|
|
|
|
GValue *value);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
pointer marshal_returned_object_array_to_vector (scheme *sc,
|
|
|
|
|
GValue *value);
|
|
|
|
|
|
2024-03-04 10:42:40 -05:00
|
|
|
gchar* marshal_returned_gfile_to_string (GValue *value);
|
|
|
|
|
|
|
|
|
|
GeglColor* marshal_component_list_to_color (scheme *sc,
|
plug-ins: new named argument syntax in Script-Fu.
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.
2025-01-19 22:21:54 +01:00
|
|
|
pointer list,
|
|
|
|
|
gchar **strvalue);
|
2024-03-04 10:42:40 -05:00
|
|
|
pointer marshal_color_to_component_list (scheme *sc,
|
|
|
|
|
GeglColor *color);
|
2021-04-30 13:51:04 -04:00
|
|
|
|
2024-03-06 14:48:41 -05:00
|
|
|
pointer marshal_color_array_to_vector (scheme *sc,
|
|
|
|
|
GimpColorArray array);
|
|
|
|
|
|
2021-04-30 13:51:04 -04:00
|
|
|
#endif /* __SCHEME_MARSHAL_H__ */
|