syntax-tree.h File Reference

#include <stdio.h>
#include <inttypes.h>
#include <wsutil/ws_assert.h>
#include <wsutil/wslog.h>
#include <epan/ftypes/ftypes.h>
#include "dfilter-loc.h"

Go to the source code of this file.

Classes
struct	sttype_t
	Describes a syntax tree node type, including its lifecycle and serialization callbacks. More...
struct	stnode
	A single node instance in the display filter syntax tree. More...

Macros
#define	ASSERT_STTYPE_NOT_REACHED(st)    ws_error("Invalid syntax node type '%s'.", sttype_name(st))
#define	ASSERT_STNODE_OP_NOT_REACHED(op)    ws_error("Invalid stnode op '%s'.", stnode_op_name(op))
#define	STFLAG_UNPARSED   (1 << 0)
	Lexical value is ambiguous and may represent either a protocol field or a literal value.
#define	stnode_todisplay(node)   stnode_tostr(node, true)
	Convert a syntax tree node to a printable string.
#define	stnode_todebug(node)   stnode_tostr(node, false)
	Convert a syntax tree node to a debug string.
#define	log_node(node)   (void)0
#define	log_test(node)   (void)0
#define	LOG_NODE(node)   (void)0
#define	ws_assert_magic(obj, mnum)   (void)0

Typedefs
typedef void *(*	STTypeNewFunc) (void *data)
	Allocates and initializes type-specific data for a syntax tree node.
typedef void *(*	STTypeDupFunc) (const void *data)
	Performs a deep copy of type-specific node data.
typedef void(*	STTypeFreeFunc) (void *data)
	Releases type-specific data associated with a syntax tree node.
typedef char *(*	STTypeToStrFunc) (const void *data, bool pretty)
	Converts type-specific node data to a human-readable string.
typedef struct stnode	stnode_t
	A single node instance in the display filter syntax tree.

Enumerations
enum	sttype_id_t {   STTYPE_UNINITIALIZED , STTYPE_TEST , STTYPE_UNPARSED , STTYPE_LITERAL ,   STTYPE_REFERENCE , STTYPE_STRING , STTYPE_CHARCONST , STTYPE_NUMBER ,   STTYPE_FIELD , STTYPE_FVALUE , STTYPE_SLICE , STTYPE_FUNCTION ,   STTYPE_SET , STTYPE_PCRE , STTYPE_ARITHMETIC , STTYPE_NUM_TYPES }
	Type identifier tags for syntax tree nodes in the display filter compiler. More...
enum	stnumber_t { STNUM_NONE = 0 , STNUM_INTEGER , STNUM_UNSIGNED , STNUM_FLOAT }
	Numeric sub-type tag for STTYPE_NUMBER nodes. More...
enum	stnode_op_t {   STNODE_OP_UNINITIALIZED , STNODE_OP_NOT , STNODE_OP_AND , STNODE_OP_OR ,   STNODE_OP_ALL_EQ , STNODE_OP_ANY_EQ , STNODE_OP_ALL_NE , STNODE_OP_ANY_NE ,   STNODE_OP_GT , STNODE_OP_GE , STNODE_OP_LT , STNODE_OP_LE ,   STNODE_OP_CONTAINS , STNODE_OP_MATCHES , STNODE_OP_IN , STNODE_OP_NOT_IN ,   STNODE_OP_BITWISE_AND , STNODE_OP_UNARY_MINUS , STNODE_OP_ADD , STNODE_OP_SUBTRACT ,   STNODE_OP_MULTIPLY , STNODE_OP_DIVIDE , STNODE_OP_MODULO }
	Operator types for test and arithmetic syntax tree nodes. More...
enum	stmatch_t { STNODE_MATCH_DEF , STNODE_MATCH_ANY , STNODE_MATCH_ALL }
	Quantifier controlling how many field values must satisfy a match condition. More...

Functions
void	sttype_register_field (void)
	Register the field type in the syntax tree type system.
void	sttype_register_function (void)
	Register the function type in the syntax tree type system.
void	sttype_register_number (void)
	Register the number type in the syntax tree type system.
void	sttype_register_pointer (void)
	Register the pointer type in the syntax tree type system.
void	sttype_register_set (void)
	Register the set type in the syntax tree type system.
void	sttype_register_slice (void)
	Register the slice type in the syntax tree type system.
void	sttype_register_string (void)
	Register the string type in the syntax tree type system.
void	sttype_register_opers (void)
	Register the operator types in the syntax tree type system.
void	sttype_init (void)
	Initialize the syntax tree types.
void	sttype_cleanup (void)
	Cleans up resources associated with the syntax tree types.
void	sttype_register (sttype_t *type)
	Registers a syntax tree type.
WS_DLL_PUBLIC const char *	sttype_name (const sttype_id_t type)
	Get the name of a syntax tree type.
WS_DLL_PUBLIC const char *	stnode_op_name (const stnode_op_t op)
	Get the name of an operation based on its type.
WS_DLL_PUBLIC stnode_t *	stnode_new (sttype_id_t type_id, void *data, char *token, df_loc_t loc)
	Creates a new syntax tree node with the given type ID, data, token, and location.
WS_DLL_PUBLIC stnode_t *	stnode_new_empty (sttype_id_t type_id)
	Creates a new empty syntax tree node.
WS_DLL_PUBLIC stnode_t *	stnode_dup (const stnode_t *org)
	Duplicates a syntax tree node.
WS_DLL_PUBLIC void	stnode_clear (stnode_t *node)
	Clears the contents of a syntax tree node.
WS_DLL_PUBLIC void	stnode_init (stnode_t *node, sttype_id_t type_id, void *data, char *token, df_loc_t loc)
	Initialize a syntax tree node.
WS_DLL_PUBLIC void	stnode_replace (stnode_t *node, sttype_id_t type_id, void *data)
	Replaces a node in the syntax tree with a new type and data.
WS_DLL_PUBLIC void	stnode_mutate (stnode_t *node, sttype_id_t type_id)
	Mutates the type of a syntax tree node.
WS_DLL_PUBLIC void	stnode_free (stnode_t *node)
	Frees a syntax tree node.
WS_DLL_PUBLIC const char *	stnode_type_name (const stnode_t *node)
	Get the type name of a syntax tree node.
WS_DLL_PUBLIC sttype_id_t	stnode_type_id (const stnode_t *node)
	Retrieves the type ID of a syntax tree node.
WS_DLL_PUBLIC void *	stnode_data (stnode_t *node)
	Retrieves the data associated with a syntax tree node.
WS_DLL_PUBLIC GString *	stnode_string (stnode_t *node)
	Retrieves the string data from a syntax tree node.
WS_DLL_PUBLIC void *	stnode_steal_data (stnode_t *node)
	Steals and returns the data associated with a syntax tree node.
WS_DLL_PUBLIC const char *	stnode_token (const stnode_t *node)
	Retrieves the token representation of a syntax tree node.
WS_DLL_PUBLIC df_loc_t	stnode_location (const stnode_t *node)
	Get the location of a syntax tree node.
WS_DLL_PUBLIC void	stnode_set_location (stnode_t *node, df_loc_t loc)
	Set the location for a syntax tree node.
WS_DLL_PUBLIC bool	stnode_get_flags (stnode_t *node, uint16_t flags)
	Get flags from a syntax tree node.
WS_DLL_PUBLIC void	stnode_set_flags (stnode_t *node, uint16_t flags)
	Sets flags for a syntax tree node.
void	stnode_merge_location (stnode_t *dst, stnode_t *n1, stnode_t *n2)
	Merges location information from two syntax tree nodes into a destination node.
WS_DLL_PUBLIC const char *	stnode_tostr (stnode_t *node, bool pretty)
	Convert a syntax tree node to a string representation.
void	log_node_full (enum ws_log_level level, const char *file, int line, const char *func, stnode_t *node, const char *msg)
	Logs a full message with detailed information about a syntax tree node.
void	log_test_full (enum ws_log_level level, const char *file, int line, const char *func, stnode_t *node, const char *msg)
	Logs a full test message for a syntax tree node.
char *	dump_syntax_tree_str (stnode_t *root)
	Dumps a syntax tree to a string.
void	log_syntax_tree (enum ws_log_level level, stnode_t *root, const char *msg, char **cache_ptr)
	Logs a syntax tree with an optional message and caches the result.

Macro Definition Documentation

stnode_todebug

#define stnode_todebug

(

node

)

stnode_tostr(node, false)

Convert a syntax tree node to a debug string.

This function returns a string representation of the syntax tree node that is suitable for debugging purposes.

Parameters

node	The syntax tree node to convert.

Returns

A string representing the syntax tree node for debugging.

stnode_todisplay

#define stnode_todisplay

(

node

)

stnode_tostr(node, true)

Convert a syntax tree node to a printable string.

This function returns a string representation of the syntax tree node that is suitable for display purposes.

Parameters

node	The syntax tree node to convert.

Returns

A string representing the syntax tree node for display.

Typedef Documentation

STTypeDupFunc

typedef void *(* STTypeDupFunc) (const void *data)

Performs a deep copy of type-specific node data.

Parameters

data	Pointer to the source type data to duplicate.

Returns

Pointer to the newly allocated duplicate, or NULL.

STTypeFreeFunc

typedef void(* STTypeFreeFunc) (void *data)

Releases type-specific data associated with a syntax tree node.

Parameters

data	Pointer to the type data to free.

STTypeNewFunc

typedef void *(* STTypeNewFunc) (void *data)

Allocates and initializes type-specific data for a syntax tree node.

Parameters

data	Pointer to initialization data passed to the constructor.

Returns

Pointer to the newly allocated type data, or NULL.

STTypeToStrFunc

typedef char *(* STTypeToStrFunc) (const void *data, bool pretty)

Converts type-specific node data to a human-readable string.

Parameters

data	Pointer to the type data to render.
pretty	If true, produce a display-friendly representation; otherwise a debug form.

Returns

Newly allocated string representation; caller is responsible for freeing it.

Enumeration Type Documentation

stmatch_t

enum stmatch_t

Quantifier controlling how many field values must satisfy a match condition.

Enumerator
STNODE_MATCH_DEF	Default quantifier; behavior determined by operator context
STNODE_MATCH_ANY	Match succeeds if any field value satisfies the condition
STNODE_MATCH_ALL	Match succeeds only if all field values satisfy the condition

stnode_op_t

enum stnode_op_t

Operator types for test and arithmetic syntax tree nodes.

Enumerator
STNODE_OP_UNINITIALIZED	Operator has not been set
STNODE_OP_NOT	Logical NOT
STNODE_OP_AND	Logical AND
STNODE_OP_OR	Logical OR
STNODE_OP_ALL_EQ	All-quantified equality (all values ==)
STNODE_OP_ANY_EQ	Any-quantified equality (any value ==)
STNODE_OP_ALL_NE	All-quantified inequality (all values !=)
STNODE_OP_ANY_NE	Any-quantified inequality (any value !=)
STNODE_OP_GT	Greater-than comparison
STNODE_OP_GE	Greater-than-or-equal comparison
STNODE_OP_LT	Less-than comparison
STNODE_OP_LE	Less-than-or-equal comparison
STNODE_OP_CONTAINS	Substring/value containment test
STNODE_OP_MATCHES	PCRE regular expression match
STNODE_OP_IN	Set membership test
STNODE_OP_NOT_IN	Set non-membership test
STNODE_OP_BITWISE_AND	Bitwise AND of two values
STNODE_OP_UNARY_MINUS	Arithmetic unary negation
STNODE_OP_ADD	Arithmetic addition
STNODE_OP_SUBTRACT	Arithmetic subtraction
STNODE_OP_MULTIPLY	Arithmetic multiplication
STNODE_OP_DIVIDE	Arithmetic division
STNODE_OP_MODULO	Arithmetic modulo

stnumber_t

enum stnumber_t

Numeric sub-type tag for STTYPE_NUMBER nodes.

Enumerator
STNUM_NONE	No numeric value; uninitialized
STNUM_INTEGER	Signed integer constant
STNUM_UNSIGNED	Unsigned integer constant
STNUM_FLOAT	Floating-point constant

sttype_id_t

enum sttype_id_t

Type identifier tags for syntax tree nodes in the display filter compiler.

Enumerator
STTYPE_UNINITIALIZED	Node has not been assigned a type yet
STTYPE_TEST	Node represents a boolean test expression
STTYPE_UNPARSED	Raw lexical token; must be resolved to a literal or field
STTYPE_LITERAL	Node holds a resolved literal value
STTYPE_REFERENCE	Node holds a field reference (e.g., ${field})
STTYPE_STRING	Node holds a quoted string constant
STTYPE_CHARCONST	Node holds a character constant
STTYPE_NUMBER	Node holds a numeric constant
STTYPE_FIELD	Node refers to a protocol header field (hfinfo)
STTYPE_FVALUE	Node holds a typed field value (fvalue_t)
STTYPE_SLICE	Node represents a byte-range slice expression
STTYPE_FUNCTION	Node represents a display filter function call
STTYPE_SET	Node represents a set literal for use with 'in' operator
STTYPE_PCRE	Node holds a compiled PCRE regular expression
STTYPE_ARITHMETIC	Node represents an arithmetic sub-expression
STTYPE_NUM_TYPES	Sentinel value; total count of defined type IDs

Function Documentation

dump_syntax_tree_str()

char * dump_syntax_tree_str

(

stnode_t *

root

)

Dumps a syntax tree to a string.

Parameters

root	Pointer to the root node of the syntax tree.

Returns

A string representation of the syntax tree.

log_node_full()

void log_node_full	(	enum ws_log_level	level,
		const char *	file,
		int	line,
		const char *	func,
		stnode_t *	node,
		const char *	msg
	)

Logs a full message with detailed information about a syntax tree node.

Parameters

level	The log level for this message.
file	The source file where the function is called.
line	The line number in the source file where the function is called.
func	The name of the function calling this one.
node	The syntax tree node to be logged.
msg	A custom message to accompany the log entry.

log_syntax_tree()

void log_syntax_tree	(	enum ws_log_level	level,
		stnode_t *	root,
		const char *	msg,
		char **	cache_ptr
	)

Logs a syntax tree with an optional message and caches the result.

Parameters

level	The log level to use for logging.
root	The root node of the syntax tree to log.
msg	An optional message to include in the log entry.
cache_ptr	A pointer to a char pointer where the logged string will be cached, or NULL if not needed.

log_test_full()

void log_test_full	(	enum ws_log_level	level,
		const char *	file,
		int	line,
		const char *	func,
		stnode_t *	node,
		const char *	msg
	)

Logs a full test message for a syntax tree node.

Parameters

level	The log level to use.
file	The source file name where the function is called.
line	The line number in the source file where the function is called.
func	The function name where the function is called.
node	The syntax tree node to log.
msg	A message describing the test.

stnode_clear()

WS_DLL_PUBLIC void stnode_clear

(

stnode_t *

node

)

Clears the contents of a syntax tree node.

This function releases any resources associated with the node and resets its fields to their initial state.

Parameters

node	Pointer to the syntax tree node to be cleared.

stnode_data()

WS_DLL_PUBLIC void * stnode_data

(

stnode_t *

node

)

Retrieves the data associated with a syntax tree node.

Parameters

node	Pointer to the syntax tree node.

Returns

Pointer to the data stored in the node.

stnode_dup()

WS_DLL_PUBLIC stnode_t * stnode_dup

(

const stnode_t *

org

)

Duplicates a syntax tree node.

Creates a new syntax tree node that is a deep copy of the given node.

Parameters

org	The original syntax tree node to duplicate.

Returns

A pointer to the newly created duplicated node.

stnode_free()

WS_DLL_PUBLIC void stnode_free

(

stnode_t *

node

)

Frees a syntax tree node.

Parameters

node	Pointer to the syntax tree node to be freed.

stnode_get_flags()

WS_DLL_PUBLIC bool stnode_get_flags	(	stnode_t *	node,
		uint16_t	flags
	)

Get flags from a syntax tree node.

Parameters

node	Pointer to the syntax tree node.
flags	Flags to retrieve.

Returns

uint16_t The intersection of the node's flags and the requested flags.

stnode_init()

WS_DLL_PUBLIC void stnode_init	(	stnode_t *	node,
		sttype_id_t	type_id,
		void *	data,
		char *	token,
		df_loc_t	loc
	)

Initialize a syntax tree node.

Parameters

node	Pointer to the syntax tree node to initialize.
type_id	Type identifier for the node.
data	Data associated with the node.
token	Token string representing the node.
loc	Location information for the node.

stnode_location()

WS_DLL_PUBLIC df_loc_t stnode_location

(

const stnode_t *

node

)

Get the location of a syntax tree node.

Parameters

node	The syntax tree node to get the location from.

Returns

df_loc_t The location of the node.

stnode_merge_location()

void stnode_merge_location	(	stnode_t *	dst,
		stnode_t *	n1,
		stnode_t *	n2
	)

Merges location information from two syntax tree nodes into a destination node.

This function updates the location of the destination node to encompass the locations of both input nodes.

Parameters

dst	Pointer to the destination syntax tree node where the merged location will be stored.
n1	Pointer to the first source syntax tree node.
n2	Pointer to the second source syntax tree node.

stnode_mutate()

WS_DLL_PUBLIC void stnode_mutate	(	stnode_t *	node,
		sttype_id_t	type_id
	)

Mutates the type of a syntax tree node.

Parameters

node	Pointer to the syntax tree node to be mutated.
type_id	The new type ID for the node.

stnode_new()

WS_DLL_PUBLIC stnode_t * stnode_new	(	sttype_id_t	type_id,
		void *	data,
		char *	token,
		df_loc_t	loc
	)

Creates a new syntax tree node with the given type ID, data, token, and location.

Parameters

type_id	The type ID of the node.
data	The data associated with the node.
token	The token representing the node.
loc	The location information for the node.

Returns

A pointer to the newly created syntax tree node.

stnode_new_empty()

WS_DLL_PUBLIC stnode_t * stnode_new_empty

(

sttype_id_t

type_id

)

Creates a new empty syntax tree node.

Parameters

type_id

The type identifier for the new node.

Returns

A pointer to the newly created empty syntax tree node.

stnode_op_name()

WS_DLL_PUBLIC const char * stnode_op_name

(

const stnode_op_t

op

)

Get the name of an operation based on its type.

Parameters

op	The operation type to get the name for.

Returns

const char* The name of the operation or "(null)" if unknown.

stnode_replace()

WS_DLL_PUBLIC void stnode_replace	(	stnode_t *	node,
		sttype_id_t	type_id,
		void *	data
	)

Replaces a node in the syntax tree with a new type and data.

Parameters

node	Pointer to the node to be replaced.
type_id	The new type ID for the node.
data	Pointer to the new data for the node.

stnode_set_flags()

WS_DLL_PUBLIC void stnode_set_flags	(	stnode_t *	node,
		uint16_t	flags
	)

Sets flags for a syntax tree node.

Parameters

node	Pointer to the syntax tree node.
flags	Flags to be set.

stnode_set_location()

WS_DLL_PUBLIC void stnode_set_location	(	stnode_t *	node,
		df_loc_t	loc
	)

Set the location for a syntax tree node.

Parameters

node	The syntax tree node to set the location for.
loc	The new location to set.

stnode_steal_data()

WS_DLL_PUBLIC void * stnode_steal_data

(

stnode_t *

node

)

Steals and returns the data associated with a syntax tree node.

Parameters

node	The syntax tree node from which to steal the data.

Returns

The stolen data, or NULL if no data was present.

stnode_string()

WS_DLL_PUBLIC GString * stnode_string

(

stnode_t *

node

)

Retrieves the string data from a syntax tree node.

Parameters

node	Pointer to the syntax tree node.

Returns

The string data stored in the node.

stnode_token()

WS_DLL_PUBLIC const char * stnode_token

(

const stnode_t *

node

)

Retrieves the token representation of a syntax tree node.

Parameters

node	Pointer to the syntax tree node.

Returns

The token representation of the node.

stnode_tostr()

WS_DLL_PUBLIC const char * stnode_tostr	(	stnode_t *	node,
		bool	pretty
	)

Convert a syntax tree node to a string representation.

Parameters

node	The syntax tree node to convert.
pretty	If true, produce a pretty-printed string; otherwise, produce a debug-friendly string.

Returns

A string representing the syntax tree node.

stnode_type_id()

WS_DLL_PUBLIC sttype_id_t stnode_type_id

(

const stnode_t *

node

)

Retrieves the type ID of a syntax tree node.

Parameters

node	Pointer to the syntax tree node.

Returns

The type ID of the node, or STTYPE_UNINITIALIZED if not set.

stnode_type_name()

WS_DLL_PUBLIC const char * stnode_type_name

(

const stnode_t *

node

)

Get the type name of a syntax tree node.

Parameters

node	Pointer to the syntax tree node.

Returns

The type name of the node.

sttype_cleanup()

void sttype_cleanup

(

void

)

Cleans up resources associated with the syntax tree types.

This function is responsible for releasing any resources that were allocated during the registration of various syntax tree types, such as strings, literals, and unparsed types.

sttype_init()

void sttype_init

(

void

)

Initialize the syntax tree types.

This function initializes the various types used in the syntax tree, including fvalue, pcre, and charconst types.

sttype_name()

WS_DLL_PUBLIC const char * sttype_name

(

const sttype_id_t

type

)

Get the name of a syntax tree type.

Parameters

type	The syntax tree type ID.

Returns

The name of the syntax tree type, or "(unknown sttype)" if the type is not recognized.

sttype_register()

void sttype_register

(

sttype_t *

type

)

Registers a syntax tree type.

This function adds a new syntax tree type to the system, allowing it to be used in the construction of syntax trees.

Parameters

type	The syntax tree type to register.