Jumble Library for Tcl and Friends

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/ .

• Important information about this package
  • How to Read This Manual
  • Build Configuration
• Error
• Command Line Processing
  • Option Specifications
  • Option Listing
  • Option Processing
  • Examples
• New Control Structures
• String
• Lists
  • Sequence
  • LOLList of Lists
• Array
• Files
  • File Name Manipulation
  • Finding Files
• Code Processing
• Invoking subprocesses
• Accessing GDBM Databases
• RPM Interface
• Miscellaneous Functions
• Package Index
• Variable Index
• Function Index
• Concept Index

Important information about this package

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.

How to Read This Manual

fresh

Returns a list with new functions in this release.

hacks

Returns a list with bug-prone functions in this release.

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.

Installation Directories

Error

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"

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.

package require Error
if {[catch "open [lindex $argv 0]" fileid] != 0} {
	Juf::Error::fatal [lindex $argv 0] [Juf::Error::tclmsg]
}

Command Line Processing

Option Specifications

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.

Option Processing Description

Option Listing

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.

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 OPTSPECS. This function stores the remaining arguments in the array OPTARR.

Examples

{{help|h {Print this message and exit.}} 
 {version|v {Print the version number of make and exit}}}

New Control Structures

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.

% 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

String

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 {bla&r;rab&{\;} 
{} {} 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

Lists

Sequence

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.

List of Lists

insert 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}}}

Array

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

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.

File Name Manipulation

juf_file_expand NAME [DIR]

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.

Finding Files

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

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 handler COMMAND 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.

Invoking subprocesses

juf_shell_run args

Passes its arguments to exec and returns 1 if successful, 0 otherwise.

Accessing GDBM Databases

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.

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

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% "

Package Index

• Array
• Error
• LOL
• Sequence
• String

Variable Index

• badoption
• errorCode
• wrongargs

Function Index

• append
• assign
• deprecate
• error
• exec
• fatal
• fault
• find
• insert
• juf_branch
• juf_compose
• juf_file_expand
• juf_file_iscwd
• juf_file_mkdirs
• juf_file_slurp
• juf_gdbm
  • close
  • delete
  • exists
  • fetch
  • insert
  • list
  • open
  • store
• juf_getopts
• juf_getopts_listspecs
• juf_misc_scriptname
• juf_misc_shell
• juf_safe_eval
• juf_safe_source
• juf_shell_run
• juf_split
• juf_strcasecmp
• juf_string_count
• lappend
• pop
• query
• shift
• sort
• switch
• tclmsg
• values
  • -unique
• warning

Concept Index

• --enable-itcl
• --with-gdbm
• --with-pq
• --with-prof
• --with-rpm
• -aliases
• -exit
• -interp
• -nonempty
• -nosafe
• -renames
• -showempty
• -stats
• -unknown
• -variables
• absolute
  • file names
• alias
• appending list elements
• arrays
  • list of values
  • sorting
    • by value
• cmdcount
• control structures
• current working directory
• databases
  • GDBM
• DATADIR
• directories
  • creating
• directory tree
• DOCDIR
• documentation
  • GNU Info files
  • HTML
• exit handler
• expanding file names
• features
  • new
  • optional
  • unstable
• FIFO
• file names
  • absolute
  • expanding
• files
  • reading
  • searching
• GDBM
• GNU
  • dbm
• GNU Info
• HTML
• HTML documentation
• Info
• INFODIR
• interpreter
  • safe
  • temporary
• LIBDIR
• link
  • symbolic
• list of lists
• lists
  • appending elements
  • removing elements
    • Juf::Sequence::pop
    • Juf::Sequence::shift
• named pipe
• new items
• null string
• option specifications
  • base set
• pipe
  • named
• removing list elements
  • Juf::Sequence::pop
  • Juf::Sequence::shift
• safe interpreter
• script name
• scripts
  • evaluating
• searching files
• shell module
• socket
• source
  • Tcl scripts
• strings
  • comparing
    • case insensitive
• substitution
  • tilde
• symbolic link
• temporary interpreter
• testing
  • libraries
  • Tcl applications
• tilde substitution
• unstable items
• |