From e48ee82824754c4358909e86d2c5bc933a896976 Mon Sep 17 00:00:00 2001 From: biscuitWizard <1904063+biscuitWizard@users.noreply.github.com> Date: Tue, 19 Apr 2022 04:46:53 -0400 Subject: [PATCH 1/3] Updated documentation for SQLite to generic SQL --- function_help.moo | 32 +++++++++++--------------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/function_help.moo b/function_help.moo index 6c81528..d20edab 100644 --- a/function_help.moo +++ b/function_help.moo @@ -48,23 +48,17 @@ @prop #123."switch_player()" {} rc ;;#123.("switch_player()") = {"Syntax: switch_player(OBJ , OBJ [, INT ])", "", "Silently switches the player associated with this connection from to . must be connected and must be a player. This can be used in do_login_command() verbs that read or suspend (which prevents the normal player selection mechanism from working.", "", "If is true, no connection messages will be printed."} @prop #123."stunt" {} rc -;;#123.("stunt") = {"LambdaMOO-Stunt adds the following built-in functions:", "", "binary_hmac", "string_hmac", "value_hmac - Cryptographically secure HMAC functions.", "decode_base64", "encode_base64 - Encode and decode binary Base64 strings.", "exec - Execute shell scripts and applications.", "exp - Return Eulers number (E) to the power of .", "generate_json - Return the JSON representation of the MOO value.", "parse_json - Return the MOO value representation of a JSON string.", "getenv - Return the value of the named environment variable.", "mapdelete - Delete a key from a map.", "mapkeys - List the keys in a map.", "mapvalues - List the values in a map.", "random_bytes - Return a binary string of bytes.", "read_http - Parse lines from a network connection as HTTP requests.", "salt - Generate a cryptographically secure salt string.", "strtr - Replace characters in a string.", "crypt - Encrypt a string using a variety of algorithms.", "task_local - Return values associated with the current task.", "set_task_local - Set values associated with the current task.", "respond_to - Check if a verb is callable on an object.", "isa - Check if an object is a descendant of another object.", "switch_player - Silently switch a connection to another player.", "", "", "Additionally, the ToastStunt fork adds these:", "", "argon2 - Argon2id secure hashing.", "argon2_verify - Compares password to hash", "sqlite - See HELP SQLITE for a complete list.", "pcre_match - Match a string using Perl Compatible Regular Expressions.", "pcre_replace - Replace text in a string using Perl Compatible Regular Expressions.", "frandom - Random floats.", "distance - Calculate the distance between an arbitrary number of points.", "relative_heading - Calculate a relative bearing between two points.", "memory_usage - Total memory used, resident set size, shared pages, text, data + stack", "ftime - Precise time, including an argument for monotonic timing.", "locate_by_name - Quickly locate objects by their name and aliases.", "usage - Returns a list of system information from the operating system.", "explode - Return a list of substrings of a string separated by a break.", "occupants - Return a list of objects of parent parent, optionally with a player flag check.", "spellcheck - Check the spelling of a word using Aspell.", "locations - Recursive location reporting function.", "clear_ancestor_cache - Manually clears the ancestor cache.", "simplex_noise - Generate Simplex Noise.", "threads - Display a list of active threads.", "thread_info - Display specific information about a running thread.", "new_waif - Create a new waif.", "waif_stats - Display a count of instantiated waifs by class.", "sort - Sorts a list by itself or another list of keys. Also support natural ordering and reverse.", "yin - Yield if needed. Suspend a task when running out of ticks or seconds.", "slice - Makes a new list of the index-th elements of the original list.", "reverse - Reverse a list.", "recreate - Create valid objects from invalid objects.", "set_thread_mode - Enable or disable threading of functions for the current verb.", "chr - Translate integers into ASCII characters.", "recycled_objects - Return a list of all invalid objects in the database.", "next_recycled_object - Return the first available invalid object.", "all_members - Return the indices of all instances of an element in a list.", "owned_objects - Return a list of all objects owned by the specified player.", "sqlite_limit - Specify limits on various SQLite constructs.", "curl - Return websites as strings.", "connection_name_lookup - Perform a DNS name lookup in another thread.", "thread_pool - Manipulate the server thread pool. (Caution advised.)", "connection_info - Return network information about a specific connection.", "maphaskey - Return true if a map contains the key specified.", "ancestors - Return all ancestors of an object", "finished_tasks - When enabled, track execution time", "listen - Updated listen() with ipv6 & tls", "open_network_connection - Updated to support ipv6 & tls", "reseed_random - Provide a new seed to the pseudo random number generator.", "FileIO - See HELP fileio for details", "log_cache_stats", "verb_cache_stats", "create", "value_hash", "index", "rindex", "encode_base64", "decode_base64", "string_hash", "binary_hash", "server_log", "new_waif", "sqlite", "typeof", "reverse", "locations", "finished_tasks", "explode", "chparents", "parents", ""} -@prop #123."sqlite_open()" {} rc -;;#123.("sqlite_open()") = {"Syntax: sqlite_open(STR , [INT options]) => INT", "", "The function `sqlite_open' will attempt to open the database at for use with SQLite.", "", "The second argument is a bitmask of options. Options are:", "", " SQLITE_PARSE_OBJECTS [4]: Determines whether strings beginning with a pound symbol (#) are interpreted as MOO object numbers or not.", " The default is true, which means that any queries that would return a string (such as \"#123\") will be returned as objects.", " SQLITE_PARSE_TYPES [2]: If unset, no parsing of rows takes place and only strings are returned.", " SQLITE_SANITIZE_STRINGS [8]: If set, newlines (\\n) are converted into tabs (\\t) to avoid corrupting the MOO database. Default is unset.", "", "NOTE: If the MOO doesn't support bitmasking, you can still specify options. You'll just have to manipulate the int yourself. e.g. if you want to parse objects and types, arg[2] would be a 6. If you only want to parse types, arg[2] would be 2.", "", "If successful, the function will return the numeric handle for the open database.", "", "If unsuccessful, the function will return a helpful error message.", "", "If the database is already open, a traceback will be thrown that contains the already open database handle."} -@prop #123."sqlite_close()" {} rc -;;#123.("sqlite_close()") = {"Syntax: sqlite_close(INT INT", "", "This function will close an open database.", "", "If successful, return 1;", "", "If unsuccessful, returns E_INVARG."} -@prop #123."sqlite_handles()" {} rc -;;#123.("sqlite_handles()") = {"Syntax: sqlite_handles() => LIST", "", "Returns a list of open SQLite database handles."} -@prop #123."sqlite_info()" {} rc -;;#123.("sqlite_info()") = {"Syntax: sqlite_info(INT ) => MAP", "", "This function returns a map of information about the database at ", "", "The information returned is:", " Database Path", " Type parsing enabled?", " Object parsing enabled?", " String sanitation enabled?"} -@prop #123."sqlite_query()" {} rc -;;#123.("sqlite_query()") = {"Syntax: sqlite_query(INT , STR [, INT ]) => [LIST or STR]", "", "This function will attempt to execute the query given in on the database referred to by .", "", "On success, this function will return a list identifying the returned rows. If the query didn't return rows but was successful, an empty list is returned.", "", "If the query fails, a string will be returned identifying the SQLite error message.", "", "If is true, the return list will include the name of the column before its results.", "", "WARNING: sqlite_query does NOT use prepared statements and should NOT be used on queries that contain user input."} -@prop #123."sqlite_execute()" {} rc -;;#123.("sqlite_execute()") = {"Syntax: sqlite_execute(INT , STR , LIST ) => [LIST or STR]", "", "This function will attempt to create and execute the prepared statement query given in on the database referred to by with the values .", "", "On success, this function will return a list identifying the returned rows. If the query didn't return rows but was successful, an empty list is returned.", "", "If the query fails, a string will be returned identifying the SQLite error message.", "", "sqlite_execute uses prepared statements, so it's the preferred function to use for security and performance reasons.", "", "Example:", "sqlite_execute(0, \"INSERT INTO users VALUES (?, ?, ?);\", {#7, \"lisdude\", \"Albori Sninvel\"})"} -@prop #123."sqlite_last_insert_row_id()" {} rc -;;#123.("sqlite_last_insert_row_id()") = {"Syntax: sqlite_last_insert_row_id(INT )", "", "This function identifies the row ID of the last insert command executed on the database."} -@prop #123."sqlite" {} rc -;;#123.("sqlite") = {"SQLite allows you to store information in locally hosted SQLite databases. The following functions (see HELP for detailed information) are available:", "", "sqlite_open Opens an SQLite database.", "sqlite_close Closes an SQLite database.", "sqlite_handles Returns a list of open SQLite database handles.", "sqlite_info Returns information about an open SQLite database.", "sqlite_query Runs a raw SQL query on the database.", "sqlite_execute Executes an SQL prepared statement on the database.", "sqlite_limit Set limits on various SQL constructs.", "sqlite_interrupt Abort a database operation.", "sqlite_last_insert_row_id Identifies row ID of the last insert command"} +;;#123.("stunt") = {"LambdaMOO-Stunt adds the following built-in functions:", "", "binary_hmac", "string_hmac", "value_hmac - Cryptographically secure HMAC functions.", "decode_base64", "encode_base64 - Encode and decode binary Base64 strings.", "exec - Execute shell scripts and applications.", "exp - Return Eulers number (E) to the power of .", "generate_json - Return the JSON representation of the MOO value.", "parse_json - Return the MOO value representation of a JSON string.", "getenv - Return the value of the named environment variable.", "mapdelete - Delete a key from a map.", "mapkeys - List the keys in a map.", "mapvalues - List the values in a map.", "random_bytes - Return a binary string of bytes.", "read_http - Parse lines from a network connection as HTTP requests.", "salt - Generate a cryptographically secure salt string.", "strtr - Replace characters in a string.", "crypt - Encrypt a string using a variety of algorithms.", "task_local - Return values associated with the current task.", "set_task_local - Set values associated with the current task.", "respond_to - Check if a verb is callable on an object.", "isa - Check if an object is a descendant of another object.", "switch_player - Silently switch a connection to another player.", "", "", "Additionally, the ToastStunt fork adds these:", "", "argon2 - Argon2id secure hashing.", "argon2_verify - Compares password to hash", "sql - See HELP SQL for a complete list.", "pcre_match - Match a string using Perl Compatible Regular Expressions.", "pcre_replace - Replace text in a string using Perl Compatible Regular Expressions.", "frandom - Random floats.", "distance - Calculate the distance between an arbitrary number of points.", "relative_heading - Calculate a relative bearing between two points.", "memory_usage - Total memory used, resident set size, shared pages, text, data + stack", "ftime - Precise time, including an argument for monotonic timing.", "locate_by_name - Quickly locate objects by their name and aliases.", "usage - Returns a list of system information from the operating system.", "explode - Return a list of substrings of a string separated by a break.", "occupants - Return a list of objects of parent parent, optionally with a player flag check.", "spellcheck - Check the spelling of a word using Aspell.", "locations - Recursive location reporting function.", "clear_ancestor_cache - Manually clears the ancestor cache.", "simplex_noise - Generate Simplex Noise.", "threads - Display a list of active threads.", "thread_info - Display specific information about a running thread.", "new_waif - Create a new waif.", "waif_stats - Display a count of instantiated waifs by class.", "sort - Sorts a list by itself or another list of keys. Also support natural ordering and reverse.", "yin - Yield if needed. Suspend a task when running out of ticks or seconds.", "slice - Makes a new list of the index-th elements of the original list.", "reverse - Reverse a list.", "recreate - Create valid objects from invalid objects.", "set_thread_mode - Enable or disable threading of functions for the current verb.", "chr - Translate integers into ASCII characters.", "recycled_objects - Return a list of all invalid objects in the database.", "next_recycled_object - Return the first available invalid object.", "all_members - Return the indices of all instances of an element in a list.", "owned_objects - Return a list of all objects owned by the specified player.", "sqlite_limit - Specify limits on various SQLite constructs.", "curl - Return websites as strings.", "connection_name_lookup - Perform a DNS name lookup in another thread.", "thread_pool - Manipulate the server thread pool. (Caution advised.)", "connection_info - Return network information about a specific connection.", "maphaskey - Return true if a map contains the key specified.", "ancestors - Return all ancestors of an object", "finished_tasks - When enabled, track execution time", "listen - Updated listen() with ipv6 & tls", "open_network_connection - Updated to support ipv6 & tls", "reseed_random - Provide a new seed to the pseudo random number generator.", "FileIO - See HELP fileio for details", "log_cache_stats", "verb_cache_stats", "create", "value_hash", "index", "rindex", "encode_base64", "decode_base64", "string_hash", "binary_hash", "server_log", "new_waif", "sql", "typeof", "reverse", "locations", "finished_tasks", "explode", "chparents", "parents", ""} +@prop #123."sql_open()" {} rc +;;#123.("sql_open()") = {"Syntax: sql_open(STR , [INT options]) => INT", "", "The function `sql_open' will attempt to open a connection to a database at at for use with SQL.", "", "The second argument is a bitmask of options. Options are:", "", " SQL_PARSE_OBJECTS [4]: Determines whether strings beginning with a pound symbol (#) are interpreted as MOO object numbers or not.", " The default is true, which means that any queries that would return a string (such as \"#123\") will be returned as objects.", " SQL_PARSE_TYPES [2]: If unset, no parsing of rows takes place and only strings are returned.", " SQL_SANITIZE_STRINGS [8]: If set, newlines (\\n) are converted into tabs (\\t) to avoid corrupting the MOO database. Default is unset.", "", "NOTE: If the MOO doesn't support bitmasking, you can still specify options. You'll just have to manipulate the int yourself. e.g. if you want to parse objects and types, arg[2] would be a 6. If you only want to parse types, arg[2] would be 2.", "", "If successful, the function will return the numeric handle for the open database.", "", "If unsuccessful, the function will return a helpful error message.", "", "If the database is already open, a traceback will be thrown that contains the already open database handle."} +@prop #123."sql_close()" {} rc +;;#123.("sql_close()") = {"Syntax: sql_close(INT INT", "", "This function will close an open connection pool.", "", "If successful, return 1;", "", "If unsuccessful, returns E_INVARG."} +@prop #123."sql_info()" {} rc +;;#123.("sql_info()") = {"Syntax: sql_info(INT ) => MAP", "", "This function returns a map of information about the database connection pool at ", "", "The information returned is:", " Database Uri", " Type parsing enabled?", " Object parsing enabled?", " String sanitation enabled?", " Connection pool size"} +@prop #123."sql_query()" {} rc +;;#123.("sql_query()") = {"Syntax: sql_query(INT , STR [, LIST ]) => [LIST or STR]", "", "This function will attempt to execute the query given in on the database referred to by . If are specified, they will be passed into the as a parameterized query.", "", "On success, this function will return a list of lists, equating to a list of column's results. If the query didn't return rows but was successful, an empty list is returned.", "", "If the query fails, a string will be returned identifying the SQL error message.", "", "If is true, the return list will include the name of the column before its results."} +@prop #123."sql" {} rc +;;#123.("sql") = {"SQL allows you to store information in local or remote databases. The following functions (see HELP for detailed information) are available:", "", "sql_open Opens a SQL connection pool.", "sql_close Closes an SQL connection pool.", "sql_info Returns information about a SQL connection pool.", "sql_query Runs a raw ore parameterized SQL query on the database."} @prop #123."pcre_replace()" {} rc ;;#123.("pcre_replace()") = {"Syntax: pcre_replace (STR , STR ) => STR", "", "The function `pcre_replace()' replaces with replacements found in using the Perl Compatible Regular Expressions library.", "", "The pattern string has a specific format that must be followed, which should be familiar if you have used the likes of Vim, Perl, or sed. The string is composed of four elements, each separated by a delimiter (typically a slash (/) or an exclamation mark (!)), that tell PCRE how to parse your replacement. We'll break the string down and mention relevant options below:", "", "1. Type of search to perform. In MOO, only 's' is valid. This parameter is kept for the sake of consistency.", "2. The text you want to search for a replacement.", "3. The regular expression you want to use for your replacement text.", "4. Optional modifiers:", " g: Global. This will replace all occurrences in your string rather than stopping at the first.", " i: Case-insensitive. Uppercase, lowercase, it doesn't matter. All will be replaced.", " ", "Examples:", "", "Replace one word with another:", "pcre_replace(\"I like banana pie. Do you like banana pie?\", \"s/banana/apple/g\")", "=> \"I like apple pie. Do you like apple pie?\"", "", "If you find yourself wanting to replace a string that contains slashes, it can be useful to change your delimiter to an exclamation mark:", "pcre_replace(\"Unix, wow! /bin/bash is a thing.\", \"s!/bin/bash!/bin/fish!g\")", "=> \"Unix, wow! /bin/fish is a thing.\""} @prop #123."frandom()" {} rc @@ -117,8 +111,6 @@ ;;#123.("all_members()") = {"Syntax: all_members(ANY , LIST ) => LIST", "", "Returns the indices of every instance of in .", "", "Example:", ";all_members(\"a\", {\"a\", \"b\", \"a\", \"c\", \"a\", \"d\"}) => {1, 3, 5}"} @prop #123."pcre_match()" {} rc ;;#123.("pcre_match()") = {"Syntax: pcre_match (STR , STR [, 0] [, 1] => LIST", "", "The function `pcre_match()' searches for using the Perl Compatible Regular Expressions library. The return value is a list of maps containing each match. Each returned map will have a key which corresponds to either a named capture group or the number of the capture group being matched. The full match is always found in the key \"0\". The value of each key will be another map containing the keys 'match' and 'position'. Match corresponds to the text that was matched and position will return the indices of the substring within .", "", "If is 1, the expression will continue to be evaluated until no further matches can be found or it exhausts the iteration limit. This defaults to 1.", "", "Additionally, wizards can control how many iterations of the loop are possible by adding a property to $server_options. $server_options.pcre_match_max_iterations is the maximum number of loops allowed before giving up and allowing other tasks to proceed. CAUTION: It's recommended to keep this value fairly low. The default value is 1000. The minimum value is 100.", "", "Examples:", "", "Extract dates from a string:", "pcre_match(\"09/12/1999 other random text 01/21/1952\", \"([0-9]{2})/([0-9]{2})/([0-9]{4})\")", "=> {[\"0\" -> [\"match\" -> \"09/12/1999\", \"position\" -> {1, 10}], \"1\" -> [\"match\" -> \"09\", \"position\" -> {1, 2}], \"2\" -> [\"match\" -> \"12\", \"position\" -> {4, 5}], \"3\" -> [\"match\" -> \"1999\", \"position\" -> {7, 10}]], [\"0\" -> [\"match\" -> \"01/21/1952\", \"position\" -> {30, 39}], \"1\" -> [\"match\" -> \"01\", \"position\" -> {30, 31}], \"2\" -> [\"match\" -> \"21\", \"position\" -> {33, 34}], \"3\" -> [\"match\" -> \"1952\", \"position\" -> {36, 39}]]}", "", "Explode a string (albeit a contrived example):", ";;ret = {}; for x in (pcre_match(\"This is a string of words, with punctuation, that should be exploded. By space. --zippy--\", \"[a-zA-Z]+\", 0, 1)) ret = {@ret, x[\"0\"][\"match\"]}; endfor return ret;", "=> {\"This\", \"is\", \"a\", \"string\", \"of\", \"words\", \"with\", \"punctuation\", \"that\", \"should\", \"be\", \"exploded\", \"By\", \"space\", \"zippy\"}"} -@prop #123."sqlite_limit()" {} rc -;;#123.("sqlite_limit()") = {"Syntax: sqlite_limit(INT , STR INT ) => INT", "", "This function allows you to specify various construct limitations on a per-database basis.", "", "If is a negative number, the limit is unchanged. Each limit category has a hardcoded upper bound. Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound.", "", "Regardless of whether or not the limit was changed, the sqlite_limit() function returns the prior value of the limit. Hence, to find the current value of a limit without changing it, simply invoke this interface with the third parameter set to -1.", "", "As of this writing, the following limits exist:", "", "LIMIT_LENGTH", " The maximum size of any string or BLOB or table row, in bytes.", "", "LIMIT_SQL_LENGTH", " The maximum length of an SQL statement, in bytes.", "", "LIMIT_COLUMN", " The maximum number of columns in a table definition or in the result set of a SELECT or the maximum number of columns in an index or in an ORDER BY or GROUP BY clause.", "", "LIMIT_EXPR_DEPTH", " The maximum depth of the parse tree on any expression.", "", "LIMIT_COMPOUND_SELECT", " The maximum number of terms in a compound SELECT statement.", "", "LIMIT_VDBE_OP", " The maximum number of instructions in a virtual machine program used to implement an SQL statement. If sqlite3_prepare_v2() or the equivalent tries to allocate space for more than this many opcodes in a single prepared statement, an SQLITE_NOMEM error is returned.", "", "LIMIT_FUNCTION_ARG", " The maximum number of arguments on a function.", "", "LIMIT_ATTACHED", " The maximum number of attached databases.", "", "LIMIT_LIKE_PATTERN_LENGTH", " The maximum length of the pattern argument to the LIKE or GLOB operators.", "", "LIMIT_VARIABLE_NUMBER", " The maximum index number of any parameter in an SQL statement.", "", "LIMIT_TRIGGER_DEPTH", " The maximum depth of recursion for triggers.", "", "LIMIT_WORKER_THREADS", " The maximum number of auxiliary worker threads that a single prepared statement may start.", "", "For an up-to-date list of limits, see the SQLite documentation here: https://www.sqlite.org/c3ref/c_limit_attached.html"} @prop #123."curl()" {} rc ;;#123.("curl()") = {"Syntax: curl(STR [, INT ]) => STR", "", "The curl builtin will download a webpage and return it as a string. If is true, the HTTP headers will be included in the return string.", "", "It's worth noting that the data you get back will be binary encoded. In particular, you will find that line breaks appear as ~0A. You can easily convert a page into a list by passing the return string into the decode_binary() function."} @prop #123."connection_name_lookup()" {} rc @@ -143,8 +135,6 @@ ;;#123.("panic()") = {"Syntax: panic([STR ])", "", "Unceremoniously shut down the server, mimicking the behavior of a fatal error. The database will NOT be dumped to the file specified when starting the server. A new file will be created with the name of your database appended with .PANIC."} @prop #123."thread_pool()" {} rc ;;#123.("thread_pool()") = {"Syntax: thread_pool(STR , STR [, INT ])", "", "This function allows you to control any thread pools that the server created at startup. It should be used with care, as it has the potential to create disasterous consequences if used incorrectly.", "", "The parameter is the function you wish to perform on the thread pool. The functions available are:", "", " INIT: Control initialization of a thread pool.", "", " ", "The parameter controls which thread pool you wish to apply the designated function to. At the time of writing, the server creates the following thread pool:", "", " MAIN: The main thread pool where threaded built-in function work takes place.", "", "", "Finally, is the value you want to pass to the of . The following functions accept the following values:", "", " INIT: The number of threads to spawn. NOTE: When executing this function, the existing will be destroyed and a new one created in its place.", "", "", "Examples:", ";thread_pool(\"INIT\", \"MAIN\", 1) => Replace the existing main thread pool with a new pool consisting of a single thread."} -@prop #123."sqlite_interrupt()" {} rc -;;#123.("sqlite_interrupt()") = {"Syntax: sqlite_interrupt(INT )", "", "This function causes any pending database operation to abort at its earliest opportunity. If the operation is nearly finished when sqlite_interrupt is called, it might not have an opportunity to be interrupted and could continue to completion.", "", "This can be useful when you execute a long-running query and want to abort it.", "", "NOTE: As of this writing (server version 2.7.0) the @kill command WILL NOT abort operations taking place in a helper thread. If you want to interrupt an SQLite query, you must use sqlite_interrupt and NOT the @kill command."} @prop #123."reverse()" {} rc ;;#123.("reverse()") = {"Syntax: reverse(LIST ) => LIST | STR", "", "Return a reversed list or string.", "", "Examples:", "", ";reverse({1,2,3,4}) => {4,3,2,1}", ";reverse(\"asdf\") => \"fdsa\"", ""} @prop #123."queued_tasks()" {} rc From e9aae02f63201bc5472af283a9a3fc4e6df691be Mon Sep 17 00:00:00 2001 From: biscuitWizard <1904063+biscuitWizard@users.noreply.github.com> Date: Tue, 19 Apr 2022 04:50:35 -0400 Subject: [PATCH 2/3] Added database URI help. --- function_help.moo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/function_help.moo b/function_help.moo index d20edab..5e54e68 100644 --- a/function_help.moo +++ b/function_help.moo @@ -50,7 +50,7 @@ @prop #123."stunt" {} rc ;;#123.("stunt") = {"LambdaMOO-Stunt adds the following built-in functions:", "", "binary_hmac", "string_hmac", "value_hmac - Cryptographically secure HMAC functions.", "decode_base64", "encode_base64 - Encode and decode binary Base64 strings.", "exec - Execute shell scripts and applications.", "exp - Return Eulers number (E) to the power of .", "generate_json - Return the JSON representation of the MOO value.", "parse_json - Return the MOO value representation of a JSON string.", "getenv - Return the value of the named environment variable.", "mapdelete - Delete a key from a map.", "mapkeys - List the keys in a map.", "mapvalues - List the values in a map.", "random_bytes - Return a binary string of bytes.", "read_http - Parse lines from a network connection as HTTP requests.", "salt - Generate a cryptographically secure salt string.", "strtr - Replace characters in a string.", "crypt - Encrypt a string using a variety of algorithms.", "task_local - Return values associated with the current task.", "set_task_local - Set values associated with the current task.", "respond_to - Check if a verb is callable on an object.", "isa - Check if an object is a descendant of another object.", "switch_player - Silently switch a connection to another player.", "", "", "Additionally, the ToastStunt fork adds these:", "", "argon2 - Argon2id secure hashing.", "argon2_verify - Compares password to hash", "sql - See HELP SQL for a complete list.", "pcre_match - Match a string using Perl Compatible Regular Expressions.", "pcre_replace - Replace text in a string using Perl Compatible Regular Expressions.", "frandom - Random floats.", "distance - Calculate the distance between an arbitrary number of points.", "relative_heading - Calculate a relative bearing between two points.", "memory_usage - Total memory used, resident set size, shared pages, text, data + stack", "ftime - Precise time, including an argument for monotonic timing.", "locate_by_name - Quickly locate objects by their name and aliases.", "usage - Returns a list of system information from the operating system.", "explode - Return a list of substrings of a string separated by a break.", "occupants - Return a list of objects of parent parent, optionally with a player flag check.", "spellcheck - Check the spelling of a word using Aspell.", "locations - Recursive location reporting function.", "clear_ancestor_cache - Manually clears the ancestor cache.", "simplex_noise - Generate Simplex Noise.", "threads - Display a list of active threads.", "thread_info - Display specific information about a running thread.", "new_waif - Create a new waif.", "waif_stats - Display a count of instantiated waifs by class.", "sort - Sorts a list by itself or another list of keys. Also support natural ordering and reverse.", "yin - Yield if needed. Suspend a task when running out of ticks or seconds.", "slice - Makes a new list of the index-th elements of the original list.", "reverse - Reverse a list.", "recreate - Create valid objects from invalid objects.", "set_thread_mode - Enable or disable threading of functions for the current verb.", "chr - Translate integers into ASCII characters.", "recycled_objects - Return a list of all invalid objects in the database.", "next_recycled_object - Return the first available invalid object.", "all_members - Return the indices of all instances of an element in a list.", "owned_objects - Return a list of all objects owned by the specified player.", "sqlite_limit - Specify limits on various SQLite constructs.", "curl - Return websites as strings.", "connection_name_lookup - Perform a DNS name lookup in another thread.", "thread_pool - Manipulate the server thread pool. (Caution advised.)", "connection_info - Return network information about a specific connection.", "maphaskey - Return true if a map contains the key specified.", "ancestors - Return all ancestors of an object", "finished_tasks - When enabled, track execution time", "listen - Updated listen() with ipv6 & tls", "open_network_connection - Updated to support ipv6 & tls", "reseed_random - Provide a new seed to the pseudo random number generator.", "FileIO - See HELP fileio for details", "log_cache_stats", "verb_cache_stats", "create", "value_hash", "index", "rindex", "encode_base64", "decode_base64", "string_hash", "binary_hash", "server_log", "new_waif", "sql", "typeof", "reverse", "locations", "finished_tasks", "explode", "chparents", "parents", ""} @prop #123."sql_open()" {} rc -;;#123.("sql_open()") = {"Syntax: sql_open(STR , [INT options]) => INT", "", "The function `sql_open' will attempt to open a connection to a database at at for use with SQL.", "", "The second argument is a bitmask of options. Options are:", "", " SQL_PARSE_OBJECTS [4]: Determines whether strings beginning with a pound symbol (#) are interpreted as MOO object numbers or not.", " The default is true, which means that any queries that would return a string (such as \"#123\") will be returned as objects.", " SQL_PARSE_TYPES [2]: If unset, no parsing of rows takes place and only strings are returned.", " SQL_SANITIZE_STRINGS [8]: If set, newlines (\\n) are converted into tabs (\\t) to avoid corrupting the MOO database. Default is unset.", "", "NOTE: If the MOO doesn't support bitmasking, you can still specify options. You'll just have to manipulate the int yourself. e.g. if you want to parse objects and types, arg[2] would be a 6. If you only want to parse types, arg[2] would be 2.", "", "If successful, the function will return the numeric handle for the open database.", "", "If unsuccessful, the function will return a helpful error message.", "", "If the database is already open, a traceback will be thrown that contains the already open database handle."} +;;#123.("sql_open()") = {"Syntax: sql_open(STR , [INT options]) => INT", "", "The function `sql_open' will attempt to open a connection to a database at at for use with SQL.", "", "The Uri connection string follows this format: database://[user:password@][host][:port]/database[?name=value][&name=value]...", "", "database:// can be any of the following if compiled with the appropriate support:", " postgresql://", " postgres://", " sqlite://", "", "The second argument is a bitmask of options. Options are:", "", " SQL_PARSE_OBJECTS [4]: Determines whether strings beginning with a pound symbol (#) are interpreted as MOO object numbers or not.", " The default is true, which means that any queries that would return a string (such as \"#123\") will be returned as objects.", " SQL_PARSE_TYPES [2]: If unset, no parsing of rows takes place and only strings are returned.", " SQL_SANITIZE_STRINGS [8]: If set, newlines (\\n) are converted into tabs (\\t) to avoid corrupting the MOO database. Default is unset.", "", "NOTE: If the MOO doesn't support bitmasking, you can still specify options. You'll just have to manipulate the int yourself. e.g. if you want to parse objects and types, arg[2] would be a 6. If you only want to parse types, arg[2] would be 2.", "", "If successful, the function will return the numeric handle for the open database.", "", "If unsuccessful, the function will return a helpful error message.", "", "If the database is already open, a traceback will be thrown that contains the already open database handle."} @prop #123."sql_close()" {} rc ;;#123.("sql_close()") = {"Syntax: sql_close(INT INT", "", "This function will close an open connection pool.", "", "If successful, return 1;", "", "If unsuccessful, returns E_INVARG."} @prop #123."sql_info()" {} rc From 12b850582e8f6f46bfdd29842fe2d99c245df952 Mon Sep 17 00:00:00 2001 From: biscuitWizard <1904063+biscuitWizard@users.noreply.github.com> Date: Tue, 19 Apr 2022 04:53:07 -0400 Subject: [PATCH 3/3] Added help for sql_connections --- function_help.moo | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/function_help.moo b/function_help.moo index 5e54e68..38d76c5 100644 --- a/function_help.moo +++ b/function_help.moo @@ -57,8 +57,10 @@ ;;#123.("sql_info()") = {"Syntax: sql_info(INT ) => MAP", "", "This function returns a map of information about the database connection pool at ", "", "The information returned is:", " Database Uri", " Type parsing enabled?", " Object parsing enabled?", " String sanitation enabled?", " Connection pool size"} @prop #123."sql_query()" {} rc ;;#123.("sql_query()") = {"Syntax: sql_query(INT , STR [, LIST ]) => [LIST or STR]", "", "This function will attempt to execute the query given in on the database referred to by . If are specified, they will be passed into the as a parameterized query.", "", "On success, this function will return a list of lists, equating to a list of column's results. If the query didn't return rows but was successful, an empty list is returned.", "", "If the query fails, a string will be returned identifying the SQL error message.", "", "If is true, the return list will include the name of the column before its results."} +@prop #123."sql_connections()" {} rc +;;#123.("sql_connections()") = {"Syntax: sql_connections() => MAP", "", "This function will return a list of all active connection pools on the server.", "", "The format will be the handle INT as the key, and the value will be the connection uri."} @prop #123."sql" {} rc -;;#123.("sql") = {"SQL allows you to store information in local or remote databases. The following functions (see HELP for detailed information) are available:", "", "sql_open Opens a SQL connection pool.", "sql_close Closes an SQL connection pool.", "sql_info Returns information about a SQL connection pool.", "sql_query Runs a raw ore parameterized SQL query on the database."} +;;#123.("sql") = {"SQL allows you to store information in local or remote databases. The following functions (see HELP for detailed information) are available:", "", "sql_open Opens a SQL connection pool.", "sql_close Closes an SQL connection pool.", "sql_info Returns information about a SQL connection pool.", "sql_query Runs a raw ore parameterized SQL query on the database.", "sql_connections Lists all active connections"} @prop #123."pcre_replace()" {} rc ;;#123.("pcre_replace()") = {"Syntax: pcre_replace (STR , STR ) => STR", "", "The function `pcre_replace()' replaces with replacements found in using the Perl Compatible Regular Expressions library.", "", "The pattern string has a specific format that must be followed, which should be familiar if you have used the likes of Vim, Perl, or sed. The string is composed of four elements, each separated by a delimiter (typically a slash (/) or an exclamation mark (!)), that tell PCRE how to parse your replacement. We'll break the string down and mention relevant options below:", "", "1. Type of search to perform. In MOO, only 's' is valid. This parameter is kept for the sake of consistency.", "2. The text you want to search for a replacement.", "3. The regular expression you want to use for your replacement text.", "4. Optional modifiers:", " g: Global. This will replace all occurrences in your string rather than stopping at the first.", " i: Case-insensitive. Uppercase, lowercase, it doesn't matter. All will be replaced.", " ", "Examples:", "", "Replace one word with another:", "pcre_replace(\"I like banana pie. Do you like banana pie?\", \"s/banana/apple/g\")", "=> \"I like apple pie. Do you like apple pie?\"", "", "If you find yourself wanting to replace a string that contains slashes, it can be useful to change your delimiter to an exclamation mark:", "pcre_replace(\"Unix, wow! /bin/bash is a thing.\", \"s!/bin/bash!/bin/fish!g\")", "=> \"Unix, wow! /bin/fish is a thing.\""} @prop #123."frandom()" {} rc