Documentation‎ > ‎Commands‎ > ‎

gnocl::keyFile

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

Synopsis

gnocl::keyFile subcommand

Options

new

Whether or not the status icon blinks.
load  string (default: "")
Load the contents of the named keyfile denoted by string. If this value is not supplies, the command will attempt to load a file names <appName>.ini where appName is the name of the application or script from which the command was made..

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:

  • .ini files use the ';' character to begin comments, key files use the '#' character.

  • Key files do not allow for ungrouped keys meaning only comments can precede the first group.

  • Key files are always encoded in UTF-8.

  • Key and Group names are case-sensitive, for example a group called [GROUP] is a different group from [group].

  • .ini files don't have a strongly typed boolean entry type, they only have GetProfileInt. In GKeyFile only true and false (in lower case) are allowed.

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

Returns the class of the widget, i.e. keyfile

id clear

Clear all groups and keys,.i.e. removes all contents.

id delete

Delete the current keyFile command and free up memory.

id free

Synonym for the delete subcommand given above.
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.

Sub-Command

The range of sub-commands provided is to reflect compatibility with the GLib library function. However,  all values passed to the calling Tcl script are strings with the most practical method to obtain information being the use of the 'value' sub-command. Returns string containing the value specified by the -group and -key options.

double string (default: "")

<description to be added>

integer string (default: "")

The main notification message presented in emboldened capitals.

boolean string (default: "")

<description to be added>

string string (default: "")

<description to be added>

value string (default: "")

<description to be added>

comment string (default: "")

<description to be added>

groups string (default: "")

<description to be added>

keys string (default: "")

<description to be added>

startgroup string (default: "")

<description to be added>.

Options

In order to determine which from which key a value is to be retrieved from, the script will need to specify both group and key.

NB: The -locale and -list options have yet to be fully implemented.

-group string (default: "")

Name of group which contains the required key.

-key string (default: "")

Name of key from which contains the required value..

-locale string (default: "")

<description to be added>

-list string (default: "")

<description to be added>
id has [-option value...]

Determine whether the specified group and member keys are present within the specified key-value list. Returns 1 if the group and/or key is exists within the key-value list.

Options

-group string (default: "")

Name of group the existence of which is being queried.

-key string (default: "")

Name of key the existence of which is being queried. For this to be effective, a group name must be specified.
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.

Sub-Command

group string (default: "")

Name of the group to be removed.

Options


-key string (default: "")

If this option is specified, only the named key within the specified group will be removed.

comment string (default: "")

Remove the comment associated with the specified group.

Options

-key string (default: "")

Remove the comment associated with the named key within the specified group.
id set
Create new groups and keys within a key-value list and assign values.

Sub-Command

double string (default: "")

<description to be added>

integer string (default: "")

<description to be added>

boolean string (default: "")

<description to be added>

string string (default: "")

<description to be added>

value string (default: "")

<description to be added>

comment string (default: "")

<description to be added>

separator string (default: "")

<description to be added>

Options

-group string (default: "")

Name of the group into which the key value is to be added. If the group does not already exist, then one will be added to the key-value list.with the name specified by string.

-key string (default: "")

Name of key to which value is to be set, If the key does not exist, then one will be added to the key-value list with the name specified by string.

-locale string (default: "")

<description to be added>

-list string (default: "")
<description to be added>

-value string (default: "")

The value to be assigned to the specified key.

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
}




Comments