Skip to content

Definitions and constants

Jump to bottom
IS4 edited this page Nov 25, 2024 · 7 revisions

Configuration

PP_VERSION

const PP_VERSION = 0x150;

The value that pp_version should return for this version of the API.

PP_SYNTAX

#if defined PP_SYNTAX
#define PP_SYNTAX_AMX_FORKED
#define PP_SYNTAX_@
#define PP_SYNTAX_@@
#define PP_SYNTAX_AWAIT
#define PP_SYNTAX_YIELD
#define PP_SYNTAX_THREADED
#define PP_SYNTAX_FOR_LIST
#define PP_SYNTAX_FOR_MAP
#define PP_SYNTAX_FOR_LINKED_LIST
#define PP_SYNTAX_STRING_OP
#define PP_SYNTAX_GENERIC
#define PP_SYNTAX_AMX_PARALLEL
#endif

PawnPlus contains many extensions for the Pawn syntax. Defining PP_SYNTAX before including the plugin will enable them all.

PP_ALL_TAGS, PP_ADDITIONAL_TAGS 

#if !defined PP_ALL_TAGS
#define PP_ALL_TAGS _,bool,Float,VariantTags,StringTags,List,Map,IterTags,HandleTags,Task
#if defined PP_ADDITIONAL_TAGS
#define AnyTag {PP_ALL_TAGS,PP_ADDITIONAL_TAGS}
#else
#define AnyTag {PP_ALL_TAGS}
#endif
#else
#define AnyTag {PP_ALL_TAGS}
#endif

This is used to control the AnyTag macro which expands to the list of known tags, used in all functions made to support any tag. Define PP_ADDITIONAL_TAGS to add more tags or PP_ALL_TAGS to specify all tags by yourself, but remember that there is a limit on the maximum number of tags a single parameter can have.

error_level

enum error_level
{
    error_message = 0,
    error_warning = 1,
    error_logic = 2,
    error_formal = 3,
    error_none = cellmax,
}

A classification for errors. Only error_logic and error_formal are currently used by natives. Used by pp_error_level, pp_raise_error, and pp_on_error.

locale_category

enum locale_category (<<= 1)
{
    locale_none = 0,
    locale_collate = 1,
    locale_ctype,
    locale_monetary,
    locale_numeric,
    locale_time,
    locale_messages,
    locale_all = -1,
}

Represents a category of operations defined by a locale. Used by pp_locale.

Pawn

filter_type

enum filter_type
{
    filter_in = 0,
    filter_out = 1,
}

Specifies the location of a filter relative to the executed code of a native function. An "in" filter executes before the actual call and can modify the arguments. An "out" filter executes after the actual call and can modify the return value. Used by pawn_add_filter.

handler_flags

enum handler_flags
{
    handler_default = 0,
    handler_return = 1,
    handler_args = 2,
    handler_inverted_return = 4,
}

Used by pawn_register_callback to specify if the handler is able to set a return value, modify the arguments, or whether the result should be bitwise negated.

Tags

tag_uid

const tag_uid:tag_uid_unknown = tag_uid:0;
const tag_uid:tag_uid_cell = tag_uid:1;
const tag_uid:tag_uid_bool = tag_uid:2;
const tag_uid:tag_uid_char = tag_uid:3;
const tag_uid:tag_uid_float = tag_uid:4;
const tag_uid:tag_uid_string = tag_uid:5;
const tag_uid:tag_uid_variant = tag_uid:6;
const tag_uid:tag_uid_list = tag_uid:7;
const tag_uid:tag_uid_map = tag_uid:8;
const tag_uid:tag_uid_iter = tag_uid:9;
const tag_uid:tag_uid_ref = tag_uid:10;
const tag_uid:tag_uid_task = tag_uid:11;
const tag_uid:tag_uid_var = tag_uid:12;
const tag_uid:tag_uid_linked_list = tag_uid:13;
const tag_uid:tag_uid_guard = tag_uid:14;
const tag_uid:tag_uid_callback_handler = tag_uid:15;
const tag_uid:tag_uid_native_hook = tag_uid:16;
const tag_uid:tag_uid_handle = tag_uid:17;
const tag_uid:tag_uid_symbol = tag_uid:18;
const tag_uid:tag_uid_signed = tag_uid:19;
const tag_uid:tag_uid_unsigned = tag_uid:20;

A tag uid is a universal identifier of a tag name, designed to represent a tag in a way that doesn't depend on a particular script. Every newly encountered add is assigned a new tag uid. Some identifiers are fixed and can be used to obtain tags of dynamically produced values.

TAG_EXPORTED

const TAG_EXPORTED = 0x80000000;

A flag that all exported tags should have. Exported tags are those used in a script that are referenced by the tagof operator or used in the exit or sleep statements.

TAG_STRONG

const TAG_STRONG = 0x40000000;

A tag is strong if it begins with an uppercase character. Strong tags cannot be assigned to tagless variables without warnings.

tag_op

enum tag_op
{
    tag_op_add = 1,
    tag_op_sub = 2,
    tag_op_mul = 3,
    tag_op_div = 4,
    tag_op_mod = 5,
    tag_op_neg = 6,
    tag_op_inc = 7,
    tag_op_dec = 8,
    
    tag_op_eq = 10,
    tag_op_neq = 11,
    tag_op_lt = 12,
    tag_op_gt = 13,
    tag_op_lte = 14,
    tag_op_gte = 15,
    tag_op_not = 16,
    
    tag_op_string = 20,
    tag_op_delete = 21,
    tag_op_release = 22,
    tag_op_collect = 23,
    tag_op_copy = 24,
    tag_op_clone = 25,
    tag_op_assign = 26,
    tag_op_init = 27,
    tag_op_hash = 28,
    tag_op_acquire = 29,
    tag_op_handle = 30,
}

All operations recognized by PawnPlus that can be performed on a tagged value.

AMX

fork_level

enum fork_level
{
    fork_exec = 0,
    fork_data = 1,
    fork_machine = 2,
}

An option to amx_fork to specify what should be separated in the fork. fork_exec causes only the necessary registers to be remembered, fork_data will copy the AMX memory, and fork_machines creates a brand new machine, a copy of the original.

AMX_ALL

const Amx:AMX_ALL = Amx:-1;

A special value for amx_call_native and amx_call_public meaning the function should be called in all loaded AMX instances.

AMX_OTHERS

const Amx:AMX_OTHERS = Amx:-2;

A special value for amx_call_native and amx_call_public meaning the function should be called in all loaded AMX instances with the exception of the current one.

amx_err

enum amx_err
{
    amx_err_none = 0,
    amx_err_exit,
    amx_err_assert,
    amx_err_stackerr,
    amx_err_bounds,
    amx_err_memaccess,
    amx_err_invinstr,
    amx_err_stacklow,
    amx_err_heaplow,
    amx_err_callback,
    amx_err_native,
    amx_err_divide,
    amx_err_sleep,
    amx_err_invstate,
    
    amx_err_memory = 16,
    amx_err_format,
    amx_err_version,
    amx_err_notfound,
    amx_err_index,
    amx_err_debug,
    amx_err_init,
    amx_err_userdata,
    amx_err_init_jit,
    amx_err_params,
    amx_err_domain,
    amx_err_general,
}

This enum represents potential error codes raised in AMX.

amx_forked

#define amx_forked(%0) for(new PP@af:_@pp_amx_forked=PP@af:amx_fork(%0);_@pp_amx_forked;_@pp_amx_forked=PP@af:amx_end_fork())

Initiates a forked block, by calling amx_fork at the beginning and amx_end_fork at the end.

This extension is disabled by default. Define PP_SYNTAX or PP_SYNTAX_AMX_FORKED to enable it in your script.

amx_parallel

#define amx_parallel(%0) for(new PP@ap:_@pp_amx_parallel=PP@ap:amx_parallel_begin(%0);_@pp_amx_parallel;_@pp_amx_parallel=PP@ap:amx_parallel_end())

Initiates a parallel block, where the code may be run in parallel with the server, by calling amx_parallel_begin and amx_parallel_end.

amx_buffer_options

enum amx_buffer_options
{
    amx_buffer_default = 0,
    amx_buffer_string_auto_fit = 1,
    amx_buffer_string_set_unpacked = 0b010,
    amx_buffer_string_set_packed = 0b110,
    amx_buffer_string_set_narrow = 0b01000,
    amx_buffer_string_set_wide = 0b11000,
    amx_buffer_string_use_strlen = 0b100000
}

Controls the behaviour of amx_addr, var_addr, and similar functions, when the storage is used as an output string. amx_buffer_string_auto_fit allows resizing the storage automatically for cooperating functions, amx_buffer_string_use_strlen forces the default behaviour or amx_StrLen, counting the actual number of non-NUL characters instead of using the actual length of the string, and the remaining flags override various options for amx_SetString.

Strings

StringTag

#define StringTags String
#define StringTag {StringTags}
#define ConstStringTags ConstString,StringTags
#define ConstStringTag {ConstStringTags}

Always use StringTag or ConstStringTag in a parameter list (if you don't expect a specific type of string) so that it is compatible with future changes. The Const version should be used if the function doesn't modify the string in any way.

STRING_NULL

const String:STRING_NULL = String:0;

STRING_NULL is a special kind of an immutable string. It is a valid string for all functions, but its value cannot be changed. Its value is usually "", but it can also be "\1;" in calls to variadic functions, since most of these crash if an empty string is passed (because amx_StrParam produces a null pointer).

INVALID_CHAR

const INVALID_CHAR = 0xFFFFFF00;

str_getc may return INVALID_CHAR if an invalid index is specified. This value cannot be in any string, since the top 0xFF denoted a packed string, but in that case it would be 3 0xFF characters. Dynamic strings always store cells, not bytes.

str_create_mode

enum str_create_mode
{
    str_preserve = 0,
    str_truncate = 1,
    str_no_nulls = 2
}

Specifies the way a string is constructed in a call to str_new, str_new_arr, or str_new_static. str_preserve keeps the characters exactly as they were read, str_truncate discards any bits outside the 8-bit range, and str_no_nulls transforms all null characters that remain into 0x00FFFF00.

regex_options

enum regex_options (<<= 1)
{
    regex_default = 0,
    regex_basic = 1,
    regex_extended = 2,
    regex_awk = 3,
    regex_grep = 4,
    regex_egrep = 5,
    
    regex_icase = 8,
    regex_nosubs,
    regex_optimize,
    regex_collate,
    
    regex_not_bol = 256,
    regex_not_eol,
    regex_not_bow,
    regex_not_eow,
    regex_any,
    regex_not_null,
    regex_continuous,
    
    regex_no_copy = 65536,
    regex_first_only,
    
    regex_cached = 4194304
}

Options for matching and parsing regex patterns. Refer to syntax_option_type and match_flag_type for more information. regex_cached stores the constructed regex machine in a map based on the pattern and options, for faster execution next time they are used.

@

#define @ str_new_static

@ itself is an invalid symbol, but a valid definition. Sadly, the parentheses are still required, but this nicely complements the ! prefix for packed strings.

This extension is disabled by default. Define PP_SYNTAX or PP_SYNTAX_@ to enable it in your script.

@@

#define @@ str_val

If a lot of conversions happens, you might want to use this extension in that case. However, since this introduces conflicts with other libraries, using % for concatenation with values, or str_format for performance is advised.

This extension is disabled by default. Define PP_SYNTAX or PP_SYNTAX_@@ to enable it in your script.

Variants

VAR_NULL

const Variant:VAR_NULL = Variant:0;

The null variant. Can be used in most places a variant could be used. This object is suitable as an "empty" value for fixed-size containers.

VariantTag

#define VariantTags Variant
#define VariantTag {VariantTags}
#define ConstVariantTags ConstVariant,VariantTags
#define ConstVariantTag {ConstVariantTags}

Similar to StringTags.

Lists

for_list

#define for_list(%0:%1) for(new Iter:%0=list_iter(%1);iter_inside(%0);iter_move_next(%0))
#define for_list_of<%2>(%0:%1) for(new Iter<%2>:%0=list_iter<%2>(%1);iter_inside(Iter:%0);iter_move_next(Iter:%0))

This syntax is only available if PP_SYNTAX_FOR_LIST is defined. Creates an iterator to a list and uses it to traverse its elements.

Linked lists

for_linked_list

#define for_linked_list(%0:%1) for(new Iter:%0=linked_list_iter(%1);iter_inside(%0);iter_move_next(%0))
#define for_linked_list_of<%2>(%0:%1) for(new Iter<%2>:%0=linked_list_iter<%2>(%1);iter_inside(Iter:%0);iter_move_next(Iter:%0))

This syntax is only available if PP_SYNTAX_FOR_LINKED_LIST is defined. Creates an iterator to a linked list and uses it to traverse its elements.

Maps

for_map

#define for_map(%0:%1) for(new Iter:%0=map_iter(%1);iter_inside(%0);iter_move_next(%0))
#define for_map_of<%2,%3>(%0:%1) for(new PairIter<%2,%3>:%0=map_iter<%2,%3>(%1);iter_inside(Iter:%0);iter_move_next(Iter:%0))

This syntax is only available if PP_SYNTAX_FOR_MAP is defined. Creates an iterator to a map and uses it to traverse its records.

Iterators

ITER_NULL

const Iter:ITER_NULL = Iter:0;

An iterator representing an empty immutable sequence.

Handles

`HANDLE_NULL

const Handle:HANDLE_NULL = Handle:0;

A dead handle.

Tasks

task_restore

enum task_restore
{
    task_restore_none = 0,
    task_restore_frame = 1,
    task_restore_context = 2,
    task_restore_full = 3,
}

An option for task_config that configures the memory range that is preserved when a context is saved. task_restore_none stores no memory from the stack or the heap. task_restore_frame stores only the memory pertaining to the current stack frame (and full heap), task_restore_context stores the memory allocated in the current context, and task_restore_full stores the full valid memory range.

task_state

const task_state:task_state_default = task_state:0;
const task_state:task_state_completed = task_state:1;
const task_state:task_state_faulted = task_state:2;

A value returned from task_state describing the state in which the task currently is.

await and yield 

#define await%9\32;%0; task_await(%0);
#define yield%9\32;%0; task_yield(%0);

These are aliases for comfort and similarity to other programming languages. Do not use this in a compound expression, only as a direct statement (await x;) or in assignment (new y = await x;) since the compiler could misinterpret the parentheses.

These extensions are disabled by default. Define PP_SYNTAX or PP_SYNTAX_AWAIT and PP_SYNTAX_YIELD respectively to enable them in your script.

Threads

sync_flags

enum sync_flags
{
    sync_explicit = 0,
    sync_auto = 1,
    sync_interrupt = 2
}

Synchronization option for thread_detach. sync_explicit synchronizes the thread with the main one only in a call to thread_sync. sync_auto does so in all calls to native functions. sync_interrupt pauses the thread and saves its memory every time the main thread enters into it.

threaded

#define threaded(%0) for(new PP@ts:_@pp_thread_running=PP@ts:(thread_detach(%0)|1);_@pp_thread_running;_@pp_thread_running=PP@ts:(thread_attach()&0))

Initialises a threaded block, by calling thread_detach at the beginning and thread_attach at the end.

This extension is disabled by default. Define PP_SYNTAX or PP_SYNTAX_THREADED to enable it in your script.

Debug

INVALID_SYMBOL_ID

const Symbol:INVALID_SYMBOL_ID = Symbol:cellmin;

A value returned from functions like debug_symbol denoting that no matching symbol was found.

symbol_kind

enum symbol_kind (<<= 1)
{
    symbol_kind_variable = 1,
    symbol_kind_reference,
    symbol_kind_array,
    symbol_kind_array_reference,
    symbol_kind_function = 1 << 8
}

Represents the kind of a symbol in Pawn. Used in debug_symbol and debug_symbol_kind.

symbol_class

enum symbol_class (<<= 1)
{
    symbol_class_global = 1,
    symbol_class_local,
    symbol_class_static
}

Represents the visibility class of a symbol in Pawn. Used in debug_symbol and debug_symbol_class.

Math

random_generator

enum random_generator
{
    generator_library_default = 0,
    generator_mt19937 = 1,
    generator_mt19937_64 = 2,
    generator_minstd_rand0 = 3,
    generator_minstd_rand = 4,
    generator_ranlux24_base = 5,
    generator_ranlux48_base = 6,
    generator_ranlux24 = 7,
    generator_ranlux48 = 8,
    generator_knuth_b = 9,
    generator_random_device = 10
}

Identifies an available (pseudo-)random number generator. See here for their properties.

Clone this wiki locally