Writing A Script-Fu Script

This section will document the constants, argument types, and functions that can be used when creating or modifying a Script-Fu script.

Named constants

Useful values from libgimpbase/gimplimits.h:

  • MIN-IMAGE-SIZE
  • MAX-IMAGE-SIZE
  • MIN-RESOLUTION
  • MAX-RESOLUTION

Useful misc constants:

  • TRUE
  • FALSE

Builtin units:

  • UNIT-PIXEL
  • UNIT-INCH
  • UNIT-MM
  • UNIT-POINT
  • UNIT-PICA

For SF-ADJUSTMENT:

  • SF-SLIDER
  • SF-SPINNER

Additional constants:

  • SF-RUN-MODE
  • DIR-SEPARATOR

Using named constants in a list in a register block

Register block arguments

The list of argument types that can be used in a register block of a Script-Fu script are:
SF-ADJUSTMENT, SF_BRUSH, SF-CHANNEL, SF_COLOR, SF_DIRNAME, SF-DISPLAY, SF-DRAWABLE, SF_ENUM, SF_FILENAME, SF_FONT, SF_GRADIENT, SF-IMAGE, SF-LAYER, SF_OPTION, SF_PALETTE, SF_PATTERN, SF-STRING, SF-TEXT, SF-TOGGLE, SF-VALUE, SF-VECTORS

Click on any of the arguments listed above to see details of that argument type.

Internally defined functions

  • gimp-directory
  • gimp-data-directory
  • gimp-plug-in-directory
  • gimp-locale-directory
  • gimp-sysconf-directory
  • script-fu-register
  • script-fu-menu-register
  • script-fu-quit

Internal function:

  • gimp-proc-db-call

The following functions have been marked as deprecated and should not be used in new scripts:

  • gimp-dir
  • gimp-data-dir
  • gimp-plugin-dir

The ftx extension

The ftx extension is based on version 1.1 of the TinyScheme Extension (TSX) created by Manuel Heras. The reason for calling it ftx (as in File and Time eXtensions) instead of TSX is due to it providing only the file and time related functions provied by the original extension. The 'getenv', 'system', and various additional functions which supported use of sockets were left out of ftx.

Scheme already defines functions to read and write files. The additional functions allow access to the filesystem permitting a script to check if a certain file exists, to get its size, etc.

In addition to these functions, a string constant DIR-SEPARATOR has been defined. It should be used in scripts which build file names that include one or more directories to keep the scripts portable to different operating systems.

(file-exists? filename)

filename: string

This function returns #t if the indicated file exists, and #f if it does not exist or if it is not accessible to the requesting user. Accessibility is based on the real user and group ID rather than the effective user ID and group ID.

(file-type filename)

filename: string

This function returns a value based on the file type. It returns FILE_TYPE_FILE (1) for regular files, FILE_TYPE_DIR (2) for directories, and FILE_TYPE_LINK (3) for symbolic links. The value FILE_TYPE_OTHER (0) is returned if the file is of some other type, does not exist, or if the user does not have sufficient priveleges to allow the file type to be determined.

(file-size filename)

filename: string

This function returns the size (in bytes) of the indicated file, or #f if the file does not exists or is not accessible to the requesting user.

(file-delete filename)

filename: string

Removes the specified file. It returns #t if the operation succeeds, or #f otherwise (e.g., because the file is read-only, or because the file does not exist).

(dir-open-stream path)

path: string

Opens a “directory stream” on the provided directory path. This stream will provide all the files within the directory, using the function read-dir-entry. The stream should be closed at the end with dir-close-stream.

(dir-read-entry dirstream)

dirstream: directory stream, obtained with dir-open-stream.

It returns the name of the following directory entry, or eof if all the entries were provided. Check the return value with with eof-object?.

(dir-rewind dirstream)

dirstream: directory stream, obtained with dir-open-stream.

Resets the given directory stream. The next call to dir-read-entry will return the first entry again. It returns #t if the operation succeeds, or #f otherwise (ie. dirstream not valid)..

(dir-close-stream dirstream)

dirstream: directory stream, obtained with dir-open-stream.

Close directory stream. No further calls to read-dir-entry should performed.

(time)

Returns the current local time, as a list of integer containing:

  (year month day-of-month hour min sec milliseconds)

The year is expressed as an offset from 1900.

(gettimeofday)

Returns a list containing the number of seconds from the beginning of the day, and microseconds within the current second.

(usleep microseconds)

microseconds: integer

The re extension

The 're' extension adds the ability to do regexp style pattern matching in Scheme scripts.

For now, it the use of this extension adds the single function (re-match <pattern> <string>). It returns true (#t) if the string matches the pattern or false (#f) if the string does not match the pattern. If the function is called with an extra parameter 1), which should be a vector, it overwrites as many elements of the vector as needed with the strings that matched the corresponding parenthesized subexpressions inside <pattern>.

Here is an example of it in use:

(re-match ".*word.*" "Does this string contain 'word'?")

SIOD compatability routines

The Script-Fu plug-in of GIMP prior to version 2.4 used SIOD as its Scheme interpreter. SIOD provided many functions that could be used in scripts which are not available in an R5RS standards compliant interpreter, or which are in direct conflict with an R5RS defined function.

To allow scripts which use functions unique to SIOD to run in the TinyScheme based Script-Fu a SIOD compatability library was created. This library of routines can be found in the script-fu-compat.init file. The routines in that file are some of the more common SIOD based functions used by scripts written before the release of the 2.4 version of GIMP. The compatability routines are added on an as needed basis dependant on ease of implementation. Some SIOD functions are easy to implement in a standards compliant Scheme interpreter and are more likely to be added. Other functions may be harder, or even not possible, to implement solely in Scheme and will be less likely to be added.

Random number related routines:

  • (srand seed)
  • (msrg-rand)
  • (random n)

The following item is a macro which defines a while loop (needed by some older scripts):

  • (while test . body)

The following functions require the ftx extension to be loaded:

  • (realtime) [This calls gettimeofday]

The following items may be useful enough to keep around:

  • (delq item lis)
  • (make-list count fill)
  • (strbreakup str sep)
  • (substring-equal? str str2 start end)
  • (string-trim str)
  • (string-trim-left str)
  • (string-trim-right str)
  • (unbreakupstr stringlist sep)

The following functions are deprecated and should not be used in new scripts:

  • aset
  • aref
  • butlast
  • cons-array
  • fmod
  • fopen
  • fread
  • fread-get-chars
  • last
  • mapcar
  • nil
  • nreverse
  • nth
  • *pi*
  • pow
  • prin1
  • print
  • prog1
  • rand
  • strcat
  • strcmp
  • string-lessp
  • symbol-bound?
  • the-environment
  • trunc
  • verbose

Script-Fu coding style

References with useful information regarding coding style:

1) 1 NOTE: I have not tested the behaviour of this function when it is called with an extra parameter.
software/sf/writing.txt · Last modified: 2012/09/21 14:08 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Valid XHTML 1.1 Valid CSS! Best viewed with any browser Ohloh profile for Kevin Cozens Driven by DokuWiki Recent changes RSS feed