protbl.sh

protbl - process a table (cvs) file

This library provides the functions to access the data stored in a table file (a csv file with the space or tab as delimiter) in a script. Each row is a data set, and the variables are named like defined in the header line of the table file plus a prefix. One can process each data row, or a selection, with a self defined function or just receive the data of a designated row.

Dependencies

N/A

Usage

protbl_getkeys FILE
Extract the keys from header of table FILE.
protbl_dims FILE
Returns the dimensions of the table FILE.
protbl_check FILE [v(erbose)]
Check consistence of table.
protbl_func FILE FUNC [VPREFIX]
Call a function for each data row in table file and providing the respective values for the variables for each call.
protbl_func_where FILE FUNC KEY VALUE [VPREFIX]
Call a function for each data row in table file where KEY = VALUE and providing the respective values for the variables for each call.
protbl_row FILE #ROW [VPREFIX]
Set the variables according to the data in row #ROW of table FILE.

Variables

protbl_VPREFIX
(default: tbl) Default prefix for input variables. Can be individually reset at each function call.
protbl_HCHECK
(default: 0) Should protbl_func/func_where/row exit (1) or cast only a warning and skip (0) if a data row is not consistent with header line?

Examples

For all examples we refer to the following table file (example.tbl):

# login uid gid password    comment
John    201 105 7ht8qX!+MZi CEO
Marry   202 105 q6pl-c24YTv secretariat
Abby    203 106 ewQp.59#Tzy accounting
Fred    204 106 iTz$P7q9g5p accounting

This have to be a cvs file with spaces or tabs as delimiter between the columns. There must be one header line with a leading hash/number sign, like:

# KEY0 KEY1 KEY2 ...

which defines the KEYs for the respective column.

First we include libinclude.sh, import the protbl library and define functions to be used with example.tbl:

#!/bin/sh
. libinclude.sh
import stpl
TBL_FILE='example.tbl'

MyFunc1 () {
        echo ''
        echo "*** $tbl_login ***"
        echo "uid: $tbl_uid  pwd: $tbl_password"
        echo "gid: $tbl_gid  com: $tbl_comment"
}

MyFunc2 () {
        echo "- $tbl_login has uid: $tbl_uid"
}

In the functions we access to the individual columns of a row by the variables following the syntax $VPREFIX_KEY. Here VPREFIX is by default tbl and can be reset through setting $protbl_VPREFIX or at each function call, and KEY refers to the respective describer in the header line, as explained above.

Now we can process the table file with a function:

protbl_func $TBL_FILE MyFunc1

Here MyFunc1 will be called for each row while the respective values for the variables are provided. This will return:

*** John ***
uid: 201  pwd: 7ht8qX!+MZi
gid: 105  com: CEO

*** Marry ***
uid: 202  pwd: q6pl-c24YTv
gid: 105  com: secretariat

*** Abby ***
uid: 203  pwd: ewQp.59#Tzy
gid: 106  com: accounting

*** Fred ***
uid: 204  pwd: iTz$P7q9g5p
gid: 106  com: accounting

We can also process only a subset of the table:

KEY='gid'
VALUE='106'
echo "Group $key=$value"
protbl_func_where $TBL_FILE MyFunc2 $KEY $VALUE

which will return:

*** Group gid=106 ***
- Abby has uid: 203
- Fred has uid: 204

Note

If the $KEY didn’t exist in $TBL_FILE the script will drop (protbl.sh) ERROR: Key '$KEY' not found in file '$TBL_FILE'! to stderr and terminate with exit code 1.

One can also retrieve, respectively define variables, of a specified row (counting starts with 1!) and access to them locally:

row=2
protbl_row $TBL_FILE $row
echo "In data row $row user $tbl_login with uid=$tbl_uid is listed."

which will return:

In data row 2 user Marry with uid=202 is listed.

Note

If the requested row number $row didn’t exist in $TBL_FILE the script will drop (protbl.sh) ERROR: Requested data rows #$row didn't exists in '$TBL_FILE'! to stderr and terminate with exit code 1.

get the keys

To get a space separated list of the KEYs, we call

protbl_getkeys $TBL_FILE

which will return: login uid gid password comment.

get the dimensions

To become information about the dimensions (#columns,#rows) of the table, we call

protbl_dims $TBL_FILE

In this example it returns: 5,4.

check consistence

To check if a table is consistent, which means that every row contains as much columns as KEYs in the header line, we use protbl_check $TBL_FILE. It returns the number of inconsistent rows, so 0 if everything is fine. With the verbose option

protbl_check $TBL_FILE v

we get:

OK! All 4 rows in table file 'example.tbl' are consistent and contain 5 columns.

or if a row is inconsistent, something like:

ERROR! Row 2 in table file 'example.tbl' contains less/more then 5 columns.

Error Handling

Note

In general: All ERROR or WARNING messages are send to sterr, and after all ERROR messages the script will terminate with exit code 1!

If one refers to a file which did not exist, the library drops something like:

(protbl.sh) ERROR: File ghost.tbl did not exist!

If the cvs file did not contain a proper header line, the library drops:

(protbl.sh) ERROR: Can't find header line!

If protbl_HCHECK=0 and one of the functions meets a row with less or more columns then defined in the header line, the library drops:

(protbl.sh) WARNING: Row #3 in file example.tbl has an inconsistent
number of columns, I skip it!

and skip this row, if protbl_HCHECK=1 it will drop:

(protbl.sh) ERROR: Row #3 in file example.tbl has an inconsistent
number of columns!

and terminate with exit code 1!