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.