4. Detailed features of the library
The λLib has a high percentage of comments on average of 48%. Comments are not only used to give credit to the authors.
At least one line in American describes the main function. In fact, the real international educational development is that at least one executable example is provided followed by a full line comment “;-> ” indicating the expected result.
In addition, some functions may be followed by a block comment about performance analysis.
🟩 Full-line versus block comment
The λLib implements the SRFI-30 nested block comments. Nesting comments allow commenting out already commented source code. 0srfi-030-comment.scm is the fundamental module of the λLib because all the modules are commented on several lines between “#|” and “|#” with the vertical bars aligned.
🟩 Nested comments in Script-Fu for Gimp
For comparison, edit in NotePad++ the original Gimp library made up of the three TinyScheme source codes:
C:\Program Files\GIMP 2\share\gimp\2.0\scripts\script-fu.init
C:\Program Files\GIMP 2\share\gimp\2.0\scripts\script-fu-compat.init
C:\Program Files\GIMP 2\share\gimp\2.0\scripts\script-fu-util.scm
The curious reader will have guessed that the file extension “.init” is equivalent to the file extension “.scm” for the source code in Scheme language.
Not only the comments are rare but they are often reduced to the credits. There is nothing to explain complex notions like macro-expand, compile-hook, quasiquote or dynamic-wind overloading call/cc. Furthermore, there is no executable example or expected result.
🟩 Comment on a full-line in green versus dark blue block comment in Notepad++
Notepad++ menu Settings > Style Configurator > Language: Scheme > Style:
In the column of Notepad++ on the right, is the “Snippets” plugin offering the vertical list of the main functions of the λLib.
-
COMMENTLINEin green for full-line comments after “;” until the end of line -
COMMENTin dark blue for multiline comments forming a block between “# |” and “| #”
Although this thema is outside of the SRFI-30, AlSchemist took advantage of the fact, that SRFI-30 is the first 0-rank module, to implement hexadecimal notation for numeric constants. Because this SRFI-30 is loaded first.
#x3bb ;-> 955
The hexadecimal constant #x3bb is equal to 955 in base 10. Remember that the full-line comment ”;-> ” indicates the expected result in the Script-Fu console.
(number->string #x3bb 16) ;-> 3bb
Conversely, we can convert the number #x3bb in base-16 character string, that is to say into a hexadecimal string.
Hexadecimal constants are used in the Gimp GUI for the color selection dialog in the “HTML” area. To decode an RGB hexadecimal string, you can call stdio: scan-and-set function of 0ts-stdio.scm provided in the Gimp Lambda Library. It is the migration of extracts of the stdio library from the C language to TinyScheme:
#| Convert a RGB string to a list of 3 bytes
(color-RGB->list "500909")
|#;-> (80 9 9)
(define (color-RGB->list strRGB)
(stdio:scan-and-set "%2x%2x%2x" strRGB #f)
)Within the 16-bit Unicode character umbrella, AlSchemist implements the #U+hhhh or #uhhhh character syntax, without the plus separator:
(string #U+03BB #u2654);-> "λ♔"
The syntax of a Latin character in Script-Fu uses the backslash notation prefixed by “#”:
; # backslash latinCharacter
(char->integer #\x);-> 120
🟩 Managing character strings
SRFI-13 is the biggest module with its 2,814 lines of Script-Fu source code: it increases the functions for managing character strings.
Let us take the case of searching in a character string with string-index:
(string-index str criterion maybe-start+end)
(string-index-okmij str a-char)In the SRFI-13 version, `string-index accepts the optional maybe-start+end parameter. If it is not specified, the search is done from the beginning to the end.
; 0123456789012345
(string-index "zero-based index" #\x);-> 15
The search result is 15 because the letter “x” is at index 15 knowing that the “z” of “zero” is at index 0.
(string-index-okmij "zero-based index" #\x);-> 15
returns the same result but slightly faster in 1 ms 312 µs compared to 1 ms 382 µs for string-index . Even if the difference is more or less important, SRFI-13 is more versatile but slower because of the management of its optional parameters.
If the optional parameters are specified, the performance decreases with a duration of 1 ms 491 µs when maybe-start+end is replaced with 0 16.
One of the causes of the slowdown is that SRFI-13 checks the expected type of its parameters. However, this on-the-fly verification makes it possible to locate a wrong parameter more quickly.
🟩 Management of coded character sets
SRFI-14 provides operations on Unicode standard character sets.
The Unicode character sets of the pieces of the chess game or Japanese or Russian, are in nested comments in order to avoid to overload Script-Fu. You can declare them on demand by removing them from the nested comment as shown in the screenshot of the Script-Fu console.
(define char-set:chess
(int-range->char-set #x2654 #x265F)
)
(show char-set:chess (char-set->list char-set:chess))`;-> displays in the Script-Fu console the concatenation of the name of the define followed on the same line of the result of show:
char-set:chess12:(♔ .. ♟)(♔ ♕ ♖ ♗ ♘ ♙ ♚ ♛ ♜ ♝ ♞ ♟)
The 41 first level kanji in Japanese are:
(define char-set:kanji1
(int-range->char-set #x889F #x88C7)
)
(show ": " char-set:kanji1 (char-set->list char-set:kanji1))`;-> displays the following output in the Script-Fu console:
char-set:kanji1: 41:(袟 .. 裇)(袟 袠 袡 袢 袣 袤 袥 袦 袧 袨 袩 袪 被 袬 袭 袮 袯 袰 袱 袲 袳 袴 袵 袶 袷 袸 袹 袺 袻 袼 袽 袾 袿 裀 裁 裂 裃 裄 装 裆 裇)