Fast Text Scanning

Text scanning utility. More...

Data Structures
struct	pj_scanner
struct	pj_scan_state

Typedefs
typedef void(*	pj_syn_err_func_ptr) (struct pj_scanner *scanner)

Enumerations
enum	{ PJ_SCAN_AUTOSKIP_WS = 1 , PJ_SCAN_AUTOSKIP_WS_HEADER = 3 , PJ_SCAN_AUTOSKIP_NEWLINE = 4 }

Functions
void	pj_cis_buf_init (pj_cis_buf_t *cs_buf)
pj_status_t	pj_cis_init (pj_cis_buf_t *cs_buf, pj_cis_t *cis)
pj_status_t	pj_cis_dup (pj_cis_t *new_cis, pj_cis_t *existing)
void	pj_cis_add_range (pj_cis_t *cis, int cstart, int cend)
void	pj_cis_add_alpha (pj_cis_t *cis)
void	pj_cis_add_num (pj_cis_t *cis)
void	pj_cis_add_str (pj_cis_t *cis, const char *str)
void	pj_cis_add_cis (pj_cis_t *cis, const pj_cis_t *rhs)
void	pj_cis_del_range (pj_cis_t *cis, int cstart, int cend)
void	pj_cis_del_str (pj_cis_t *cis, const char *str)
void	pj_cis_invert (pj_cis_t *cis)
int	pj_cis_match (const pj_cis_t *cis, pj_uint8_t c)
void	pj_scan_init (pj_scanner *scanner, char *bufstart, pj_size_t buflen, unsigned options, pj_syn_err_func_ptr callback)
void	pj_scan_fini (pj_scanner *scanner)
int	pj_scan_is_eof (const pj_scanner *scanner)
int	pj_scan_peek (pj_scanner *scanner, const pj_cis_t *spec, pj_str_t *out)
int	pj_scan_peek_n (pj_scanner *scanner, pj_size_t len, pj_str_t *out)
int	pj_scan_peek_until (pj_scanner *scanner, const pj_cis_t *spec, pj_str_t *out)
void	pj_scan_get (pj_scanner *scanner, const pj_cis_t *spec, pj_str_t *out)
void	pj_scan_get_unescape (pj_scanner *scanner, const pj_cis_t *spec, pj_str_t *out)
void	pj_scan_get_quote (pj_scanner *scanner, int begin_quote, int end_quote, pj_str_t *out)
void	pj_scan_get_quotes (pj_scanner *scanner, const char *begin_quotes, const char *end_quotes, int qsize, pj_str_t *out)
void	pj_scan_get_n (pj_scanner *scanner, unsigned N, pj_str_t *out)
int	pj_scan_get_char (pj_scanner *scanner)
void	pj_scan_get_until (pj_scanner *scanner, const pj_cis_t *spec, pj_str_t *out)
void	pj_scan_get_until_ch (pj_scanner *scanner, int until_char, pj_str_t *out)
void	pj_scan_get_until_chr (pj_scanner *scanner, const char *until_spec, pj_str_t *out)
void	pj_scan_advance_n (pj_scanner *scanner, unsigned N, pj_bool_t skip)
int	pj_scan_strcmp (pj_scanner *scanner, const char *s, int len)
int	pj_scan_stricmp (pj_scanner *scanner, const char *s, int len)
int	pj_scan_stricmp_alnum (pj_scanner *scanner, const char *s, int len)
void	pj_scan_get_newline (pj_scanner *scanner)
void	pj_scan_skip_whitespace (pj_scanner *scanner)
void	pj_scan_skip_line (pj_scanner *scanner)
void	pj_scan_save_state (const pj_scanner *scanner, pj_scan_state *state)
void	pj_scan_restore_state (pj_scanner *scanner, pj_scan_state *state)
int	pj_scan_get_col (const pj_scanner *scanner)

Detailed Description

Text scanning utility.

This module describes a fast text scanning functions.

Typedef Documentation

pj_syn_err_func_ptr

typedef void(* pj_syn_err_func_ptr) (struct pj_scanner *scanner)

The callback function type to be called by the scanner when it encounters syntax error.

Parameters

scanner

The scanner instance that calls the callback .

Enumeration Type Documentation

anonymous enum

anonymous enum

Flags for scanner.

Enumerator
PJ_SCAN_AUTOSKIP_WS	This flags specifies that the scanner should automatically skip whitespaces
PJ_SCAN_AUTOSKIP_WS_HEADER	This flags specifies that the scanner should automatically skip SIP header continuation. This flag implies PJ_SCAN_AUTOSKIP_WS.
PJ_SCAN_AUTOSKIP_NEWLINE	Auto-skip new lines.

Function Documentation

pj_cis_add_alpha()

void pj_cis_add_alpha

(

pj_cis_t *

cis

)

Add alphabetic characters to the specification.

Parameters

cis	The scanner character specification.

pj_cis_add_cis()

void pj_cis_add_cis	(	pj_cis_t *	cis,
		const pj_cis_t *	rhs
	)

Add specification from another specification.

Parameters

cis	The specification is to be set.
rhs	The specification to be copied.

pj_cis_add_num()

void pj_cis_add_num

(

pj_cis_t *

cis

)

Add numeric characters to the specification.

Parameters

cis	The scanner character specification.

pj_cis_add_range()

void pj_cis_add_range	(	pj_cis_t *	cis,
		int	cstart,
		int	cend
	)

Add the characters in the specified range '[cstart, cend)' to the specification (the last character itself ('cend') is not added).

Parameters

cis	The scanner character specification.
cstart	The first character in the range.
cend	The next character after the last character in the range.

pj_cis_add_str()

void pj_cis_add_str	(	pj_cis_t *	cis,
		const char *	str
	)

Add the characters in the string to the specification.

Parameters

cis	The scanner character specification.
str	The string.

pj_cis_buf_init()

void pj_cis_buf_init

(

pj_cis_buf_t *

cs_buf

)

Initialize scanner input specification buffer.

Parameters

cs_buf

The scanner character specification.

pj_cis_del_range()

void pj_cis_del_range	(	pj_cis_t *	cis,
		int	cstart,
		int	cend
	)

Delete characters in the specified range from the specification.

Parameters

cis	The scanner character specification.
cstart	The first character in the range.
cend	The next character after the last character in the range.

pj_cis_del_str()

void pj_cis_del_str	(	pj_cis_t *	cis,
		const char *	str
	)

Delete characters in the specified string from the specification.

Parameters

cis	The scanner character specification.
str	The string.

pj_cis_dup()

pj_status_t pj_cis_dup	(	pj_cis_t *	new_cis,
		pj_cis_t *	existing
	)

Create a new input specification based on an existing specification.

Parameters

new_cis	The new specification to be initialized.
existing	The existing specification, from which the input bitmask will be copied to the new specification.

Returns

PJ_SUCCESS if new specification has been successfully created, or PJ_ETOOMANY if there are already too many specifications in the buffer.

pj_cis_init()

pj_status_t pj_cis_init	(	pj_cis_buf_t *	cs_buf,
		pj_cis_t *	cis
	)

Create a new input specification.

Parameters

cs_buf	Specification buffer.
cis	Character input specification to be initialized.

Returns

PJ_SUCCESS if new specification has been successfully created, or PJ_ETOOMANY if there are already too many specifications in the buffer.

pj_cis_invert()

void pj_cis_invert

(

pj_cis_t *

cis

)

Invert specification.

Parameters

cis	The scanner character specification.

pj_cis_match()

int pj_cis_match	(	const pj_cis_t *	cis,
		pj_uint8_t	c
	)

Check whether the specified character belongs to the specification.

Parameters

cis	The scanner character specification.
c	The character to check for matching.

Returns

Non-zero if match (not necessarily one).

References PJ_INLINE.

pj_scan_advance_n()

void pj_scan_advance_n	(	pj_scanner *	scanner,
		unsigned	N,
		pj_bool_t	skip
	)

Advance the scanner N characters, and skip whitespace if necessary.

Parameters

scanner	The scanner.
N	Number of characters to skip.
skip	Flag to specify whether whitespace should be skipped after skipping the characters.

pj_scan_fini()

void pj_scan_fini

(

pj_scanner *

scanner

)

Call this function when application has finished using the scanner.

Parameters

scanner

The scanner.

pj_scan_get()

void pj_scan_get	(	pj_scanner *	scanner,
		const pj_cis_t *	spec,
		pj_str_t *	out
	)

Get characters from the buffer according to the spec, and return them in out parameter. The scanner will attempt to get as many characters as possible as long as the spec matches. If the first character doesn't match the spec, or scanner is already in EOF when this function is called, an exception will be thrown.

Parameters

scanner	The scanner.
spec	The spec to match input string.
out	String to store the result.

pj_scan_get_char()

int pj_scan_get_char

(

pj_scanner *

scanner

)

Get one character from the scanner.

Parameters

scanner

The scanner.

Returns

The character.

pj_scan_get_col()

int pj_scan_get_col

(

const pj_scanner *

scanner

)

Get current column position.

Parameters

scanner

The scanner.

Returns

The column position.

References pj_scanner::curptr, PJ_INLINE, and pj_scanner::start_line.

pj_scan_get_n()

void pj_scan_get_n	(	pj_scanner *	scanner,
		unsigned	N,
		pj_str_t *	out
	)

Get N characters from the scanner.

Parameters

scanner	The scanner.
N	Number of characters to get.
out	String to store the result.

pj_scan_get_newline()

void pj_scan_get_newline

(

pj_scanner *

scanner

)

Get a newline from the scanner. A newline is defined as '\n', or '\r', or "\\r\\n". If current input is not newline, syntax error will be thrown.

Parameters

scanner

The scanner.

pj_scan_get_quote()

void pj_scan_get_quote	(	pj_scanner *	scanner,
		int	begin_quote,
		int	end_quote,
		pj_str_t *	out
	)

Get characters between quotes. If current input doesn't match begin_quote, syntax error will be thrown. Note that the resulting string will contain the enclosing quote.

Parameters

scanner	The scanner.
begin_quote	The character to begin the quote.
end_quote	The character to end the quote.
out	String to store the result.

pj_scan_get_quotes()

void pj_scan_get_quotes	(	pj_scanner *	scanner,
		const char *	begin_quotes,
		const char *	end_quotes,
		int	qsize,
		pj_str_t *	out
	)

Get characters between quotes. If current input doesn't match begin_quote, syntax error will be thrown. Note that the resulting string will contain the enclosing quote.

Parameters

scanner	The scanner.
begin_quotes	The character array to begin the quotes. For example, the two characters " and '. @param end_quotes The character array to end the quotes. The position found in the begin_quotes array will be used to match the end quotes. So if the begin_quotes was the array of "'< the end_quotes should be "'>. If begin_array matched the ' then the end_quotes will look for ' to match at the end.
qsize	The size of the begin_quotes and end_quotes arrays.
out	String to store the result.

pj_scan_get_unescape()

void pj_scan_get_unescape	(	pj_scanner *	scanner,
		const pj_cis_t *	spec,
		pj_str_t *	out
	)

Just like pj_scan_get(), but additionally performs unescaping when escaped ('') character is found. The input spec MUST NOT contain the specification for '' characted.

Parameters

scanner	The scanner.
spec	The spec to match input string.
out	String to store the result.

pj_scan_get_until()

void pj_scan_get_until	(	pj_scanner *	scanner,
		const pj_cis_t *	spec,
		pj_str_t *	out
	)

Get characters from the scanner and move the scanner position until the current character matches the spec.

Parameters

scanner	The scanner.
spec	Get until the input match this spec.
out	String to store the result.

pj_scan_get_until_ch()

void pj_scan_get_until_ch	(	pj_scanner *	scanner,
		int	until_char,
		pj_str_t *	out
	)

Get characters from the scanner and move the scanner position until the current character matches until_char.

Parameters

scanner	The scanner.
until_char	Get until the input match this character.
out	String to store the result.

pj_scan_get_until_chr()

void pj_scan_get_until_chr	(	pj_scanner *	scanner,
		const char *	until_spec,
		pj_str_t *	out
	)

Get characters from the scanner and move the scanner position until the current character matches until_char.

Parameters

scanner	The scanner.
until_spec	Get until the input match any of these characters.
out	String to store the result.

pj_scan_init()

void pj_scan_init	(	pj_scanner *	scanner,
		char *	bufstart,
		pj_size_t	buflen,
		unsigned	options,
		pj_syn_err_func_ptr	callback
	)

Initialize the scanner. Note that the input string buffer MUST be NULL terminated and have length at least buflen+1 (buflen MUST NOT include the NULL terminator).

Parameters

scanner	The scanner to be initialized.
bufstart	The input buffer to scan, which must be NULL terminated.
buflen	The length of the input buffer, which normally is strlen(bufstart), hence not counting the NULL terminator.
options	Zero, or combination of PJ_SCAN_AUTOSKIP_WS or PJ_SCAN_AUTOSKIP_WS_HEADER
callback	Callback to be called when the scanner encounters syntax error condition.

pj_scan_is_eof()

int pj_scan_is_eof

(

const pj_scanner *

scanner

)

Determine whether the EOF condition for the scanner has been met.

Parameters

scanner

The scanner.

Returns

Non-zero if scanner is EOF.

References pj_scanner::curptr, pj_scanner::end, and PJ_INLINE.

pj_scan_peek()

int pj_scan_peek	(	pj_scanner *	scanner,
		const pj_cis_t *	spec,
		pj_str_t *	out
	)

Peek strings in current position according to parameter spec, and return the strings in parameter out. The current scanner position will not be moved. If the scanner is already in EOF state, syntax error callback will be called thrown.

Parameters

scanner	The scanner.
spec	The spec to match input string.
out	String to store the result.

Returns

the character right after the peek-ed position or zero if there's no more characters.

pj_scan_peek_n()

int pj_scan_peek_n	(	pj_scanner *	scanner,
		pj_size_t	len,
		pj_str_t *	out
	)

Peek len characters in current position, and return them in out parameter. Note that whitespaces or newlines will be returned as it is, regardless of PJ_SCAN_AUTOSKIP_WS settings. If the character left is less than len, syntax error callback will be called.

Parameters

scanner	The scanner.
len	Length to peek.
out	String to store the result.

Returns

the character right after the peek-ed position or zero if there's no more characters.

pj_scan_peek_until()

int pj_scan_peek_until	(	pj_scanner *	scanner,
		const pj_cis_t *	spec,
		pj_str_t *	out
	)

Peek strings in current position until spec is matched, and return the strings in parameter out. The current scanner position will not be moved. If the scanner is already in EOF state, syntax error callback will be called.

Parameters

scanner	The scanner.
spec	The peeking will stop when the input match this spec.
out	String to store the result.

Returns

the character right after the peek-ed position.

pj_scan_restore_state()

void pj_scan_restore_state	(	pj_scanner *	scanner,
		pj_scan_state *	state
	)

Restore the full scanner state. Note that this would not restore the string if application has modified it. This will only restore the scanner scanning position.

Parameters

scanner	The scanner.
state	State of the scanner.

pj_scan_save_state()

void pj_scan_save_state	(	const pj_scanner *	scanner,
		pj_scan_state *	state
	)

Save the full scanner state.

Parameters

scanner	The scanner.
state	Variable to store scanner's state.

pj_scan_skip_line()

void pj_scan_skip_line

(

pj_scanner *

scanner

)

Skip current line.

Parameters

scanner

The scanner.

pj_scan_skip_whitespace()

void pj_scan_skip_whitespace

(

pj_scanner *

scanner

)

Manually skip whitespaces according to flag that was specified when the scanner was initialized.

Parameters

scanner

The scanner.

pj_scan_strcmp()

int pj_scan_strcmp	(	pj_scanner *	scanner,
		const char *	s,
		int	len
	)

Compare string in current position with the specified string.

Parameters

scanner	The scanner.
s	The string to compare with.
len	Length of the string to compare.

Returns

zero, <0, or >0 (just like strcmp()).

pj_scan_stricmp()

int pj_scan_stricmp	(	pj_scanner *	scanner,
		const char *	s,
		int	len
	)

Case-less string comparison of current position with the specified string.

Parameters

scanner	The scanner.
s	The string to compare with.
len	Length of the string to compare with.

Returns

zero, <0, or >0 (just like strcmp()).

pj_scan_stricmp_alnum()

int pj_scan_stricmp_alnum	(	pj_scanner *	scanner,
		const char *	s,
		int	len
	)

Perform case insensitive string comparison of string in current position, knowing that the string to compare only consists of alphanumeric characters.

Note that unlike pj_scan_stricmp, this function can only return zero or -1.

Parameters

scanner	The scanner.
s	The string to compare with.
len	Length of the string to compare with.

Returns

zero if equal or -1.

See also

strnicmp_alnum, pj_stricmp_alnum