Dependencies: lib_2da, lib_anon, lib_array, lib_fn, lib_ini, lib_math, lib_sfo, lib_sugar, lib_tools, lib_ui
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]
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, '
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.
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).
]*{\([^