confparse.hh File Reference

---

Detailed Description

Support for parsing configuration strings.

Defines functions and helpers for parsing configuration strings into numbers, IP addresses, and other useful types.

cp_va_kparse Introduction

Most elements that take configuration strings parse them using the cp_va_kparse() function and friends. These functions take a variable argument list describing the desired arguments and result slots. They parse the configuration, store the results in the slots, report any errors, and return the number of arguments successfully assigned on success or a negative value on failure.

Note:

Previous versions of Click used cp_va_parse() and friends instead of cp_va_kparse(). A guide for transitioning from cp_va_parse() to cp_va_kparse() is given in the documentation for cp_va_parse().

Here are some cp_va_kparse() examples.

 int MyElement::configure(Vector<String> &conf, ErrorHandler *errh) {
     String data; uint32_t limit = 0; bool stop = false;
     if (cp_va_kparse(conf, this, errh,
                      "DATA", cpkP+cpkM, cpString, &data,
                      "LIMIT", cpkP, cpUnsigned, &limit,
                      "STOP", 0, cpBool, &stop,
                      cpEnd) < 0)   // argument list always terminated by cpEnd
         return -1;
     ... }

This element supports three arguments, DATA (a string), LIMIT (an unsigned integer), and STOP (a boolean). Here are some example element definitions:

 MyElement(DATA "blah blah blah", LIMIT 10);
             /* OK, sets data = "blah blah blah", limit = 10; leaves stop unchanged */
 MyElement(LIMIT 10, DATA "blah blah blah");
             /* OK, has the same effect */
 MyElement(LIMIT 10);
             /* error "missing mandatory DATA argument" */
             /* (the cpkM flag marks an argument as mandatory) */
 MyElement(DATA "blah blah blah");
             /* OK, sets data = "blah blah blah" and leaves limit unchanged */
             /* (LIMIT lacks the cpkM flag, so it can be left off) */
 MyElement(DATA "blah blah blah", STOP true);
             /* OK, sets data = "blah blah blah" and stop = true */
             /* (LIMIT lacks the cpkM flag, so it can be left off) */
 MyElement(DATA "blah blah blah", LIMIT 10, DATA "blah");
             /* OK, sets data = "blah" (later arguments take precedence) */
 MyElement(DATA "blah blah blah", LIMIT 10, BOGUS "bogus");
             /* error "too many arguments" */
 MyElement("blah blah blah", 10);
             /* OK, same as MyElement(DATA "blah blah blah", LIMIT 10) */
             /* (the cpkP flag allows positional arguments) */
 MyElement("blah blah blah", 10, true);
             /* error "too many arguments" */
             /* (STOP lacks the cpkP flag and must be given by name) */

cp_va_kparse Items

An item in a cp_va_kparse() argument list consists of:

1. Argument name (type: const char *). Example: "DATA".
2. Parse flags (type: int). Zero or more of cpkP, cpkM, and cpkC.
3. If the parse flags contain cpkC, then a confirmation flag comes next (type: bool *). This flag is set to true if an argument successfully matched the item and false if not.
4. Argument type (type: CpVaParseCmd). Defines the type of argument read from the configuration string. Example: cpString.
5. Optional parse parameters (determined by the argument type). For example, cpUnsignedReal2 takes a parse parameter that defines how many bits of fraction are needed.
6. Result storage (determined by the argument type).

This example uses more of these features.

 int MyElement2::configure(Vector<String> &conf, ErrorHandler *errh) {
     bool p_given; uint32_t p = 0x10000; IPAddress addr, mask;
     if (cp_va_kparse(conf, this, errh,
                      "P", cpkC, &p_given, cpUnsignedReal2, 16, &p,
                      "NETWORK", 0, cpIPPrefix, &addr, &mask,
                      cpEnd) < 0)
         return -1;
     ... }

This element supports two arguments, P (a fixed-point number with 16 bits of fraction) and NETWORK (an IP prefix, defined by address and mask). Here are some example element definitions:

 MyElement2();
             /* OK, since neither argument is mandatory; sets p_given = false */
 MyElement2(P 0.5, PREFIX 10/8);
             /* OK, sets p_given = true, p = 0x8000, addr = 10.0.0.0, and mask = 255.0.0.0 */

cp_va_kparse Argument Types

cp_va_kparse() argument types are defined by CpVaParseCmd constants. For example, the cpInteger argument type parses a 32-bit signed integer. See CpVaParseCmd for more. Elements may also define their own argument types with cp_register_argtype().

Direct Parsing Functions

You may also call parsing functions directly if cp_va_kparse() doesn't match your needs. These functions have names like cp_bool(), cp_string(), cp_integer(), cp_ip_address(), and so forth, and share a basic interface:

• The first argument, const String &str, contains the string to be parsed.
• The last argument(s) specify locations where the parsed results should be stored. These result arguments have pointer type.
• The return type is bool. True is returned if and only if parsing succeeds, and the result slots are modified if and only if parsing succeeds.
• Most parsing functions expect to parse the entire supplied string. Any extraneous characters, such as trailing whitespace, cause parsing to fail.
• Most parsing functions never report errors to any source; they simply return false when parsing fails.

Argument Manipulation

Finally, functions like cp_uncomment(), cp_unquote(), cp_quote(), cp_argvec(), and cp_is_space() manipulate arguments as strings. cp_uncomment() removes comments and simplifies white space; cp_unquote() removes quotation marks and expands backslash escapes; cp_argvec() splits a configuration string at commas; and so forth.

#include <click/string.hh>
#include <click/vector.hh>

Go to the source code of this file.

Classes
struct	cp_argtype
struct	cp_value
Direct Parsing Functions
#define	CP_REAL2_MAX_FRAC_BITS   28
enum	CpErrors {   CPE_OK = 0, CPE_FORMAT, CPE_NEGATIVE, CPE_OVERFLOW,   CPE_INVALID, CPE_MEMORY, CPE_NOUNITS }
enum	{ cp_basic_integer_whole = 64 }
int	cp_errno
bool	cp_string (const String &str, String *result, String *rest=0)
	Parse a string from str.
bool	cp_word (const String &str, String *result, String *rest=0)
	Parse a word from str.
bool	cp_keyword (const String &str, String *result, String *rest=0)
	Parse a keyword from str.
bool	cp_bool (const String &str, bool *result)
	Parse a boolean from str.
const char *	cp_basic_integer (const char *begin, const char *end, int flags, int size, void *result)
const char *	cp_integer (const char *begin, const char *end, int base, int *result)
	Parse an integer from [begin, end) in base base.
const char *	cp_integer (const char *begin, const char *end, int base, unsigned *result)
const char *	cp_integer (const char *begin, const char *end, int base, long *result)
const char *	cp_integer (const char *begin, const char *end, int base, unsigned long *result)
const char *	cp_integer (const char *begin, const char *end, int base, int64_t *result)
const char *	cp_integer (const char *begin, const char *end, int base, uint64_t *result)
bool	cp_integer (const String &str, int base, int *result)
	Parse an integer from str in base base.
bool	cp_integer (const String &str, int base, unsigned int *result)
bool	cp_integer (const String &str, int base, long *result)
bool	cp_integer (const String &str, int base, unsigned long *result)
bool	cp_integer (const String &str, int base, int64_t *result)
bool	cp_integer (const String &str, int base, uint64_t *result)
bool	cp_integer (const String &str, int *result)
	Parse an integer from str in base 0.
bool	cp_integer (const String &str, unsigned int *result)
bool	cp_integer (const String &str, long *result)
bool	cp_integer (const String &str, unsigned long *result)
bool	cp_integer (const String &str, int64_t *result)
bool	cp_integer (const String &str, uint64_t *result)
bool	cp_real2 (const String &str, int frac_bits, int32_t *result)
	Parse a fixed-point number from str.
bool	cp_real2 (const String &str, int frac_bits, uint32_t *result)
bool	cp_real10 (const String &str, int frac_digits, int32_t *result)
	Parse a real number from str, representing the result as an integer with frac_digits decimal digits of fraction.
bool	cp_real10 (const String &str, int frac_digits, uint32_t *result)
bool	cp_real10 (const String &str, int frac_digits, uint32_t *result_int, uint32_t *result_frac)
	Parse a real number from str, representing the result as an integer with frac_digits decimal digits of fraction.
bool	cp_double (const String &str, double *result)
	Parse a real number from str.
bool	cp_seconds_as (const String &str, int frac_digits, uint32_t *result)
	Parse an amount of time from str.
bool	cp_seconds_as_milli (const String &str, uint32_t *result)
	Parse an amount of time in milliseconds from str.
bool	cp_seconds_as_micro (const String &str, uint32_t *result)
	Parse an amount of time in microseconds from str.
bool	cp_seconds (const String &str, double *result)
	Parse an amount of time from str.
bool	cp_time (const String &str, Timestamp *result)
	Parse a timestamp from str.
bool	cp_time (const String &str, struct timeval *result)
bool	cp_bandwidth (const String &str, uint32_t *result)
	Parse a bandwidth value from str.
bool	cp_ip_address (const String &str, IPAddress *result, Element *context=0)
	Parse an IP address from str.
bool	cp_ip_address (const String &str, struct in_addr *result, Element *context=0)
bool	cp_ip_address (const String &str, unsigned char *result, Element *context=0)
bool	cp_ip_prefix (const String &str, IPAddress *result_addr, IPAddress *result_mask, bool allow_bare_address, Element *context=0)
	Parse an IP address or prefix from str.
bool	cp_ip_prefix (const String &str, unsigned char *result_addr, unsigned char *result_mask, bool allow_bare_address, Element *context=0)
bool	cp_ip_prefix (const String &str, IPAddress *result_addr, IPAddress *result_mask, Element *context=0)
bool	cp_ip_prefix (const String &str, unsigned char *result_addr, unsigned char *result_mask, Element *context=0)
bool	cp_ip_address_list (const String &str, Vector< IPAddress > *result, Element *context=0)
	Parse a space-separated list of IP addresses from str.
bool	cp_ip6_address (const String &str, IP6Address *result, Element *context=0)
	Parse an IPv6 address from str.
bool	cp_ip6_address (const String &str, unsigned char *result, Element *context=0)
bool	cp_ip6_prefix (const String &str, IP6Address *result_addr, int *result_prefix, bool allow_bare_address, Element *context=0)
	Parse an IPv6 address or prefix from str.
bool	cp_ip6_prefix (const String &str, unsigned char *result_addr, int *result_prefix, bool allow_bare_address, Element *context=0)
bool	cp_ip6_prefix (const String &str, unsigned char *result_addr, unsigned char *result_mask, bool allow_bare_address, Element *context=0)
bool	cp_ip6_prefix (const String &str, IP6Address *result_addr, IP6Address *result_mask, bool allow_bare_address, Element *context=0)
bool	cp_ethernet_address (const String &str, EtherAddress *result, Element *context=0)
	Parse an Ethernet address from str.
bool	cp_ethernet_address (const String &str, unsigned char *result, Element *context=0)
bool	cp_tcpudp_port (const String &str, int proto, uint16_t *result, Element *context=0)
	Parse a TCP, UDP, etc. port number from str.
Element *	cp_element (const String &str, const Element *context, ErrorHandler *errh=0)
	Parse an element reference from str.
Element *	cp_element (const String &str, Router *router, ErrorHandler *errh=0)
	Parse an element reference from str.
bool	cp_handler_name (const String &str, Element **result_element, String *result_hname, const Element *context, ErrorHandler *errh=0)
	Parse a handler name from str.
bool	cp_handler (const String &str, int flags, Element **result_element, const Handler **result_handler, const Element *context, ErrorHandler *errh=0)
	Parse a handler reference from str.
bool	cp_filename (const String &str, String *result)
	Parse a filename string from str.
bool	cp_file_offset (const String &str, off_t *result)
	Parse a file offset from str.
bool	cp_anno (const String &str, int size, int *result, Element *context=0)
	Parse a packet annotation value from str.
cp_va_kparse
enum	CpKparseFlags {   cpkN = 0, cpkM = 1, cpkP = 2, cpkC = 4,   cpkD = 8, cpkNormal = cpkN, cpkMandatory = cpkM, cpkPositional = cpkP,   cpkConfirm = cpkC, cpkDeprecated = cpkD }
	Type of flags for cp_va_kparse() items. More...
const CpVaParseCmd	cpEnd
	Use as argument name. Ends cp_va argument list.
const CpVaParseCmd	cpIgnoreRest
	Use as argument name. No result storage; causes cp_va_kparse() to ignore unparsed arguments and any remaining items.
const CpVaParseCmd	cpIgnore
	No result storage, ignores this argument.
const CpVaParseCmd	cpArgument
	Result storage String*, accepts any argument.
const CpVaParseCmd	cpArguments
	Result storage Vector<String>*, accepts any number of arguments with the same keyword.
const CpVaParseCmd	cpString
	Result storage String*, parsed by cp_string().
const CpVaParseCmd	cpWord
	Result storage String*, parsed by cp_word().
const CpVaParseCmd	cpKeyword
	Result storage String*, parsed by cp_keyword().
const CpVaParseCmd	cpBool
	Result storage bool*, parsed by cp_bool().
const CpVaParseCmd	cpByte
	Result storage unsigned char*, parsed by cp_integer().
const CpVaParseCmd	cpShort
	Result storage short*, parsed by cp_integer().
const CpVaParseCmd	cpUnsignedShort
	Result storage unsigned short*, parsed by cp_integer().
const CpVaParseCmd	cpInteger
	Result storage int32_t*, parsed by cp_integer().
const CpVaParseCmd	cpUnsigned
	Result storage uint32_t*, parsed by cp_integer().
const CpVaParseCmd	cpNamedInteger
	Parse parameter uint32_t nameinfo_type, result storage int32_t*, parsed by NameInfo::query_int.
const CpVaParseCmd	cpInteger64
	Result storage int64_t*, parsed by cp_integer().
const CpVaParseCmd	cpUnsigned64
	Result storage uint64_t*, parsed by cp_integer().
const CpVaParseCmd	cpUnsignedReal2
	Parse parameter int frac_bits, result storage uint32_t*, parsed by cp_real2().
const CpVaParseCmd	cpReal10
	Parse parameter int frac_digits, result storage int32_t*, parsed by cp_real10().
const CpVaParseCmd	cpUnsignedReal10
	Parse parameter int frac_digits, result storage uint32_t*, parsed by cp_real10().
const CpVaParseCmd	cpDouble
	Result storage double*, parsed by cp_double().
const CpVaParseCmd	cpSeconds
	Result storage uint32_t*, parsed by cp_seconds_as() with frac_digits 0.
const CpVaParseCmd	cpSecondsAsMilli
	Result storage uint32_t*, parsed by cp_seconds_as_milli().
const CpVaParseCmd	cpSecondsAsMicro
	Result storage uint32_t*, parsed by cp_seconds_as_micro().
const CpVaParseCmd	cpTimestamp
	Result storage Timestamp*, parsed by cp_time().
const CpVaParseCmd	cpTimeval
	Result storage struct timeval*, parsed by cp_time().
const CpVaParseCmd	cpBandwidth
	Result storage uint32_t*, parsed by cp_bandwidth().
const CpVaParseCmd	cpIPAddress
	Result storage IPAddress* or equivalent, parsed by cp_ip_address().
const CpVaParseCmd	cpIPPrefix
	Result storage IPAddress* addr and IPAddress *mask, parsed by cp_ip_prefix().
const CpVaParseCmd	cpIPAddressOrPrefix
	Result storage IPAddress* addr and IPAddress *mask, parsed by cp_ip_prefix().
const CpVaParseCmd	cpIPAddressList
	Result storage Vector<IPAddress>*, parsed by cp_ip_address_list().
const CpVaParseCmd	cpEtherAddress
	Result storage EtherAddress*, parsed by cp_ethernet_address().
const CpVaParseCmd	cpEthernetAddress
	Result storage EtherAddress*, parsed by cp_ethernet_address(). Synonym for cpEtherAddress.
const CpVaParseCmd	cpTCPPort
	Result storage uint16_t*, parsed by cp_tcpudp_port().
const CpVaParseCmd	cpUDPPort
	Result storage uint16_t*, parsed by cp_tcpudp_port().
const CpVaParseCmd	cpElement
	Result storage Element**, parsed by cp_element().
const CpVaParseCmd	cpHandlerName
	Result storage Element** and String*, parsed by cp_handler_name().
const CpVaParseCmd	cpHandlerCallRead
	Result storage HandlerCall*, parsed by HandlerCall.
const CpVaParseCmd	cpHandlerCallWrite
	Result storage HandlerCall*, parsed by HandlerCall.
const CpVaParseCmd	cpHandlerCallPtrRead
	Result storage HandlerCall**, parsed by HandlerCall::reset_read.
const CpVaParseCmd	cpHandlerCallPtrWrite
	Result storage HandlerCall**, parsed by HandlerCall::reset_write.
const CpVaParseCmd	cpIP6Address
	Result storage IP6Address* or equivalent, parsed by cp_ip6_address().
const CpVaParseCmd	cpIP6Prefix
	Result storage IP6Address* addr and IP6Address* mask, parsed by cp_ip6_prefix().
const CpVaParseCmd	cpIP6AddressOrPrefix
	Result storage IP6Address* addr and IP6Address* mask, parsed by cp_ip6_prefix().
const CpVaParseCmd	cpDesCblock
	Result storage uint8_t[8], parsed by cp_des_cblock().
const CpVaParseCmd	cpFilename
	Result storage String*, parsed by cp_filename().
const CpVaParseCmd	cpFileOffset
	Result storage off_t*, parsed by cp_integer().
const CpVaParseCmd	cpAnno
	Parse parameter int annotation_size, result storage int*, parsed by cp_anno().
const CpVaParseCmd	cpOptional
	cp_va_parse only: Following arguments are optional.
const CpVaParseCmd	cpKeywords
	cp_va_parse only: Following arguments are keywords.
const CpVaParseCmd	cpConfirmKeywords
	cp_va_parse only: Following arguments are confirmed keywords.
const CpVaParseCmd	cpMandatoryKeywords
	cp_va_parse only: Following arguments are mandatory keywords.
const CpVaParseCmd cpInterval	CLICK_CONFPARSE_DEPRECATED
const CpVaParseCmd cpInterval cpReadHandlerCall	CLICK_CONFPARSE_DEPRECATED
const CpVaParseCmd cpInterval cpReadHandlerCall cpWriteHandlerCall	CLICK_CONFPARSE_DEPRECATED
typedef const char *	CpVaParseCmd
	Type of argument type names for cp_va_kparse() items.
int	cp_va_kparse (const Vector< String > &conf, Element *context, ErrorHandler *errh,...) CP_SENTINEL
int	cp_va_kparse (const String &str, Element *context, ErrorHandler *errh,...) CP_SENTINEL
int	cp_va_space_kparse (const String &str, Element *context, ErrorHandler *errh,...) CP_SENTINEL
int	cp_va_kparse_keyword (const String &str, Element *context, ErrorHandler *errh,...) CP_SENTINEL
int	cp_va_kparse_remove_keywords (Vector< String > &conf, Element *context, ErrorHandler *errh,...) CP_SENTINEL
int	cp_assign_arguments (const Vector< String > &argv, const String *param_begin, const String *param_end, Vector< String > *values=0)
	Assign arguments from argv to values.
void	cp_va_static_initialize ()
	Initialize the cp_va_kparse() implementation.
void	cp_va_static_cleanup ()
	Clean up the cp_va_kparse() implementation.
Argument Types for cp_va_kparse()
enum	{ cpArgNormal = 0, cpArgStore2 = 1, cpArgExtraInt = 2, cpArgAllowNumbers = 4 }
typedef void(*)	cp_parsefunc (cp_value *value, const String &arg, ErrorHandler *errh, const char *argdesc, Element *context)
typedef void(*)	cp_storefunc (cp_value *value, Element *context)
int	cp_register_argtype (const char *name, const char *description, int flags, cp_parsefunc parsefunc, cp_storefunc storefunc, void *user_data=0)
void	cp_unregister_argtype (const char *name)
int	cp_register_stringlist_argtype (const char *name, const char *description, int flags)
int	cp_extend_stringlist_argtype (const char *name,...)
Argument Manipulation
const char *	cp_skip_space (const char *begin, const char *end)
	Find the first nonspace character in the string [begin, end).
const char *	cp_skip_comment_space (const char *begin, const char *end)
	Find the first nonspace, noncomment character in the string [begin, end).
const char *	cp_skip_double_quote (const char *begin, const char *end)
	Return the first character after a double-quoted string starting at begin.
bool	cp_eat_space (String &str)
	Remove spaces from the beginning of str.
bool	cp_is_space (const String &str)
	Test if str is all spaces.
bool	cp_is_word (const String &str)
	Test whether str is a valid "word".
bool	cp_is_click_id (const String &str)
	Test if str is a valid Click identifier.
String	cp_uncomment (const String &str)
	Simplify str's whitespace and replace comments by spaces, returning the result.
String	cp_unquote (const String &str)
	Remove one level of quoting from str, returning the result.
const char *	cp_process_backslash (const char *begin, const char *end, StringAccum &sa)
	Process a backslash escape, appending results to sa.
String	cp_quote (const String &str, bool allow_newlines=false)
	Return a quoted version of str.
void	cp_argvec (const String &str, Vector< String > &conf)
	Separate a configuration string into arguments at commas.
String	cp_unargvec (const Vector< String > &conf)
	Join the strings of conf with commas and return the result.
void	cp_spacevec (const String &str, Vector< String > &conf)
	Separate a configuration string into arguments at unquoted spaces.
String	cp_pop_spacevec (String &str)
	Remove and return the first space-separated argument from str.
String	cp_unspacevec (const String *begin, const String *end)
	Join the strings in [begin, end) with spaces and return the result.
String	cp_unspacevec (const Vector< String > &conf)
	Join the strings in conf with spaces and return the result.
Unparsing
String	cp_unparse_bool (bool value)
String	cp_unparse_real2 (int32_t value, int frac_bits)
String	cp_unparse_real2 (uint32_t value, int frac_bits)
String	cp_unparse_real2 (int64_t value, int frac_bits)
String	cp_unparse_real2 (uint64_t value, int frac_bits)
String	cp_unparse_real10 (int32_t value, int frac_digits)
String	cp_unparse_real10 (uint32_t value, int frac_digits)
String	cp_unparse_milliseconds (uint32_t value)
String	cp_unparse_microseconds (uint32_t value)
String	cp_unparse_interval (const Timestamp &value)
String	cp_unparse_interval (const struct timeval &value)
String	cp_unparse_bandwidth (uint32_t value)
Legacy Functions
int	cp_va_parse (const Vector< String > &conf, Element *context, ErrorHandler *errh,...)
int	cp_va_parse (const String &str, Element *context, ErrorHandler *errh,...)
int	cp_va_space_parse (const String &str, Element *context, ErrorHandler *errh,...)
int	cp_va_parse_keyword (const String &str, Element *context, ErrorHandler *errh,...)
int	cp_va_parse_remove_keywords (Vector< String > &conf, int first, Element *context, ErrorHandler *errh,...)

---

Typedef Documentation

typedef const char* CpVaParseCmd

Type of argument type names for cp_va_kparse() items.

---

Enumeration Type Documentation

enum CpKparseFlags

Type of flags for cp_va_kparse() items.

Enumerator:

cpkN	Default flags.
cpkM	Argument is mandatory.
cpkP	Argument may be specified positionally.
cpkC	Argument presence should be confirmed.
cpkD	Argument is deprecated.

---

Function Documentation

const char* cp_skip_space	(	const char *	begin,
		const char *	end
	)

Find the first nonspace character in the string [begin, end).

Parameters:

	begin	beginning of string
	end	one past end of string

Returns:

Pointer to first non-space character in [begin, end), or end if the string is all spaces.

Space characters are defined as by isspace() in the "C" locale, and consist of the characters in [ \f\n\r\t\v].

const char* cp_skip_comment_space	(	const char *	begin,
		const char *	end
	)

Find the first nonspace, noncomment character in the string [begin, end).

Parameters:

	begin	beginning of string
	end	one past end of string

Returns:

Pointer to first nonspace and noncomment character in [begin, end), or end if the string is all spaces and comments.

This function recognizes C-style and C++-style comments:

 /* C style */  // C++ style (runs until newline)

In C++-style comments, the character sequences "\n", "\r", and "\r\n" are recognized as newlines. The newline is considered part of the comment.

const char* cp_skip_double_quote	(	const char *	begin,
		const char *	end
	)

Return the first character after a double-quoted string starting at begin.

Parameters:

	begin	beginning of double-quoted string
	end	one past end of string

Returns:

Pointer to first character in [begin, end) after the double-quoted string, or end if the double-quoted portion is not correctly terminated.

Precondition:

begin < end and *begin == '\"'

cp_skip_double_quote() understands all the backslash escapes processed by cp_process_backslash().

bool cp_eat_space

(

String &

str

)

Remove spaces from the beginning of str.

Parameters:

[in,out]

str

string

Returns:

True if the resulting string is nonempty, false otherwise.

bool cp_is_space

(

const String &

str

)

[inline]

Test if str is all spaces.

Returns:

True when every character in str is a space.

bool cp_is_word

(

const String &

str

)

Test whether str is a valid "word".

A "word" in Click consists of one or more characters in the ASCII range '!' through '~', inclusive, except for the quote characters '"' and ''', the backslash '\', and the comma ','.

bool cp_is_click_id

(

const String &

str

)

Test if str is a valid Click identifier.

A Click identifier consists of one or more characters in the set [A-Za-z0-9/_@], with restrictions on where / may appear (it cannot be the first character or the last character, and two adjacent slashes aren't allowed either).

String cp_uncomment

(

const String &

str

)

Simplify str's whitespace and replace comments by spaces, returning the result.

Returns:

A version of str with all initial space removed, all final space removed, and all comments and space-comment sequences replaced by a single space character.

Adjacent space characters are preserved in the output unless they appear next to a comment. For example:

 cp_uncomment("  a   b  ") == "a   b", but:
 cp_uncomment("  a /* Comment */       b  ") == "a b"

Comment characters inside double or single quotes are ignored:

 cp_uncomment("  \" /*???  */ \"  ") == "\" /*???  */ \""

String cp_unquote

(

const String &

str

)

Remove one level of quoting from str, returning the result.

This function acts as cp_uncomment, plus removing one level of quoting. "..." and '...' sequences are replaced by their contents. Backslash escapes are expanded inside double quotes (see cp_process_backslash). Additionally, "\<...>" sequences are expanded outside of any quotes. For example:

 cp_unquote("\"\\n\" abc /* 123 */ '/* def */'") == "\n abc /* def */"

const char* cp_process_backslash	(	const char *	begin,
		const char *	end,
		StringAccum &	sa
	)

Process a backslash escape, appending results to sa.

Parameters:

	begin	beginning of string
	end	end of string
	sa	string accumulator

Precondition:

begin < end, and begin points to a backslash character.

Returns:

A pointer to the first character in [begin, end) following the backslash escape.

This function understands the following backslash escapes.

• "\[newline]" is ignored (it adds no characters to sa), where [newline] is one of the sequences "\n", "\r", or "\r\n".
• "\[C escape]" is processed as in C, where [C escape] is one of the characters in [abfnrtv].
• "\\" expands to a single backslash. Similarly, "\$", "\'", "\\""</tt>, and <tt>"\," expand to the escaped character.
• "\[1-3 octal digits]" expands to the given character.
• "\x[hex digits]" expands to the given character.
• "\<[hex digits, spaces, and comments]>" expands to the binary string indicated by the hex digits. Spaces and comments are removed. For example,

   "<48656c6C 6f 2 /* And finally */ 1>" expands to "Hello!"
  

  (This example should begin with "\<"; it may not because of Doxygen problems.)
• A backslash at the end of the string expands to a backslash.

String cp_quote	(	const String &	str,
		bool	allow_newlines
	)

Return a quoted version of str.

Parameters:

	str	string
	allow_newlines	If true, then newline sequences are allowed in in the result. If false, then newline sequences should be translated to their backslash escape equivalents. Default is false.

Returns a double-quoted string that, when unquoted by cp_unquote(), will equal str. The returned string consists of a single double-quoted string, and in particular is never empty.

Invariant:

cp_quote(str) != "" && cp_unquote(cp_quote(str)) == str

void cp_argvec	(	const String &	str,
		Vector< String > &	conf
	)

Separate a configuration string into arguments at commas.

Parameters:

	str	configuration string
[out]	conf	arguments

The configuration string is broken into arguments at unquoted commas. Each argument is passed through cp_uncomment(), then appended to conf. If the final argument is empty, it is ignored. For example:

 cp_argvec("a, b, c", v)            appends  "a", "b", "c"
 cp_argvec("  a /*?*/ b,  c, ", v)  appends  "a b", "c"
 cp_argvec("\"x, y\" // ?", v)      appends  "\"x, y\""

String cp_unargvec

(

const Vector< String > &

conf

)

Join the strings of conf with commas and return the result.

This function does not quote or otherwise protect the strings in conf. The caller should do that if necessary.

void cp_spacevec	(	const String &	str,
		Vector< String > &	conf
	)

Separate a configuration string into arguments at unquoted spaces.

Parameters:

	str	configuration string
[out]	conf	arguments

The configuration string is broken into arguments at unquoted spaces. Each argument is passed through cp_uncomment(), then appended to conf. If the final argument is empty, it is ignored. For example:

 cp_spacevec("a  b, c", v)            appends  "a", "b,", "c"
 cp_spacevec("  'a /*?*/ b'c", v)     appends  "'a /*?*/ b'c"

String cp_pop_spacevec

(

String &

str

)

Remove and return the first space-separated argument from str.

Parameters:

[in,out]

str

space-separated configuration string

The first space-separated argument in the configuration string is removed and returned. The returned argument is passed through cp_uncomment(). str is set to the remaining portion of the string, with any preceding space removed. If the input string is all spaces and comments, then both the returned string and str will be empty.

String cp_unspacevec	(	const String *	begin,
		const String *	end
	)

Join the strings in [begin, end) with spaces and return the result.

Parameters:

	begin	first string in range
	end	one past last string in range

This function does not quote or otherwise protect the strings in [begin, end). The caller should do that if necessary.

See also:

cp_unspacevec(const Vector<String> &) <