include/wvtclstring.h

   1 /* -*- Mode: C++ -*-
   2  * Worldvisions Weaver Software:
   3  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
   4  *
   5  * FIXME:
   6  *   It would be possible to represent arbitrary binary blobs using this
   7  *   technique, but we'd have to avoid using null-terminated strings in a few
   8  *   places, particularly in the input to wvtcl_escape().
   9  *
  10  *   We could even make encoded binary blobs printable (although that's not
  11  *   _strictly_ necessary in all cases) by encoding non-printable characters
  12  *   using \x## notation, if wvtcl_escape() or wvtcl_unescape() supported it.
  13  */
  14 /** \file
  15  * Functions to handle "tcl-style" strings and lists.
  16  *
  17  * Using wvtcl_encode(), you can encode _any_ list of strings into a single
  18  * string, then reliably split the single string back into the list using
  19  * wvtcl_decode().
  20  *
  21  * You can create recursive lists of lists by simply running wvtcl_encode()
  22  * on a list of strings returned from wvtcl_encode().
  23  *
  24  * Example list encodings (all of the following lists have exactly 3 elements):
  25  *     foo blah weasels
  26  *     e1 elem2 {element 3}
  27  *     x1 {} "element 3"
  28  *     w x y\ z
  29  *
  30  * Example list of lists:
  31  *     foo\ blah\ weasels {e1 elem2 {element 3}} {w x y\ z}
  32  */
  33
  34 #ifndef __WVTCLSTRING_H
  35 #define __WVTCLSTRING_H
  36
  37 #include "wvbuf.h"
  38 class WvStringMask;
  39
  40 // the default set of "nasties", ie. characters that need to be escaped if
  41 // they occur somewhere in a string.
  42 #define WVTCL_NASTY_SPACES_STR    " \t\n\r"
  43 extern const WvStringMask WVTCL_NASTY_SPACES;
  44
  45 // Another default set of nasties, but only splitting on newlines
  46 #define WVTCL_NASTY_NEWLINES_STR  "\n\r"
  47 extern const WvStringMask WVTCL_NASTY_NEWLINES;
  48
  49 // {, }, \, and " are always considered "nasty."
  50 #define WVTCL_ALWAYS_NASTY_CASE '{': case '}': case '\\': case '"'
  51
  52
  53 // the default set of split characters, ie. characters that separate elements
  54 // in a list.  If these characters appear unescaped and not between {} or ""
  55 // in a list, they signify the end of the current element.
  56 #define WVTCL_SPLITCHARS_STR " \t\n\r"
  57 extern const WvStringMask WVTCL_SPLITCHARS;
  58
  59
  60 /**
  61  * tcl-escape a string.  There are three ways to do this:
  62  *   1) Strings that need no escaping are unchanged.
  63  *   2) Strings containing characters in 'nasties' are usually encoded just
  64  *         by enclosing the unmodified string in braces.
  65  *         (For example, "foo blah" becomes "{foo blah}")
  66  *   3) Strings containing nasties _and_ unmatched braces are encoded using
  67  *         backslash notation.  (For example, " foo} " becomes "\ foo\}\ "
  68  */
  69 WvString wvtcl_escape(WvStringParm s,
  70                       const WvStringMask &nasties = WVTCL_NASTY_SPACES);
  71
  72
  73 /**
  74  * tcl-unescape a string.  This is generally the reverse of wvtcl_escape,
  75  * except we can reverse any backslashified or embraced string, even if it
  76  * doesn't follow the "simplest encoding" rules used by wvtcl_escape.  We
  77  * can also handle strings in double-quotes, ie. '"foo"' becomes 'foo'.
  78  */
  79 WvString wvtcl_unescape(WvStringParm s);
  80
  81
  82 /**
  83  * encode a tcl-style list.  This is easily done by tcl-escaping each
  84  * string in 'l', then appending the escaped strings together, separated by
  85  * the first char in splitchars.
  86  */
  87 WvString wvtcl_encode(WvList<WvString> &l,
  88                       const WvStringMask &nasties = WVTCL_NASTY_SPACES,
  89                       const WvStringMask &splitchars = WVTCL_SPLITCHARS);
  90
  91 /**
  92  * Get a single tcl word from an input buffer, and return the rest of the
  93  * buffer untouched.  If no word can be created from the buffer, return
  94  * a null string and leave the buffer unmodified.
  95  */
  96 WvString wvtcl_getword(WvBuf &buf,
  97                        const WvStringMask &splitchars = WVTCL_SPLITCHARS,
  98                        bool do_unescape = true);
  99
 100 /**
 101  * split a tcl-style list.  There are some special "convenience" features
 102  * here, which allow users to create lists more flexibly than wvtcl_encode
 103  * would do.
 104  *
 105  * Elements of the list are separated by any number of any characters from
 106  * the 'splitchars' list.
 107  *
 108  * Quotes are allowed around elements: '"foo"' becomes 'foo'.  These work
 109  * mostly like braces, except the string is assumed to be backslashified.
 110  * That is, '"\ "' becomes ' ', whereas '{\ }' becomes '\ ' (ie. the backslash
 111  * wouldn't be removed).
 112  *
 113  * Zero-length elements must be represented by {}
 114  *
 115  */
 116 void wvtcl_decode(WvList<WvString> &l, WvStringParm _s,
 117                   const WvStringMask &splitchars = WVTCL_SPLITCHARS,
 118                   bool do_unescape = true);
 119
 120 #endif // __WVTCLSTRING_H