Update scribble-methods.md

9.0/scribble-methods.md

@@ -802,6 +802,55 @@ Forces Scribble to remove this text element from the internal cache, invalidatin
 
  
 
+# Preprocessor
+
+## `.preprocessor(function)` *regenerator*
+
+**Returns**: The text element
+
+|Name      |Datatype|Purpose                                                                                                                                                           |
+|----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`function`|function|The function to execute as a preprocessor. Set to `undefined` to use the global default preprocessor, or set to `SCRIBBLE_NO_PREPROCESS` to force no preprocessing|
+
+A preprocessor function allows you to adjust a string being drawn by Scribble using custom code that goes beyond what Scribble can natively employ. A preprocessor function takes one argument which is the input string defined when calling `scribble()`. This string is literally the string passed to `scribble()` so it will include command tags. A preprocessor function will need to return the modified string using the standard `return` command.
+
+Without intervention, a text element will use the global default preprocessor function as set by `scribble_default_preprocessor_set()`. Updating the global default preprocessor function will **not** automatically regenerate existing text elements so be careful how you use it (intention is to set-and-forget when the game starts).
+
+A preprocessor function is called before Scribble does any processing, including Scribble macros, so it is maximally flexible. **The preprocessor function is only called once when a text element is cached.** This means that using a preprocessor to draw a variable that is liable to update during the lifetime of a text element will not lead to sastisfactory results. Because the preprocessor function is called when the text element is cached, the value that is found in the variable is "frozen" into the text model and will not change until the text element is regenerated by some means. *(If you want to have live updating variables, just modify the input string like you would with any other normal text drawing command.)*
+
+An example pass-through preprocessor function (a function that does not modify the string) looks like this:
+
+```gml
+function(_string)
+{
+    return _string;
+}
+```
+
+A more complicated preprocessor function that replaces `$123$` to follow the pattern `[spr_money][c_green]123[/c]` looks like this:
+
+```gml
+function(_string)
+{
+    var _split = string_split(_string, "$");
+    var _i = array_length(_split)-2;
+    repeat((array_length(_split)-1) div 2)
+    {
+        array_insert(_split, _i,   "[spr_money][c_green]");
+        array_insert(_split, _i+1, "[/c]");
+        _i -= 2;
+    }
+    
+    return string_concat_ext(_split);
+}
+```
+
+ 
+
+ 
+
+ 
+
 # Miscellaneous
 
 ## `.get_events(position, [page])`