IdEst – ID3 Editing and Scripting Tool (split by node):   Section:   Chapter:FastBack: Structure   Up: Top   FastForward: Backups   Contents: Table of ContentsIndex: Concept Index

10 Scripting

Idest offers a scripting facility, which makes it possible to extend its functionality beyond the basic operations, described in previous chapters. Scripts must be written in Scheme, using ‘Guile’, the GNU’s Ubiquitous Intelligent Language for Extensions. For information about the language, refer to Revised(5) Report on the Algorithmic Language Scheme. For a detailed description of Guile and its features, see Overview in The Guile Reference Manual.

The scripting mode is enabled when the option --script (-S) is given in the command line. This option stops further option processing, so any other idest command line options must be given before it. The argument to this option specifies the name of the script file:

$ idest --script list.scm *.mp3

You can omit the ‘.scm’ suffix, as idest will try it automatically (see below).

When this option is given, the following operations are performed:

  1. The program looks for files .idest.scm, $HOME/.idest.scm and guile-site-dir/idest/idest.scm in that order. Here, ‘$HOME’ stands for the user home directory and guile-site-dir stands for the Guile site-wide directory, as described in guile-site-dir. If any of these files is found, it is loaded as a Scheme source code and further search is discontinued. This allows you to configure Guile settings on per-directory, per-user and site-wide basis.

    This step is omitted if the program is given the --no-init-files (-N) option.

    When a startup file is loaded, the list of files which were to be tried after it is passed to it as arguments. This allows for chain-loading all files in the list using the following code:

    (let load-loop ((name-list (cdr (command-line))))
      (if (not (null? name-list))
          (let ((name (car name-list)))
    	(load-loop (cdr name-list))
    	(if (file-exists? name)
    	    (primitive-load name)))))
  2. Unless the supplied script name contains directory separators (‘/’), it is searched in the Guile’s %load-path. The default load path is formed as follows:

    where the components are as follows:


    The standard Guile load path (see Build Config in The Guile Reference Manual).


    This directory is selected at compile time using the rules below. Its value is returned by the (%idest-guile-site-dir) primitive:

    1. Determine actual value of the default Guile site directory, by inspecting the value returned by the ‘%site-dir’ primitive.
    2. If that value lies under the current installation prefix, use it.
    3. Otherwise, if the --with-guile-site-dir option is supplied:
      1. If it is used without arguments, use the ‘%site-dir’ value.
      2. Otherwise, the value of this option is taken as new site directory.
    4. Otherwise, a warning is issued and $(datadir)/guile/site is used as the site directory.

    The reason for using this directory is described in

    If guile-site-dir coincides with the standard %site-dir, this part is omitted, because the latter is always present in the %load-path.


    This is the directory for installing version-independent idest files. It is formed as follows:


    This value is returned by the (%idest-package-site-dir) primitive.


    This is the directory for installing version-dependent idest files. It is formed as follows:


    This value is returned by the (%idest-version-site-dir) primitive.

    The load path can be modified using the --load-path (-P) and --prepend-load-path (-p) command line options. Both options take as argument a list of directory names, separated by colons. The --load-path option adds these directories to the tail of the load path list. The --prepend-load-path option adds them to the head of the load path list.

    The script is loaded via primitive-load-path (see primitive-load-path in The Guile Reference Manual), so idest will consult the %load-extensions list and try suffixes from that list as described in %load-extensions in The Guile Reference Manual).

  3. The script is read and evaluated.

    The script can access command line arguments via the usual command-line function (see command-line in The Guile Reference Manual). It can also modify the argument list (e.g. by removing its command line options). It must not, however, modify ‘argv[0]’. Any changes it does to the argument list become visible to idest. The only requirement is that the modified argument list consist of the script name (as argv[0]) and input file names.

  4. The script’s main function is applied to each input file in turn.

The main function must be declared as:

Function: idest-main file frames

It takes two arguments. The file argument supplies the name of the file being processed. The frames argument is a list of ID3 frames read from that file. Each element of frames is a pair, with the frame name in its car and an association list of frame properties in its cdr.

The properties are identified by property names, which are Scheme symbols. The following property names are defined:


Value of this frame, as a string.


Frame description. It is a string, verbosely describing the frame. For example, the description of ‘TRCK’ frames is ‘Track number/position in set’.

These are the same descriptions that are output with the --describe option (see describe).


Unsupported or partially-supported frames contain only this property. Its value is a list of frame fields. Each field is represented by a triplet ‘(ord type value)’, where ord is the ordinal number of that field in frame, type is its type (integer) and value is its value. If type is one of numeric types, value is the numeric value converted to string (as per number->string). If type is a string type, value contains the string in the appropriate encoding. Otherwise, value holds the field value as a binary string. Each byte in such a string is represented by two hexadecimal digits. For example, ‘AB\n’ is represented as ‘41420A’.

More properties are defined at a per-frame basis to represent frame qualifiers. They are named after corresponding qualifiers as listed in --list-frames output (see describe). For example, for ‘comment’ (‘COMM’) frames:


A three-letter code of the language in which the text is written.


Content descriptor.

The mode in which input files are open is controlled by the idest-readonly variable:

Variable: idest-readonly

This is a boolean variable that indicates whether idest-main can modify tag frames. If its value is #t, the function return value will be ignored, and input files will be opened in read-only mode. This is the default.

If idest-readonly is ‘#f’ the idest-main function should return the new list of frames. If it returns an empty list, all existing frames will be deleted. If the function chooses not to modify any frames, it must return #f.

The two following sections show how to write script files. The sample scripts they discuss can be found in subdirectory examples of the idest distribution.

IdEst – ID3 Editing and Scripting Tool (split by node):   Section:   Chapter:FastBack: Structure   Up: Top   FastForward: Backups   Contents: Table of ContentsIndex: Concept Index