[Plugin] PawnPlus

[IllidanS4]

PawnPlus v1.1 released!



Additions

Pools

• A new type of collection providing support for efficient storage of data using reusable integer indices.
  
  
• When an element is added to a pool, it gets assigned an index which is then used to refer to the element.
  
  
• Pools come in two versions with the same API ? ordered (new indices are assigned in a specific order), and unordered. Ordered pools will always assign the lowest unused index to a newly added element.
  
  
• A pool can grow to any size if there are no unused slots for new elements.
  
  

Expressions

• Dynamic run-time representations of operations.
  
  
• Can be constructed from components in a tree-like manner, or parsed from string with expr_parse.
  
  
• The parser supports all standard Pawn operators and some PawnPlus-specific ones. It can also find and use non-public Pawn variables (via the debug API).
  
  
• Expressions can be used in collections and new types of iterators to easily perform queries on multiple elements.
  
  

Async

• async pseudo-attribute for functions using the async pattern (together with return async).
  
  
• The await macro has an alternative definition supporting multiline expression, but requires additional configuration for all tags (enabled via PP_MULTILINE_AWAIT).
  
  
• await_arr and await_var added.
  
  

Collections

• The API is now more unified, so all collections have roughly the same functions with the same semantics.
  
  
• The capacity of the underlying container can be obtained.
  
  

Strings

• If {?} is used in str_format and it doesn't correspond to a color code or a parameter selector, it is parsed and executed as a piece of code.
  
  
• %f in str_format accepts a width parameter.
  
  
• str_append_format added.
  
  

Pawn and AMX

• pawn_create_callback can be used to create a new callback/public function and attach it to the current script. The function consists of an expression that is executed every time the public function is called.
  
  
• Declarational initializers and finalizers added. Any public function whose name starts with _pp@on_init@ will be called first before every other function, when the script is loaded. Any function whose name starts with _pp@on_exit@ will be called last after all other functions, when the script is unloaded. Macros pawn_on_init and pawn_on_exit can be used for easy creation of these functions.
  
  
• AMX guards introduced. While a Pawn guard protects the object for the duration of the current context (analogous to a local variable), an AMX guard protects it for the duration of the script (analogous to a global/static local variable).
  
  
• Handling public function index incompatibility with SAMPGDK can be resolved by pp_public_min_index or pp_use_funcidx. Callback handlers can be registered for negative indices.
  
  
• Captured arguments (in pawn_register_callback or pawn_add_hook) now accept v, h, and x as new types of values. v corresponds to a Variant: argument which is copied to the closure and loaded when it is restored, h corresponds to a Handle: argument which is prolonged by the closure (so the underlying object is not destroyed) and whose value is loaded when the closure is restored, and x corresponds to an Expression: argument containing an expression which is executed every time the argument is restored.
  
  

Error handling

• Dynamically called external natives that raise a system error/signal do not crash the server, but are handled and reported via PawnPlus errors.
  
  

C API

• Support for errors and serialization.
  
  

Changes

Error handling

• pp_on_error is only called for a native called directly by the script. Errors in internally called natives are handled or propagated by the code that called them. pawn_try_call_native never invokes pp_on_error.
  
  

Collections

• Iterators are invalidated on addition only when necessary (when the underlying buffer needs to be reallocated).
  
  

Variants

• Calling operations on variables that are incompatible (different tags or sizes) now produces an error (used to return null).
  
  

Math

• Dynamically called operations on signed: and unsigned: values can raise an error.
  
  

Pawn and AMX

• Incorrect public function index caused by SAMPGDK is detected and warned about.
  
  

Fixes

Variants

• collect operation is now correctly called in some places.
  
  

Async

• When a context is stored after a call to an asynchronous function, reset_stk and reset_hea are now used to correctly restore the original values of stk and hea, fixing a memory leak that happened when a public function with parameters was stored (because the parameters were not taken into account when stk was restored).
  
  

Math

• signed: and unsigned: subtraction fixed.
  
  

Error handling

• Allocation of more data than the script supports is prevented.
  
  

Pawn and AMX

• Removing a hook handler when it is running will not crash the server.
  
  

Examples

Format expressions

Code:

new val1 = 5, val2 = 10;

print_s(str_format("the sum of {val1} and {val2} is {val1  val2}"));

Queries

Code:

new Map:m = map_new();

map_add(m, 1, 10);

map_add(m, 2, 21);

map_add(m, 3, 30);

map_add(m, 4, 41);

map_add(m, 5, 50);

? ?

map_remove_if(m, expr_parse("10*$key != $value")); //removes 2 and 4

Caching expressions

Code:

static Expression:expr;

if(!expr)

{

? ?expr = expr_parse("$value*$value");

? ?amx_guard(expr);

}

Declarational callback handler

Code:

pawn_on_init[callback1]

{

? ?new id = pawn_create_callback("OnPlayerConnect", expr_const(0));

? ?pawn_register_callback(amx_encode_public(id), "MyOnPlayerConnect");

}