Allows the creation and maintenance of key-value pairs commonly used in the creation of application configuration files.

Synopsis

gnocl::keyFile subcommand

Description

The command gnocl::keyFile provides the ability to create, edit and parse lists of key-value pairs. The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments.

#--------------- 
# sample_config.ini 
#--------------- 
# this is just an example
# there can be comments before the first group

[Batch]
base="/"
path=""

[Crop]
top=0
bottom=100
center=50
sides=100

[Scan]
type=tif
resolution=400
threshold=128
mode=binary 
format=tiff
x=210
y=297
l=0
t=0
i=0
prefix="img-"
last=0

[Page]
width=2480 
height=3508

Lines beginning with a '#' and blank lines are considered comments.

Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group.

Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form key[locale]=value, with a locale identifier of the form lang_COUNTRYMODIFIER where COUNTRY and MODIFIER are optional. Space before and after the '=' character are ignored. Newline, tab, carriage return and backslash characters in value are escaped as \n, \t, \r, and \\, respectively. To preserve leading spaces in values, these can also be escaped as \s.

Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically ';' or ','. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash.

This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences:

Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged together. Another difference is that keys and group names in key files are not restricted to

Commands

id class
id clear
id delete

id free

id get  <subcommand>  [-option value...]

Obtain specific values from named keys. If no command and options are specified, then the command will return a string containing the contents of the key-value list.

id has [-option value...]

id new

Create an instance of an new keyFile object. This list will remain in memory and the filename <script-name>.ini assigned by default where <script-name> is the name of the active script. This name can be changed during any subsequent write operation.

id remove

 Clear specific group and keys from the key-value list.

id set

Create new groups and keys within a key-value list and assign values.

id write string (default: "")

Write the contents of the key-value list back to disk to the file named string. If no filename is specified then the command will attempt to save the contents of the key-value list to a file named <appName>.ini where appName is the name of the application or script from which the command has been made.

Example

The following example shows a simple way of using keyfiles to load, save and edit application preferences.

#---------------
# test-keyfile.tcl
#---------------
# William J Giddings, 19/05/2012
#---------------

#!/bin/sh
#\
exec tclsh "$0" "$@"

package require Gnocl

#---------------
# manipulate application preferences
#---------------
# preferences stored in global two-dimensional array name "prefs"
# array names are equivalent to the group/key pairings required for keyFile
#---------------
# args
#    cmd        one of load, edit, save
#    keyfile    name of keyfile to load/save, ignored for edit
# returns
#   none
#---------------
proc preferences {cmd {keyFile {} } } {

 global prefs

 switch $cmd {

    load {

        set kf [gnocl::keyFile load $keyFile]
        set prefs(comment) [$kf get comment]
       
        foreach group [$kf get groups] {
            foreach key [$kf get keys -group $group] {
                # assign each value
                set prefs($group,$key) [$kf get value -group $group -key $key]
                }
            }
        }

    edit {
       
        # make a copy of the prefs, might need undoing
        global _prefs
        foreach item [array names prefs] { set _prefs($item) $prefs($item) }

        # dialog response proc
        proc _responseProc {v} {
            global prefs _prefs
            switch $v {
                No {
                    foreach item [array names _prefs] { set prefs($item) $_prefs($item) }
                }
            }
            array unset _prefs
        } ;# _responseProc
       
        # preferences edit gui
        set box [gnocl::box -orientation vertical]
        set notebook [gnocl::notebook]
        set lgroup ""
        foreach item [lsort [array names prefs]] {
            if {$item == "comment"} { continue }
            foreach {group key} [split $item ,] {
                if { $group != $lgroup } {
                    set table($group) [gnocl::table -homogeneous 0]
                    $notebook addPage $table($group) $group
                }
                $table($group) addRow \
                    [list [gnocl::label -text $key -align right -maxWidthChars 10 -widthGroup 1] \
                          [gnocl::entry -variable prefs($group,$key) -data $prefs($group,$key)] ] \
                    -fill 1 -expand {0 0}
                set lgroup $group
            }
        }
        gnocl::dialog \
            -child $notebook \
            -buttons "{{%_C_ancel} %#No} {{%_O_kay} %#Yes}" \
            -onResponse "_responseProc %v"
        }

    save {
        set kf [gnocl::keyFile new]
        $kf set comment -value $prefs(comment)
        foreach item [array names prefs] {
            foreach {group key} [split $item ,] {
                $kf set string -group $group -key $key -value $prefs($item)
            }
        }
        $kf write $keyFile
        $kf free
        }
 } ;# end switch
   
}

# package demonstration
if {1} {
    # create as sample .ini file
    set fp [open "sample_config.ini" w]
    puts $fp {
#---------------
# sample_config.ini
#---------------
# this is just an example
# there can be comments before the first group

[Batch]
base=/
path=

[Crop]
top=0
bottom=100
center=50
sides=100

[Scan]
type=tif
resolution=400
threshold=128
mode=binary
format=tiff
x=210
y=297
l=0
t=0
i=0
prefix=img-
last=0

[Page]
width=2480
height=3508
}

    close $fp

    preferences load sample_config.ini
    preferences edit

    parray prefs

    set prefs(comment) "---------------\n\tmy new tmp.ini\n---------------"
    preferences save tmp.ini
}