lib_funlib function library

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

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 or Switch, use this sort of notation

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

Functions

funlib_document_component(component_loc: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", doc_path:s="MOD_FOLDER/sfo/doc", 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 HTML documentation for each library. 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.

funlib_get_dependencies(recursive:i=1, library_array:a, ignore:s="MOD_FOLDER/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_function_descriptions(path:s, file:s)=(function_descriptions:a) action

Process the given file to get an 3d array of form (function_name,function_type,comment)->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.)

funlib_get_functions_documented(file:s, path:s)=(library_doc:s, technical_note: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_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_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_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_used(file:s, path:s, location:s, locbase:s)=(functions_used:a) action

Return a k=>_ array of all functions used (via LAF/LPF) in the specified library.)

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

Go through the given directory and return an array of tpa/tph files, in the format file->path (path is the same for all).

funlib_process_document_lines(type:s)=(data:s) dimorphic

Technical notes

]*{\([^