NAME

       ::textutil  - Procedures to manipulate texts and strings..


SYNOPSIS

_________________________________________________________________

       textutil::adjust string args
                                         0]+}
       textutil::splitx string {regexp [

       textutil::tabify string {num 8}

       textutil::trim string {regexp [ ]+}

       textutil::trimleft string {regexp [ ]+}

       textutil::trimright string {regexp [ ]+}

       textutil::untabify string {num 8}

       textutil::strRepeat string num
_________________________________________________________________


DESCRIPTION

       The ::textutil package provides commands  that  manipulate
       strings  or  texts  (a.k.a.  long  strings  or string with
       embedded newlines or paragraphs).

       The complete set of procedures is described below.

       textutil::adjust string args
              Do a justification on the string according to args.
              The  string is taken as one big paragraph, ignoring
              any newlines.  Then the line is formatted according
              to  the  options used, and the command return a new
              string with enough lines to contain all the  print­
              able  chars in the input string. A line is a set of
              chars between the beginning of  the  string  and  a
              newline,  or  between 2 newlines, or between a new­
              line and the end of the string. If the input string
              is  small enough, the returned string won't contain
              any newlines.

       By default, any occurrence of spaces characters or
              tabulation are
              replaced by a single space so each word in  a  line
              is separated from the next one by exactly one space
              char, and this forms a real line. Each real line is
              placed  in  a  logical  line,  which have exactly a
              given length (see -length option below).  The  real

              any trailing spaces are  ignored  before  returning
              the  string (see -full option below). The following
              options may be used after the string parameter, and
              change  the  way the command place a real line in a
              logical line.

       -full boolean
              if set to  false,  any  trailing  space  chars  are
              deleted  before  returning  the  string.  If set to
              true, any trailing space  chars  are  left  in  the
              string. Default to false.

       -justify (center|left|plain|right)
              set  the  justification  of  the returned string to
              center, left, plain or right. By default, it is set
              to  left.  The justification means that any line in
              the returned string  but  the  last  one  is  build
              according to the value. If the justification is set
              to plain and the number of printable chars  in  the
              last  line is less than 90% of the length of a line
              (see -length), then this line is justified with the
              left  value,  avoiding  the  expansion of this line
              when it is too small. The meaning of each value is:

              centerthe real line is centered in the logical
                     line. If needed, a set of space
                     char are added at the beginning (half of the
                     needed set) and at  the  end  (half  of  the
                     needed  set)  of  the  line if required (see
                     -full option).

              left   the real line is set on the left of the log­
                     ical  line. It means that there are no space
                     chars at the  beginning  of  this  line.  If
                     required,  all  needed space chars are added
                     at the end of the line (see -full option).

              plain  the real line is exactly set in the  logical
                     line.  It means that there are no leading or
                     trailing space chars. All the  needed  space
                     chars  are added in the real line, between 2
                     (or more) words.

              right  the real line is set on  the  right  of  the
                     logical  line.  It  means  that there are no
                     space chars at the end  of  this  line,  and
                     there  may be some space chars at the begin­
                     ning, despite of the -full option.

       -length integer
              set the length of the logical line in the string to
              integer.  integer must be a positive integer value.
              Default to 72.

              Split the string and return a list. The  string  is
              split  according  to  the regular expression regexp
              instead of a simple list of chars. Note that if you
              add  parenthesis  into  the regexp, the parentheses
              part of separator would be added into list as addi­
              tional element.

       textutil::tabify string {num 8}
              Tabify the string by replacing any substring of num
              space chars by a tabulation and return  the  result
              as a new string.

       textutil::trim string {regexp [    ]+}
              Remove in string any leading and trailing substring
              according to  the  regular  expression  regexp  and
              return  the  result as a new string.  This apply on
              any line in  the  string,  that  is  any  substring
              between  2  newline chars, or between the beginning
              of the string and a newline, or between  a  newline
              and  the  end of the string, or, if the string con­
              tain no newline, between the beginning and the  end
              of the string.

       textutil::trimleft string {regexp [     ]+}
              Remove in string any leading substring according to
              the regular expression regexp and return the result
              as  a  new  string.  This  apply on any line in the
              string, that is any  substring  between  2  newline
              chars, or between the beginning of the string and a
              newline, or between a newline and the  end  of  the
              string,  or,  if  the  string  contain  no newline,
              between the beginning and the end of the string.

       textutil::trimright string {regexp [    ]+}
              Remove in string any trailing  substring  according
              to  the  regular  expression  regexp and return the
              result as a new string. This apply on any  line  in
              the string, that is any substring between 2 newline
              chars, or between the beginning of the string and a
              newline,  or  between  a newline and the end of the
              string, or,  if  the  string  contain  no  newline,
              between the beginning and the end of the string.

       textutil::untabify string {num 8}
              Untabify  the  string  by  replacing any tabulation
              char by a substring of num space chars  and  return
              the result as a new string.

              The  implementation  depends  on the core executing
              the package. Used string repeat if it  is  present,
              or  a fast tcl implementation if it is not. Returns
              a string containing the text  repeated  num  times.
              The   repetitions  are  joined  without  characters
              between them. A value of num <= 0 causes  the  com­
              mand to return an empty string.


SEE ALSO

       regexp, split, string


KEYWORDS

       string, regular expression


Man(1) output converted with man2html