Extension.Configuration
Configuration Parameters.
Use this module to declare and use configuration parameters for your plugins. Although configuration parameters could be specified via the command line, they are different from the corresponding parameters of commands in several ways:
type t = ctxt
the current configuration.
get ctxt parameter
gets the value of the parameter
.
Accesses the value of the previously defined parameter
.
The Extension.Syntax
module also provides an infix version of this function under the -->
name.
parameter t name
declares a configuration parameter.
This declaration extends the common-options
grammar by adding the following rules
common-options = ... | common-options, R | R, common-options R = ["--<plugin>-<name>", ["="], t]
,
where <plugin>
is the name of the plugin in which the configuration parameter is specified. (Note, the name of a plugin is the name of the file in which it is packed without the extension, e.g., a plugin foo.plugin
has name foo
).
When the --<plugin>-<name> v
is specified on the command line, or a configuration file, or in the environment, then get ctxt p
will evaluate to v
, where p
is the declared parameter.
The as_flag
option makes the value part optional on the command line, so that declare ~as_flag=v t name
extends the grammar by adding the following rules
common-options = ... | common-options, R | R, common-options R = ["--<plugin>-<name>", [["="], t]]
,
Then, if the parameter was specified on the command line without an argument, then v
will be used as the value of the parameter.
When aliases
are specified, then for each name
in the aliases a --<plugin>-<name>
option will be added.
Note, even if the name is short (i.e., consisting only of one letter) it will still be prefixed with the plugin name and interpreted as a long option, e.g., if name is "k"
and the plugin name is "foo"
, then the option name will be "--foo-k"
.
Examples
Declaring a simple configuration parameter:
open Core_kernel[@@warning "-D"]
open Bap_main.Extension
let depth = Configuration.parameter Type.int "depth"
let () =
Bap_main.Extension.declare @@ fun ctxt ->
printf "Will dive to depth %d\n"
(Configuration.get ctxt depth)
The Extension.Syntax
module adds an infix (-->)
operator for the get
function. Using this operator the previous example could be rewritten as:
open Core_kernel[@@warning "-D"]
open Bap_main.Extension
open Bap_main.Extension.Syntax
let depth = Configuration.parameter Type.int "depth"
let () =
Bap_main.Extension.declare @@ fun ctxt ->
printf "Will dive to depth %d\n" (ctxt-->depth)
val parameters :
?doc:string ->
?as_flag:'a ->
?aliases:string list ->
'a typ ->
string ->
'a list param
parameters t name
declares a multi-occurring parameter.
This declaration extends the common-options
grammar by adding the following rules
common-options = ... | common-options, R | R, common-options R = {"--<plugin>-<name>", ["="], t}
,
where <plugin>
is the name of the plugin in which the configuration parameter is specified. (Note, the name of a plugin is the name of the file in which it is packed without the extension, e.g., a plugin foo.plugin
has name foo
).
Every time the --<plugin>-<name> v
is specified on the command line, or a configuration file, or in the environment, then v
is added to the list to which get ctxt p
, where p
is the declared parameter.
The rest of the parameters have the same meaning as in the parameter
function.
val flag : ?doc:string -> ?aliases:string list -> string -> bool param
flag name
declares a parameter that can be used as a flag.
This is a specialization of a more general parameter
function. The common-options
grammar is extended with the following rules:
common-options = ... | common-options, R | R, common-options R = ["--<plugin>-<name>"]
,
where <plugin>
is the name of the plugin in which the configuration parameter is specified. (Note, the name of a plugin is the name of the file in which it is packed without the extension, e.g., a plugin foo.plugin
has name foo
).
When the --<plugin>-<name> v
is specified on the command line, or in the environment, then get ctxt p
will evaluate to true
, where p
is the declared parameter.
val determined : 'a param -> 'a Bap_future.Std.future
determined p
is a future that becomes determined when context is ready.
datadir
a directory for user-specific BAP readonly data.
The folder is either $XDG_DATA_HOME/bap or $HOME/.local/share/bap if the former is not set.
If $HOME is also not set then it defaults just to the current workding directory.
Plugins are encouraged to use this folder as the base folder and store their information in subfolders of it.
before 2.3.0 the value of this parameter was equal to sysconfdir
cachedir
folder for user-specific non-essential data files.
It is either $XDG_CACHE_HOME/bap or $HOME/.cache/bap or $TMP/bap/cache, depending on whether the corresponding variables are set.
libdir
a directory for BAP object files, libraries, and internal binaries that are not intended to be executed directly.
refine ~provides ~exclude ctxt
refines the context.
Refine the context by excluding from it all parameters of the plugins that do not provide a feature from provides
or provide a feature from excluded
.
@parameter provides (defaults to set of all features) the set of features that should be left.
@parameter exclude (defaults to the empty set) the set of features that should be excluded.
plugins ctxt
enumerates all enabled plugins.
If provides
is specified, then enumerates only plugins than provide at least one of specified feature.
If exclude
is specified, then exclude from the list plugins, that has one of the feature specified in the exclude
list.
commands ctxt
enumerates all available commands.
If features
and/or exclude
are specified, then they have the same meaning as in plugins~features~exclude
.
val info_name : info -> string
name info
returns the name of a plugin or command.
val info_doc : info -> string
doc info
returns the short documentation.
val digest : ctxt -> string
digest context
returns the context
digest.
The digest is a 128-bit MD5 sum of all options of all plugins that were selected in the context and match the filters specified by the features
and exclude
parameters.
See the plugins
function for the description of the features
and exclude
parameters.
Note: the digest doesn't include the command options and arguments only plugins configuration options.
val features : ctxt -> string list
val pp : Stdlib.Format.formatter -> ctxt -> unit
prints the context