| Zesstra | 715ec20 | 2025-07-09 22:18:31 +0200 | [diff] [blame] | 1 | SYNOPSIS |
| 2 | #include <compile_string.h> |
| 3 | |
| 4 | closure compile_string(symbol* args, string str) |
| 5 | closure compile_string(symbol* args, string str |
| 6 | , struct compile_string_options opts) |
| 7 | closure compile_string(symbol* args, string &str |
| 8 | , struct compile_string_options opts) |
| 9 | |
| 10 | DESCRIPTION |
| 11 | Compiles <str> into a closure. The closure will be bound to the |
| 12 | current object. By default the string will be interpreted as an |
| 13 | LPC expression. The string may also contain preprocessor directives |
| 14 | (which must occur on their own line). |
| 15 | |
| 16 | The argument names are given as the first argument <args>. |
| 17 | |
| 18 | Optionally the function accepts a struct with additional options. |
| 19 | All entries in this struct are optional. These are the members: |
| 20 | |
| 21 | functions: |
| 22 | variables: |
| 23 | structs: |
| 24 | A mapping or closure for the lookup of functions, variables, |
| 25 | resp. structs during compilation. A mapping is looked up using |
| 26 | the name, the closure will be called with the name as its only |
| 27 | argument. The name of the function, variable, resp. struct will |
| 28 | be given as a symbol. The result (mapping value resp. closure |
| 29 | return value) should be: |
| 30 | - for <functions> a closure, |
| 31 | - for <variables> a reference, and |
| 32 | - for <structs> a template struct (i.e. a struct whose data |
| 33 | is irrelevant, only its type will be used). |
| 34 | |
| 35 | use_object_functions: |
| 36 | use_object_variables: |
| 37 | use_object_structs: |
| 38 | If set (integer != 0) the compiled code may reference the |
| 39 | current object's functions, variables, resp. structs. However |
| 40 | successful lookups in <variables>, <functions>, resp. <structs> |
| 41 | have precedence. Private variables, functions and structs |
| 42 | cannot be accessed this way. |
| 43 | |
| 44 | compile_expression: |
| 45 | If set (integer != 0) the string is interpreted as an expression |
| 46 | (eg. "1+1") and therefore must not contain a terminal semicolon. |
| 47 | If no compile mode is selected, this is the default. |
| 48 | |
| 49 | compile_block: |
| 50 | If set (integer != 0) the string is interpreted as a block (code |
| 51 | between braces), the surrounding braces can be omitted. To return |
| 52 | a value, the code needs a return statement. |
| 53 | |
| 54 | as_async: |
| 55 | If set (integer != 0) the code will be compiled as a coroutine, |
| 56 | i.e. the resulting closure will return a coroutine when called. |
| 57 | |
| 58 | detect_end: |
| 59 | If set (integer != 0) the driver will try(!) to detect the end |
| 60 | of the expression/block and return the remaining string in <str> |
| 61 | (<str> needs to be passed as a reference for this). |
| 62 | An end is detected if the word or character following a full |
| 63 | expression or block is not suitable to continue the expression |
| 64 | or block. Also a comma will end an expression. |
| 65 | |
| 66 | When compiling expressions the result of the H_AUTO_INCLUDE_EXPRESSION |
| 67 | driver hook will be prepended, for blocks the H_AUTO_INCLUDE_BLOCK |
| 68 | hook will be used. |
| 69 | |
| 70 | EXAMPLES |
| 71 | funcall(compile_string(({'a,'b}), "a+b"), 1, 2); |
| 72 | |
| 73 | HISTORY |
| 74 | Introduced in LDMud 3.6.7. |
| 75 | |
| 76 | SEE ALSO |
| 77 | compile_string_options(S), lambda(E), block(LPC), |
| 78 | auto_include_expression(H), auto_include_block(H) |