pkg://jultaf-0.0.4-1.i386.rpm:140767/
usr/
info/jultaf.info
info downloads
This is Info file jultaf.info, produced by Makeinfo version 1.67 from
the input file jultaf.texi.
INFO-DIR-SECTION Tcl and Friends
START-INFO-DIR-ENTRY
* Jultaf: (jultaf). The Jumble Library for Tcl and Friends.
END-INFO-DIR-ENTRY
File: jultaf.info, Node: Top, Up: (dir)
Jumble Library for Tcl and Friends
**********************************
The *Jumble Library for Tcl and Friends* is a collection of Tcl and
[incr Tcl] scripts and provides procedures resp. classes with various
purposes. Additionally a shared library for accessing GDBM databases
from Tcl can be build with this package.
This document corresponds to version 0.0.4 of the library. Up-to-date
information about Jultaf can be found via
http://www.han.de/~racke/jultaf/.
* Menu:
* Introduction:: Important information about this package
* Error:: Error Handling
* Command Line Processing::
* New Control Structures::
* String:: String manipulation functions
* Lists:: How to manipulate lists
* Array:: Array manipulation functions
* Files:: File manipulation functions
* Code Processing:: Evaluating Tcl code
* Invoking subprocesses:: Shell interaction
* GNU dbm:: Accessing GDBM Databases
* RPM Interface::
* Miscellaneous:: Functions not fitting elsewhere
* Packages:: Index of Jultafs Packages
* Variable Index::
* Function Index::
* Concept Index::
File: jultaf.info, Node: Introduction, Next: Error, Up: Top
Important information about this package
****************************************
Jultaf is *alpha* software. It is not tested by anyone but me and
documentation is not as good as required for a decent package. However,
it works for me.
Jultaf is *free* software. This means that everyone may use it,
redistribute it and/or modify it under the terms of the GNU General
Public License, as published by the Free Software Foundation.
* Menu:
* Conventions:: How to Read This Manual
* Build Configuration::
File: jultaf.info, Node: Conventions, Next: Build Configuration, Up: Introduction
How to Read This Manual
=======================
Items introduced in one of the last revisions are marked as new in
this manual as shown in the example below:
`fresh' *NEW*
Returns a list with new functions in this release.
Jultaf is a work in progress and several items will be a moving
target. Their syntax may change in a not backward compatible way and
are marked as "unstable" :
`hacks' *EXPERIMENTAL*
Returns a list with bug-prone functions in this release.
File: jultaf.info, Node: Build Configuration, Prev: Conventions, Up: Introduction
Build Configuration
===================
* Menu:
* Optional Features:: `--enable-' and `--with-' options
* Installation Directories::
File: jultaf.info, Node: Optional Features, Next: Installation Directories, Up: Build Configuration
Optional Features
-----------------
`--enable-itcl'= `yes'|`no'|PATH
Indicates if the [incr Tcl] library files should be installed as
well as the vanilla Tcl library files. If set to `yes' or the PATH
to the [incr Tcl] interpreter, this files will be installed. The
default value depends on the fact if `configure' detects `itclsh'
in the path.
`--with-gdbm'
Enables compiling and installing of the Jufgdbm library.
`--with-prof'
Enables compiling and installing of the Jufprof library.
`--with-pq'
Enables compiling and installing of the Jufpq library.
`--with-rpm'
Enables compiling and installing of the Jufrpm library.
File: jultaf.info, Node: Installation Directories, Prev: Optional Features, Up: Build Configuration
Installation Directories
------------------------
This section describes where the various files of the Jultaf
distribution get installed by `make install'.
Symbolic Name Default value Files
`DATADIR' /usr/local/share/jultaf Tcl and [incr Tcl] files
`LIBDIR' /usr/local/lib library files (Jufprof and Jufgdbm)
`INFODIR' /usr/local/info documentation (GNU Info format)
`DOCDIR' /usr/local/doc/jultaf documentation (HTML format)
File: jultaf.info, Node: Error, Next: Command Line Processing, Prev: Introduction, Up: Top
Error
*****
The functions provided by the `Error' package can be divided into error
handling functions and error evaluation functions.
`fault' TYPE [ARG ...]
Generates an Tcl error. The message is composed of an template
specified by TYPE and the remaining arguments:
`badoption'
`bad option "%s": must be %s'
`wrongargs'
`wrong # args: should be "%s"'
The following error handling functions concatenates the given
arguments together with the `: ' separator string between them. The
scriptname is prepended if running non-interactively.
`fatal' [ARGS...]
Prints an error message on `stderr' and exits the current process.
`error' [ARGS...]
Print an error message on `stderr'.
`warning' [ARGS...]
Print an error message on `stderr' with the text "warning"
preprended.
Only one error evaluation function exists by now:
`tclmsg'
Evaluates the Tcl variable `errorCode' and generates an
appropriate error message.
This is useful for reporting errors on file operations:
package require Error
if {[catch "open [lindex $argv 0]" fileid] != 0} {
Juf::Error::fatal [lindex $argv 0] [Juf::Error::tclmsg]
}
File: jultaf.info, Node: Command Line Processing, Next: New Control Structures, Prev: Error, Up: Top
Command Line Processing
***********************
* Menu:
* Option Specifications:: How to specify and describe an option
* Option Listing::
* Option Processing::
* Examples::
File: jultaf.info, Node: Option Specifications, Next: Option Listing, Up: Command Line Processing
Option Specifications
=====================
The `juf_getopts' (*note Option Processing::.) function and the
`juf_getopts_listspecs' (*note Option Listing::.) function expect a
list of "option specifications" as one of their arguments.
Each option specification consists of an option processing
description, an option description and an argument description. Only
the processing description is mandatory. The other two elements of a
option specification are optional and evaluated only by the
`juf_getopts_listspecs' function.
* Menu:
* Option Processing Description::
File: jultaf.info, Node: Option Processing Description, Up: Option Specifications
Option Processing Description
-----------------------------
Each option can be specified through usage of different names, e.g.
`-h' and `--help' . The processing description starts with these names,
concatenated by the `|' -sign.
File: jultaf.info, Node: Option Listing, Next: Option Processing, Prev: Option Specifications, Up: Command Line Processing
Option Listing
==============
An option listing can be produced with the `juf_getopts_listspecs'
function:
`juf_getopts_listspecs' OPTSPECS OUTID
Writes a option listing to the file bound to the file identifier
OUTID. Expects as OPTSPECS a list of option specifications (*note
Option Specifications::.).
File: jultaf.info, Node: Option Processing, Next: Examples, Prev: Option Listing, Up: Command Line Processing
Option Processing
=================
`juf_getopts' OPTSPECS OPTARR NEWARGV OLDARGV
Processes the command line arguments in OLDARGV. Any options
(preceded with `-' or `--' ) are evaluated according to the option
specifications (*note Option Specifications::.) OPTSPECS. This
function stores the remaining arguments in the array OPTARR.
File: jultaf.info, Node: Examples, Prev: Option Processing, Up: Command Line Processing
Examples
========
I recommend the following set of option specifications as base set
(make sure to replace `make' with the actual script name):
{{help|h {Print this message and exit.}}
{version|v {Print the version number of make and exit}}}
File: jultaf.info, Node: New Control Structures, Next: String, Prev: Command Line Processing, Up: Top
New Control Structures
**********************
"Control structures" are commands that direct the flow of control
like the Tcl builtins `if', `while' and `switch'.
`juf_branch' VALUE [PATTERN SCRIPT] ... 2
Creates and evaluates `switch' statement. Causes error if VALUE
matches with none of the PATTERN arguments. To override this
behaviour you may add `default {}' to the arguments.
Example for this command:
% proc version {subcmd number} {
set parts [split $number .]
juf_branch $subcmd major {lindex $parts 0} minor {lindex $parts 1} \
minuscule {lindex $parts 2}
}
% version minor 1.2.3
2
% version patch 1.2.3
bad option "patch": must be major, minor, or minuscule
File: jultaf.info, Node: String, Next: Lists, Prev: New Control Structures, Up: Top
String
******
The functions provided by the `String' package perform several
operations on array variables:
`juf_split' [OPTIONS] STRING [EXP LIMIT]
Returns a list created by splitting STRING at each match of the
regular expression EXP. If EXP is omitted or an empty string is
given, it defaults to whitespace. If LIMIT is given, it stops the
matching process, so that the size of the resulting list is equal
or lesser than LIMIT.
A regular expression matching the null string will split STRING
into separate characters at each point it matches that way:
% juf_split "hello world" " *"
h e l l o w o r l d
If the initial arguments to `juf_split' start with `-', they are
treated as options. The following options are supported:
`-showempty'
Adds an empty element to the list for each match of the
regular expression:
% juf_split -showempty {blarab}
{} {} bla {} arg {} rab {}
`--'
Marks the end of the options. The argument following this one
will be treated as STRING even if it starts with a `-'.
`juf_compose' STRING NUMBER
Composes a string of NUMBER times of STRING.
`juf_strcasecmp' STRING1 STRING2
Performs a case insensitive string comparison. Returns -1, 0, or 1,
depending on whether STRING1 is considered less than, equal to, or
greater than STRING2 .
`juf_string_count' STRING [ARRNAME]
Returns the number of different characters in STRING. If ARRNAME
is given, an array ARRNAME will be created with characters as keys
and character counts as values.
% juf_string_count example count
6
% array get count
l 1 p 1 x 1 m 1 a 1 e 2
File: jultaf.info, Node: Lists, Next: Array, Prev: String, Up: Top
Lists
*****
Jultaf provides two packages working on lists, `Sequence' for all
lists and `LOL' for lists inside of lists.
* Menu:
* Sequence:: Generic list operations
* LOLList of Lists:: Operations on nested lists
File: jultaf.info, Node: Sequence, Next: LOLList of Lists, Up: Lists
Sequence
========
The functions provided by the `Sequence' package perform several
operations on lists:
`Juf::Sequence::shift' NAME [COUNT]
Removes COUNT element from the list stored in the variable NAME
and returns the last element removed. COUNT defaults to 1.
`Juf::Sequence::pop' NAME [COUNT]
Removes COUNT element from the end of the list stored in the
variable NAME and returns the last element removed. COUNT defaults
to 1.
`Juf::Sequence::append' [OPTION ...] NAME [VALUE ...]
Works like the Tcl builtin `lappend', but considers these options:
`-nonempty'
Append only non-empty values.
`--'
Marks the end of the options. The argument following this one
will be treated as NAME even if it starts with a `-'.
`Juf::Sequence::assign' LIST [NAME ...]
Sets value of the variables specified by the NAME arguments to
that of the existing elements of LIST. Returns remaining list
elements. If the number of variables exceeds the list length, the
remaining variables will be removed.
File: jultaf.info, Node: LOLList of Lists, Prev: Sequence, Up: Lists
List of Lists
=============
Each hierarchy level is a list with keys as odd elements and
inferior lists as even elements. The empty string is a special key. The
accompanying element is list of values instead of a inferior list.
`insert' *NEW* *EXPERIMENTAL* NAME LIST VALUE
Inserts VALUE into list of lists stored within variable NAME as
specified by the keys LIST.
% package require LOL
% set grplist ""
% Juf::LOL::insert grplist "Development Languages Tcl" Jultaf
Development {Languages {Tcl {{} Jultaf}}}
File: jultaf.info, Node: Array, Next: Files, Prev: Lists, Up: Top
Array
*****
The functions provided by the `Array' package perform several
operations on array variables:
`values' [SWITCH ...] [NAME ...]
Returns a list containing the values of all of the elements in the
array(s) specified by the NAME arguments. If invoked with the
`-unique' switch, a specific value appears only once in the list.
% array set test {whiskey drink beer drink fish food}
% Juf::Array::values test
drink food drink
% Juf::Array::values -unique test
drink food
`sort' NAME
Returns list of element names of array NAME, sorted according to
the element values.
% array set test {whiskey drink beer drink fish food}
% Juf::Array::sort test
whiskey beer fish
File: jultaf.info, Node: Files, Next: Code Processing, Prev: Array, Up: Top
Files
*****
`juf_file_slurp' FILE NAME
Reads complete FILE into variable NAME. Returns 1 in case of
success, 0 otherwise.
`juf_file_mkdirs' [DIR ...]
Creates all directories given as arguments. Any missing parent
directories are created too. Considers an existing argument
directory not as an error.
`juf_file_iscwd' FILENAME
Checks if FILENAME corresponds to the current working directory.
Returns 1 if successful, 0 otherwise.
* Menu:
* File Names:: Dealing with file names
* find:: Finding Files
File: jultaf.info, Node: File Names, Next: find, Up: Files
File Name Manipulation
======================
`juf_file_expand' NAME [DIR] *NEW* *EXPERIMENTAL*
Converts file name NAME to the corresponding absolute filename,
performs tilde substitution and returns the result. Please note
that `..' and `.' will not expanded (yet). If NAME is a relative
name, the function assumes that DIR is the directory where the
file corresponding to NAME resides in. In the case that no value
for DIR is passed, the current working directory is used.
File: jultaf.info, Node: find, Prev: File Names, Up: Files
Finding Files
=============
This section describes the procedure `find', which searches for
files matching certain criteria. `find' is available only if Jultaf has
been configured with `--enable-itcl (*note Optional Features::.)'.
`find' expects as arguments any number of "directory trees" and
options with or without values. The procedure searches all files in the
given directory trees and returns all files that matches the criteria
specified by the options. A "directory tree" is a directory and the
files it contains, all of its subdirectories and the files they
contain, etc. It can also be a single non-directory file.
Valid options are:
`-name' PATTERN
Qualifies files that match PATTERN in a `string match'-like
fashion. Only the last component of the file name is considered
for the match.
`-type' CHAR
Qualifies files that are of type CHAR:
`b'
block (buffered) special
`c'
character (buffered) special
`d'
directory
`f'
regular file
`l'
symbolic link
`p'
pipe (FIFO)
`s'
socket
File: jultaf.info, Node: Code Processing, Next: Invoking subprocesses, Prev: Files, Up: Top
Code Processing
***************
`juf_safe_eval' [OPTIONS] SCRIPT
Evaluates SCRIPT as Tcl script in a temporary safe interpreter and
returns the result.
Valid options are:
`-aliases NAME'
Creates an alias for each key in array NAME within the safe
interpreter.
`-exit COMMAND'
exit handlerCOMMAND will be called with the interpreter as
argument after processing SCRIPT.
`-interp NAME'
Stores interpreter into variable NAME. Useful with the
`-unknown' option.
`-nosafe'
Use an ordinary slave interpreter.
`-renames NAME'
Renames commands stored as keys in array NAME to the
corresponding values within the safe interpreter.
`-stats NAME'
Fills array NAME with statistics:
cmdcount
number of commands executed within the safe interpreter.
`-unknown NAME'
Function NAME will be called if the safe interpreter stumbles
over an unknown command.
`-variables NAME'
Creates a variable for each key in array NAME within the safe
interpreter. The initial value of the variable is the
corresponding array element.
`--'
Marks the end of the options. The argument following this one
will be treated as NAME even if it starts with a `-'.
`juf_safe_source' [OPTIONS] FILE [NAME]
Evaluate FILE as Tcl script in a temporary safe interpreter.
Accepts the same options as `juf_safe_eval'.
File: jultaf.info, Node: Invoking subprocesses, Next: GNU dbm, Prev: Code Processing, Up: Top
Invoking subprocesses
*********************
The `shell' module consists only of one function:
`juf_shell_run' ARGS
Passes its arguments to `exec' and returns 1 if successful, 0
otherwise.
File: jultaf.info, Node: GNU dbm, Next: RPM Interface, Prev: Invoking subprocesses, Up: Top
Accessing GDBM Databases
************************
GNU dbm databases can be manipulated with the `juf_gdbm' command.
Note that this command is available only if Jultaf is configured with
the -with-gdbm (*note Optional Features::.) option.
`juf_gdbm open' NAME FLAGS
Opens database file NAME and returns database identifier. The
access mode is specified by FLAGS:
`r'
Database is opened for reading. Any call to `juf_gdbm' with
the options `delete' or `store' will fail.
`rw'
Database is opened for reading and writing.
`rwc'
Same as `rw', if the database does not exist, a new one will
be created.
`rwn'
Same as `rw', a new database will be created in any case.
`juf_gdbm close' DBID
Closes database specified by DBID.
`juf_gdbm store' DBID KEY VALUE
Stores KEY with the associated VALUE in database specified by DBID.
`juf_gdbm insert' DBID KEY VALUE
Inserts KEY with the associated VALUE in database specified by
DBID. Generates an error if KEY exists already.
`juf_gdbm fetch' DBID KEY
Returns associated value for KEY in database specified by DBID. If
KEY doesn't exist, a empty string is returned.
`juf_gdbm delete' DBID KEY
Removes KEY from database specified by DBID.
`juf_gdbm exists' DBID KEY
Returns 1, if KEY exists in database specified by DBID, 0
otherwise.
`juf_gdbm list' DBID
Returns a list containing all keys in database specified by DBID.
File: jultaf.info, Node: RPM Interface, Next: Miscellaneous, Prev: GNU dbm, Up: Top
RPM Interface
*************
`query' PACKAGE TAG
Queries PACKAGE for the value of TAG. If a file PACKAGE doesn't
exist, the RPM database will be searched for PACKAGE. Supported
tags are:
`name'
name of package
`group'
slash separated list of group names
Queries looks like:
% package require RPM
% Juf::RPM::query rpm name
rpm
% Juf::RPM::query file group
Utilities/File
File: jultaf.info, Node: Miscellaneous, Next: Packages, Prev: RPM Interface, Up: Top
Miscellaneous Functions
***********************
`Juf::deprecate' OLD NEW
Deprecates function OLD in favor of function NEW. Maps OLD to NEW
and prints error message at the first call of OLD.
% package require Jufbase
% 0.0.4
Juf::deprecate juf_compose Juf::String::compose
% juf_compose foo 5
juf_compose: deprecated function
foofoofoofoofoo
`juf_misc_scriptname'
Returns name of the current script with leading directories and
extension(s) removed.
`juf_misc_shell' [PROMPT]
Displays the prompt given in PROMPT which defaults to "% " and
evaluates the user input in the current interpreter until the user
types `exit' or the demanded command invokes the `exit' command.
This command is very useful for testing libraries and/or Tcl
applications. The following script can be adapted to your needs:
#!/usr/bin/tclsh
lappend auto_path "/usr/share/jultaf"
juf_misc_shell "jultaflib% "
File: jultaf.info, Node: Packages, Next: Variable Index, Prev: Miscellaneous, Up: Top
Package Index
*************
* Menu:
* Array: Array.
* Error: Error.
* LOL: LOLList of Lists.
* Sequence: Sequence.
* String: String.
File: jultaf.info, Node: Variable Index, Next: Function Index, Prev: Packages, Up: Top
Variable Index
**************
* Menu:
* badoption: Error.
* errorCode: Error.
* wrongargs: Error.
File: jultaf.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Top
Function Index
**************
* Menu:
* append: Sequence.
* assign: Sequence.
* deprecate: Miscellaneous.
* error: Error.
* exec: Invoking subprocesses.
* fatal: Error.
* fault: Error.
* find: find.
* insert: LOLList of Lists.
* juf_branch: New Control Structures.
* juf_compose: String.
* juf_file_iscwd: Files.
* juf_file_mkdirs: Files.
* juf_file_slurp: Files.
* juf_gdbmclose: GNU dbm.
* juf_gdbmdelete: GNU dbm.
* juf_gdbmexists: GNU dbm.
* juf_gdbmfetch: GNU dbm.
* juf_gdbminsert: GNU dbm.
* juf_gdbmlist: GNU dbm.
* juf_gdbmopen: GNU dbm.
* juf_gdbmstore: GNU dbm.
* juf_getopts: Option Processing.
* juf_getopts_listspecs: Option Listing.
* juf_misc_scriptname: Miscellaneous.
* juf_misc_shell: Miscellaneous.
* juf_safe_eval: Code Processing.
* juf_safe_source: Code Processing.
* juf_shell_run: Invoking subprocesses.
* juf_split: String.
* juf_strcasecmp: String.
* juf_string_count: String.
* lappend: Sequence.
* pop: Sequence.
* query: RPM Interface.
* shift: Sequence.
* sort: Array.
* switch: New Control Structures.
* tclmsg: Error.
* values: Array.
* values-unique: Array.
* warning: Error.
File: jultaf.info, Node: Concept Index, Prev: Function Index, Up: Top
Concept Index
*************
* Menu:
* -aliases: Code Processing.
* -exit: Code Processing.
* -interp: Code Processing.
* -nonempty: Sequence.
* -nosafe: Code Processing.
* -renames: Code Processing.
* -showempty: String.
* -stats: Code Processing.
* -unknown: Code Processing.
* -variables: Code Processing.
* absolutefile names: File Names.
* alias: Code Processing.
* appending list elements: Sequence.
* arrayslist of values: Array.
* arrayssortingby value: Array.
* cmdcount: Code Processing.
* control structures: New Control Structures.
* current working directory: Files.
* databasesGDBM: GNU dbm.
* DATADIR: Installation Directories.
* directoriescreating: Files.
* directory tree: find.
* DOCDIR: Installation Directories.
* documentationGNU Info files: Installation Directories.
* documentationHTML: Installation Directories.
* exit handler: Code Processing.
* expanding file names: File Names.
* featuresnew: Conventions.
* featuresoptional: Optional Features.
* featuresunstable: Conventions.
* FIFO: find.
* file names: File Names.
* file namesabsolute: File Names.
* file namesexpanding: File Names.
* filesreading: Files.
* filessearching: find.
* GDBM: GNU dbm.
* GNU Info: Installation Directories.
* GNUdbm: GNU dbm.
* HTML: Installation Directories.
* HTML documentation: Installation Directories.
* Info: Installation Directories.
* INFODIR: Installation Directories.
* interpretersafe: Code Processing.
* interpretertemporary: Code Processing.
* LIBDIR: Installation Directories.
* linksymbolic: find.
* list of lists: LOLList of Lists.
* listsappending elements: Sequence.
* listsremoving elementsJuf::Sequence::pop: Sequence.
* listsremoving elementsJuf::Sequence::shift: Sequence.
* named pipe: find.
* new items: Conventions.
* null string: String.
* option specificationsbase set: Examples.
* pipenamed: find.
* removing list elementsJuf::Sequence::pop: Sequence.
* removing list elementsJuf::Sequence::shift: Sequence.
* safe interpreter: Code Processing.
* script name: Miscellaneous.
* scriptsevaluating: Code Processing.
* searching files: find.
* shell module: Invoking subprocesses.
* socket: find.
* sourceTcl scripts: Code Processing.
* stringscomparingcase insensitive: String.
* substitutiontilde: File Names.
* symbolic link: find.
* temporary interpreter: Code Processing.
* testinglibraries: Miscellaneous.
* testingTcl applications: Miscellaneous.
* tilde substitution: File Names.
* unstable items: Conventions.
* |: Option Processing Description.
Tag Table:
Node: Top233
Node: Introduction1486
Node: Conventions2074
Node: Build Configuration2649
Node: Optional Features2880
Node: Installation Directories3660
Node: Error4232
Node: Command Line Processing5537
Node: Option Specifications5822
Node: Option Processing Description6505
Node: Option Listing6828
Node: Option Processing7283
Node: Examples7756
Node: New Control Structures8109
Node: String8978
Node: Lists10844
Node: Sequence11147
Node: LOLList of Lists12304
Node: Array12945
Node: Files13800
Node: File Names14429
Node: find15001
Node: Code Processing16197
Node: Invoking subprocesses17834
Node: GNU dbm18139
Node: RPM Interface19748
Node: Miscellaneous20313
Node: Packages21426
Node: Variable Index21813
Node: Function Index22092
Node: Concept Index24432
End Tag Table
