Home --> Documentations --> PJLIB-UTIL Reference

Data Structures | Typedefs | Enumerations | Functions

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

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
scannerThe scanner instance that calls the callback .

Enumeration Type Documentation

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

void pj_cis_add_alpha ( pj_cis_t cis)

Add alphabetic characters to the specification.

Parameters
cisThe scanner character specification.
void pj_cis_add_cis ( pj_cis_t cis,
const pj_cis_t rhs 
)

Add specification from another specification.

Parameters
cisThe specification is to be set.
rhsThe specification to be copied.
void pj_cis_add_num ( pj_cis_t cis)

Add numeric characters to the specification.

Parameters
cisThe scanner character specification.
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
cisThe scanner character specification.
cstartThe first character in the range.
cendThe next character after the last character in the range.
void pj_cis_add_str ( pj_cis_t cis,
const char *  str 
)

Add the characters in the string to the specification.

Parameters
cisThe scanner character specification.
strThe string.
void pj_cis_buf_init ( pj_cis_buf_t cs_buf)

Initialize scanner input specification buffer.

Parameters
cs_bufThe scanner character specification.
void pj_cis_del_range ( pj_cis_t cis,
int  cstart,
int  cend 
)

Delete characters in the specified range from the specification.

Parameters
cisThe scanner character specification.
cstartThe first character in the range.
cendThe next character after the last character in the range.
void pj_cis_del_str ( pj_cis_t cis,
const char *  str 
)

Delete characters in the specified string from the specification.

Parameters
cisThe scanner character specification.
strThe string.
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_cisThe new specification to be initialized.
existingThe 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_status_t pj_cis_init ( pj_cis_buf_t cs_buf,
pj_cis_t cis 
)

Create a new input specification.

Parameters
cs_bufSpecification buffer.
cisCharacter 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.
void pj_cis_invert ( pj_cis_t cis)

Invert specification.

Parameters
cisThe scanner character specification.
int pj_cis_match ( const pj_cis_t cis,
pj_uint8_t  c 
)

Check whether the specified character belongs to the specification.

Parameters
cisThe scanner character specification.
cThe character to check for matching.
Returns
Non-zero if match (not necessarily one).
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
scannerThe scanner.
NNumber of characters to skip.
skipFlag to specify whether whitespace should be skipped after skipping the characters.
void pj_scan_fini ( pj_scanner scanner)

Call this function when application has finished using the scanner.

Parameters
scannerThe scanner.
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
scannerThe scanner.
specThe spec to match input string.
outString to store the result.
int pj_scan_get_char ( pj_scanner scanner)

Get one character from the scanner.

Parameters
scannerThe scanner.
Returns
The character.
int pj_scan_get_col ( const pj_scanner scanner)

Get current column position.

Parameters
scannerThe scanner.
Returns
The column position.
void pj_scan_get_n ( pj_scanner scanner,
unsigned  N,
pj_str_t out 
)

Get N characters from the scanner.

Parameters
scannerThe scanner.
NNumber of characters to get.
outString to store the result.
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
scannerThe scanner.
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
scannerThe scanner.
begin_quoteThe character to begin the quote.
end_quoteThe character to end the quote.
outString to store the result.
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
scannerThe scanner.
begin_quotesThe character array to begin the quotes. For example, the two characters " and '.
end_quotesThe 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.
qsizeThe size of the begin_quotes and end_quotes arrays.
outString to store the result.
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
scannerThe scanner.
specThe spec to match input string.
outString to store the result.
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
scannerThe scanner.
specGet until the input match this spec.
outString to store the result.
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
scannerThe scanner.
until_charGet until the input match this character.
outString to store the result.
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
scannerThe scanner.
until_specGet until the input match any of these characters.
outString to store the result.
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 have length at least buflen+1 because the scanner will NULL terminate the string during initialization.

Parameters
scannerThe scanner to be initialized.
bufstartThe input buffer to scan. Note that buffer[buflen] will be filled with NULL char until scanner is destroyed, so the actual buffer length must be at least buflen+1.
buflenThe length of the input buffer, which normally is strlen(bufstart).
optionsZero, or combination of PJ_SCAN_AUTOSKIP_WS or PJ_SCAN_AUTOSKIP_WS_HEADER
callbackCallback to be called when the scanner encounters syntax error condition.
int pj_scan_is_eof ( const pj_scanner scanner)

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

Parameters
scannerThe scanner.
Returns
Non-zero if scanner is EOF.
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
scannerThe scanner.
specThe spec to match input string.
outString to store the result.
Returns
the character right after the peek-ed position or zero if there's no more characters.
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
scannerThe scanner.
lenLength to peek.
outString to store the result.
Returns
the character right after the peek-ed position or zero if there's no more characters.
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
scannerThe scanner.
specThe peeking will stop when the input match this spec.
outString to store the result.
Returns
the character right after the peek-ed position.
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
scannerThe scanner.
stateState of the scanner.
void pj_scan_save_state ( const pj_scanner scanner,
pj_scan_state state 
)

Save the full scanner state.

Parameters
scannerThe scanner.
stateVariable to store scanner's state.
void pj_scan_skip_line ( pj_scanner scanner)

Skip current line.

Parameters
scannerThe scanner.
void pj_scan_skip_whitespace ( pj_scanner scanner)

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

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

Compare string in current position with the specified string.

Parameters
scannerThe scanner.
sThe string to compare with.
lenLength of the string to compare.
Returns
zero, <0, or >0 (just like strcmp()).
int pj_scan_stricmp ( pj_scanner scanner,
const char *  s,
int  len 
)

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

Parameters
scannerThe scanner.
sThe string to compare with.
lenLength of the string to compare with.
Returns
zero, <0, or >0 (just like strcmp()).
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
scannerThe scanner.
sThe string to compare with.
lenLength of the string to compare with.
Returns
zero if equal or -1.
See also
strnicmp_alnum, pj_stricmp_alnum

 


PJLIB-UTIL Open Source, small footprint, and portable asynchronous/caching DNS resolver, text scanner, STUN client, and XML library
Copyright (C) 2006-2009 Teluu Inc.