Legend:
Library
Module
Module type
Parameter
Class
Class type
A self reflection.
This is a generative functor module refers to an information bundled with an application. Use include Self() syntax to bring this definitions to the scope.
It is designed to be used inside a plugin, but can be used in a standalone program as well (this is useful, for debugging plugins, by running them as a standalone applications).
If run in a standalone mode, then field name would be set to Sys.executable_name and argv to Sys.argv.
Note: this module uses the Event.Self() module and extends it with several more fields, such as name, version, doc, and argv. It is recommended to use Event.Self() aka Bap_main_event.Self() instead.
Parameters
Signature
val name : string
name of a plugin
val version : string
version number
val doc : string
A short, one-line description
val argv : string array
args name returns an array of arguments designated for a plugin with a given name.
The arguments will be extracted from Sys.argv array by removing all arguments that doesn't start with --name-. Then, from all command arguments that are left, the --name- prefix is substituted with --. For example, if argv contained [| "bap"; "-lcallgraph"; "--callgraph"
"--callgraph-help"|] then pass that registered itself under callgraph name will receive the following array of arguments [| "callgraph"; --help |] . That means, that plugins can't accept arguments that are anonymous or short options
val report_progress :
?task:string ->?note:string ->?stage:int ->?total:int ->unit ->
unit
report_progress ~task:t ~note:n ~state:s ~total:s' () reports a progress of the task t.
Reports that the task t made a progress to the stage s out the total number of stages s'. The note n may provide an additional textual explanation of the current stage. The report doesn't mean that the stage is finished, but rather that it is entered. Thus for s' stages we expect to receive s'-1 reports. (This approach works fine with functional programming and iterating - as in functional programming it is more convenient to report before computation, and during the indexed iteration the index of the last element is one less than the total number of elements).
All parameters are optional, and have the following default values if not specified:
parametertask
defaults to the plugin name;
parameternote
defaults to the empty string;
parameterstage
defaults to None
parametertotal
defaults to None or to the last value of this parameter for the given task.
The report_progress bar is an easy way to provide some feedback to the system, either in the form of a progress (if the total number of stages is known) or in the form of a friendly ping back.
The mechanism should be used by analyses that expect to take some time to complete. Usually, one plugin implements only one task, so the task name may be omitted. If an analysis is built from several tasks, then they can be represented as subtasks, and the main task should represent the whole work.