Module `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:

configuration parameters could be still passed even when there is no command line interface (via configuration files and environment);

they are specific to plugins and are always prefixed with the plugin name.

type 'a param

a configuration parameter

type t = ctxt

the current configuration.

type info

a piece of information about a system component.

val get : ctxt -> 'a param -> 'a

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.

val parameter : 
  ?doc:string ->
  ?as_flag:'a ->
  ?aliases:string list ->
  'a typ ->
  string ->
  'a param

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}

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>"]

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.

val version : string

version is the preconfigured application version.

val datadir : string

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

val cachedir : string

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.

since 2.3.0

val sysdatadir : string

sysdatadir a directory for system-specific BAP readonly data

since 2.3.0 before that version it was named [datadir]

val libdir : string

libdir a directory for BAP object files, libraries, and internal binaries that are not intended to be executed directly.

val confdir : string

confdir a directory for BAP specific configuration files

val refine : ?provides:string list -> ?exclude:string list -> ctxt -> ctxt

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.

val plugins : ctxt -> info list

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.

val commands : ctxt -> info 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 : Format.formatter -> ctxt -> unit

prints the context

package bap-main

Module Extension.Configuration

Module `Extension.Configuration`