Tcl Parse Library Module

The Tcl parse library module has the file name parse.tcl. This module performs string manipulation and word parsing.

Note that most word oriented functions have two levels. The higher level functions operate on space delimited words and the low level functions (whose names begin with ll_ [el el]) operate on a word string delimited by any character.

Here is a list of procedures in the parse library module:

- trim
- word
- ll_word
- wordlen
- ll_wordlen
- indxword
- ll_indxword
- words
- ll_words
- command_words
- command_word
- command_indxword
- command_wordlen
- sub_string
- getyn
- command_worddel
- worddel
- ll_worddel
- ll_wordput
- num
- ucase
- parse_extend
- initstring
- inittstring
- initqstring
- delbytes
- logic_string_to_flag
- flag_2_logic_string
- pmatch
- lpad
- rpad
- strip_space

# Module Dependencies

No other modules are required in order to use this parse module.

# Module Definition Files

This module requires the definition file:

- stdhead.tcl

# Module Procedures

## trim

    Declaration  : proc trim {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : output string

This procedure takes the input string, removes leading, tailing, and intra-word spacing.

This trim procedure is not like most trim procedures in that extraneous spaces are removed from the beginning, end and also between each word in the string.

## word

    Declaration  : proc word {instr outstr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : word number

    Returns      : 1 if extraction was successful, 0 otherwise

This procedure will extract a specific space delimited word from the input string and place it into the output string.

## ll_word

    Declaration  : proc ll_word {instr outstr which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : 1 if extraction was successful, 0 otherwise

This procedure will extract a specific word of the input string delimited by any character and place it into the output string.

## wordlen

    Declaration  : proc wordlen {instr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : word number

    Returns      : word length upon success, -1 otherwise

This procedure will determine the length (in characters) of a specific space delimited word in the input string.

Note that it is valid to have a word of zero characters.

## ll_wordlen

    Declaration  : proc ll_wordlen {instr which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : word length upon success, -1 otherwise

This procedure will determine the length (in characters) of a specific word delimited by a specific character in the input string.

Note that it is valid to have a word of zero characters.

## indxword

    Declaration  : proc indxword {instr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : word number

    Returns      : word position/index upon success, -1 otherwise

This procedure will determine the position/index of a specific space delimited word within the input string.

Note that the returned index is base zero (first position is zero) to conform to Tcl's string indexing.

## ll_indxword

    Declaration  : proc ll_indxword {instr which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : word position/index upon success, -1 otherwise

This procedure will determine the position/index of a specific word delimited by a specific character within the input string.

Note that the returned index is base zero (first position is zero) to conform to Tcl's string indexing.

## words

    Declaration  : proc words {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : number of words upon success, zero otherwise

This function counts the number of space delimited words in the input string.

## ll_words

    Declaration  : proc ll_words {instr delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : number of words upon success, zero otherwise

This procedure counts the number of words delimited by a specific character within the input string.

## command_words

    Declaration  : proc command_words {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : number of command words upon success, zero otherwise

This procedure will count the number of command words within the input string.

## command_word

    Declaration  : proc command_word {instr outstr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : command word number

    Returns      : 1 if the extraction was successful, 0 otherwise

This procedure will extract a specific command word from the input string.

## command_indxword

    Declaration  : proc command_indxword {instr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : command word number

    Returns      : position/index of the command word upon success, -1 otherwise

This procedure will determine the position or index of a specific command word within the input string.

Note that the returned index is base zero (first position is zero) to conform to Tcl's string indexing.

## command_wordlen

    Declaration  : proc command_wordlen {instr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : which
          Type   : positive integer
    Description  : command word number

    Returns      : the length upon success, -1 otherwise

This procedure determines the length of a specific command word within the input string.

Note that it is valid to have a command word of zero characters.

## sub_string

    Declaration  : proc sub_string {instr sub}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : sub
          Type   : string
    Description  : sub-string

    Returns      : position/index upon success, -1 otherwise

This procedure searches the input string for a sub-string.

Note that the returned index is base zero (first position is zero) to conform to Tcl's string indexing.

## getyn

    Declaration  : proc getyn {prompt}
    Parameters   :
          Name   : prompt
          Type   : string
    Description  : prompt string

    Returns      : 1 if yes, 0 if no

This procedure will display the prompt string and wait for a user yes or no response. No other response is allowed. procedure will not exit until a valid response is received.

## command_worddel

    Declaration  : proc command_worddel {instr outstr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : command word number

    Returns      : 1 upon success, 0 otherwise

This function will delete a specific command word within the input string and load the result into the output string.

## worddel

    Declaration  : proc worddel {instr outstr which}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : word number

    Returns      : 1 upon success, 0 otherwise

This procedure will delete a specific space delimited word from the input string and load this into the output string.

## ll_worddel

    Declaration  : proc ll_worddel {instr outstr which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : 1 upon success, 0 otherwise

This procedure will delete a specific word from the input string based on a specific word delimiter.

## ll_wordput

    Declaration  : proc ll_wordput {instr outstr wdata which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : wdata
          Type   : string
    Description  : word data

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : 1 upon success, 0 otherwise

This procedure will place the word data into the input string at the specific word. If the specific word already exists, it will be replaced, if does not exist, the word string will be extended out to the required word before copying. Each word is delimited by the word delimiter. The new string will be returned in the output string upon success.

## num

    Declaration  : proc num {instr}
    Parameters   :
          Name   : instr
          Type   : number string
    Description  : input string

    Returns      : 1 if a number, 0 otherwise

This procedure evaluates the input string to determine whether it is a valid number. Numbers are the digits 0-9. A minus sign is allowed in the first character. No other characters are allowed.

## ucase

    Declaration  : proc ucase {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : converted string

This procedure will convert the input string to uppercase and return it.

## parse_extend

    Declaration  : proc parse_extend {instr outstr which delim}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : which
          Type   : positive integer
    Description  : word number

          Name   : delim
          Type   : single character string
    Description  : word delimiter

    Returns      : 1 upon success, 0 otherwise

This procedure will extend the input string out to the requested word. Each word is delimited by the word delimiter. You may not extend using the space delimiter because of the nature of the space and the trim function.

## initstring

    Declaration  : proc initstring {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : copy of the input string

This procedure will create a copy of the input string and return it. Not really required in Tcl but provided for compatibility with C source code.

## inittstring

    Declaration  : proc inittstring {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : trimed copy of the input string

This procedure will create a trimed copy of the input string and return it. Not really required in Tcl but provided for compatibility with C source code.

## initqstring

    Declaration  : proc initqstring {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : quoted copy of the string

This procedure will create a quoted copy of the input string (if the input string contains more than one word) and return it. If the input string does not contain more than one word, the output copy will not be quoted. Quoted strings contain matching single quotes.

## delbytes

    Declaration  : proc delbytes {instr outstr pos numbytes}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : outstr
          Type   : string
    Description  : output string

          Name   : pos
          Type   : integer
    Description  : position/index

          Name   : numbytes
          Type   : integer
    Description  : number of bytes

    Returns      : 1 upon success, 0 otherwise

This procedure will delete the number of bytes from the input string starting from the given position and place the result into the output string. The number of bytes may be zero which indicates from the position for the remainder of the string.

## logic_string_2_flag

    Declaration  : proc logic_string_2_flag {instr flag}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

          Name   : flag
          Type   : boolean
    Description  : output converted flag

    Returns      : 1 upon success, 0 otherwise

This procedure converts a string representation of a flag or switch to an integer (boolean) flag value. The input string must be one of:

- yes
- no
- true
- false
- on
- off
- 0
- 1

String comparison is case insensitive.

## flag_2_logic_string

    Declaration  : proc flag_2_logic_string {flag outstr}
    Parameters   :
          Name   : flag
          Type   : boolean
    Description  : input flag

          Name   : outstr
          Type   : string
    Description  : output logic string

    Returns      : 1 upon success, 0 otherwise

This procedure converts a boolean value to an English logic string. The input flag value must be either zero or one. The output logic string will be on for one and off for zero.

## pmatch

    Declaration  : proc pmatch {pat name}
    Parameters   :
          Name   : pat
          Type   : string
    Description  : pattern

          Name   : name
          Type   : string
    Description  : name or word to match

    Returns      : 1 if a match was found, 0 otherwise

This procedure will attempt to match the given name or word to match with the pattern. The pattern may be anything acceptable to the Tcl string match command.

## lpad

    Declaration  : proc lpad {istr padch padlen}
    Parameters   :
          Name   : istr
          Type   : string
    Description  : input string

          Name   : padch
          Type   : single character string
    Description  : pad character

          Name   : padlen
          Type   : positive integer
    Description  : desired padded length

    Returns      : padded string

This procedure will pad a string on the left with the pad character to the desired padded length.

## rpad

    Declaration  : proc rpad {istr padch padlen}
    Parameters   :
          Name   : istr
          Type   : string
    Description  : input string

          Name   : padch
          Type   : single character string
    Description  : pad character

          Name   : padlen
          Type   : positive integer
    Description  : desired padded length

    Returns      : padded string

This procedure will pad a string on the right with the pad character to the desired padded length.

## strip_space

    Declaration  : proc strip_space {instr}
    Parameters   :
          Name   : instr
          Type   : string
    Description  : input string

    Returns      : stripped string

This procedure will strip all spaces from the input string.

Goto Top | Tcl Applications | Tcl Software Overview | Tcl Library Overview
| Future Lab Home | Contact Webmaster | Feedback

Copyright © 2006 Future Lab, Last Updated Jul 01, 2006