lib_funlib function library

Dependencies: lib_2da, lib_anon, lib_array, lib_fn, lib_ini, lib_math, lib_sfo, lib_sugar, lib_tools, lib_ui

Description

Dedicated library to document a set of WEIDU function libraries and work out their dependencies. Documentation is pulled directly from the tph/tpa file.

To document a function, use this notation in a comment somewhere in your TPH:

document{my_function} {Description of the function.}

To put a description of the whole library, use this:

describe-library
{
Description of the library
}

To mark a variable as Boolean, Array, Function, Obsolete (not documented) or Switch, use this sort of notation

INT_VAR
b=0//boolean
i=0
o=0//obsolete STR_VAR
f=""//function
a=""//array
c=""//[upper|lower]

Public functions

funlib_combine_libraries(library:s, path:s="MOD_FOLDER/sfo", data_path:s="MOD_FOLDER/sfo/data")=() action

Given 'library' and 'path' (defaults to the sfo library path), look for a template file, '.tpt'. If you find it, copy it to '.tpc' (also at 'path'), replacing any instances of include-library{lib_whatever

funlib_document_component(component_loc:s, extra_path:s)=() dimorphic

Particular application of funlib_document_libraries that documents all tpa/tph files in a directory, setting extra_path to the sfo library directory.

funlib_document_libraries(library_path:s="MOD_FOLDER/sfo", library_array:a, extra_path:s, extra_array:s, style_path:s="../../doc/files", resource_path:s="MOD_FOLDER/sfo", template_path:s="MOD_FOLDER/sfo/resource/doc_template.html", index_template_path:s="MOD_FOLDER/sfo/resource/index_template.html", doc_path:s="MOD_FOLDER/sfo/doc/functions", ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da", menu_data:s="menu_data.ini", menu_path:s="MOD_FOLDER/sfo/data")=() dimorphic

Given either an array of libraries in the form file=>path, or a path to a directory of libraries (assumed to be all and only the tph/tpa files) generate HTML documentation for each library (and also check for namespace collisions). MOD_FOLDER/sfo/resource/doc_template.html points to the HTML template into which we substitute the data. ../../doc/files points to the location of the css files and similar. doc_path is where you want them to go. Functions listed in the 'ignore' 2da (by default, the weidu built-in functions) are ignored. If 'extra_array' or 'extra_path' are set, the libraries contained in the array or on the path are included for dependencies but not documented.

'menu_data' and 'menu_path' point to the file that describes which overall lists of functions are to be generated. (The default file lists the SFO functions, the SFO-LUA functions, all the functions, and all the functions including deprecated and internal ones.

funlib_get_functions_used(file:s, path:s, location:s, locbase:s)=(functions_used:a, ignore_dependencies:a) action

Return a k=>_ array of all functions used (via LAF/LPF) in the specified library. Also return an array of dependencies we're directed to ignore (via ignore_dependencies).

funlib_report_dependencies(recursive:i=1, library_path:s, library_array:a, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=() dimorphic

Given either an array of libraries in the form file=>path, or a path to a directory of libraries (assumed to be all and only the tph/tpa files), generate a report in the data_loc directory on dependencies, missing functions, and use of internal functions. If recursive=1, close dependency relations transitively.

Internal functions

These should not be called from outside the library itself.

funlib_extract_function_data()=(function_data:a) patch

Destructively process the current file (assumed to be a tpx file) and return a 3d array of the function spec blocks (everything up to the BEGIN) in the format (function_name,function_type,function_comment=>function_spec. (Function_type is action, patch or dimorphic.)

funlib_get_dependencies(recursive:i=1, library_array:a, ignore:s="sfo/data/weidu_functions.2da")=(dependency_map:a, missing_map:a, internal_map:a) action

Given an array of libraries in the format file=>path, find all the dependencies and return them in a 2d array in format (dependent_library,required_library)=>_.

Also return a 2d array of functions that are used in the libraries but not defined in any of them, in the format (library, function_it_uses)=>_.

Also return a 2d array of libraries that use internal functions, in the format (library,function_it_uses)=>_

Functions in the zeroth column of the 2da file 'ignore' (by default, a list of all the predefined WEIDU functions) are ignored.

funlib_get_external_functions(ignore:s="sfo/data/weidu_functions.2da", file:s, path:s)=() action

Echo to screen the external functions used by a specific library.

funlib_get_function_descriptions(path:s, file:s)=(function_descriptions:a) action

Process the given file to get an 4d array of form (function_name,function_type,comment,library)->nicely_processed_description_of_spec.

funlib_get_function_locations(library_array:a)=(function_locations:a, function_locations_singular:a, internal_functions:a) action

Given either an array of libraries in the format file=>path, or a path to a directory of libraries (with tpa/tph suffixes), go through all the libraries and get where each function is. Return it in a 2d array in the form (function,library)=>_. Also return a 1d array in the form function=>_ of all the internal functions. Also return a 1d array in the form function=>library, that contains an arbitrary library where the function is.

(I mean, functions shouldn't be multiply defined. But sometimes they are. If they are, also throw a WARNING and record it in the SFO logfile.

funlib_get_functions_defined()=(functions_defined:a) patch

Return a k=>v array of all functions defined in the currently-being-patched library, where v is the comment if any.

funlib_get_functions_documented(file:s, path:s)=(library_doc:s, technical_note:s, brief_desc:s, function_docs:a) action

Return a function-name=>function-description array of all function descriptions in the specified library, as well as the overall library description (if any). Also return 'library_doc' and 'technical_doc', which code more advanced details

funlib_get_library_array(library_path:s)=(library_array:a) dimorphic

Go through the given directories and return an array of tpa/tph files, in the format file->path.

funlib_list_external_functions(file:s, path:s, location:s, locbase:s, library_array:a, library_path:s, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=(external_functions:a) action

funlib_process_document_lines(include_origin:i, count_functions:i, type:s, descriptions:s="function_descriptions", documentations:s="function_docs", require_path:s)=(data:s, function_counts:a) dimorphic

funlib_record_dependencies(library_path:s="MOD_FOLDER/sfo", library_array:a, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da", output:s="MOD_FOLDER/sfo/data/sfo_dependencies.2da")=() action

Output the 2D array generated by funlib_get_dependencies into an array (default values generate SFO's dependency array, used by the sfo_load function).

Technical notes

]*{\([^