bap-std 2.2.0 · OCaml Package

This module allows plugins to access BAP configuration variables.

When reading the values for the configuration variables, the decreasing order of precedence for the values is:

Command line arguments
Environment variables
Configuration file
Default fallback value

Example usage:

let path = Config.(param string ~doc:"a path to file"
                     ~default:"input.txt" "path")
let debug = Config.(flag (* ... *) )

(* ... *)

let main () =
  Config.when_ready
    (fun {Config.get=(!)} ->
       do_stuff !path !debug (* ... *)
    )

val version : string

Version number

val datadir : string

A directory for bap specific read-only architecture independent data files.

val libdir : string

A directory for bap specific object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts

val confdir : string

A directory for bap specific configuration files

type 'a param

An abstract parameter type that can be later read using a reader

type 'a parser = string -> [ `Ok of 'a | `Error of string ]

Parse a string to an 'a

type 'a converter

Type for converting string <-> 'a. Also defines a default value for the 'a type.

val converter : 
  'a parser ->
  (Stdlib.Format.formatter -> 'a -> unit) ->
  'a ->
  'a converter

val deprecated : string

Default deprecation warning message, for easy deprecation of parameters.

val param : 
  'a converter ->
  ?deprecated:string ->
  ?default:'a ->
  ?as_flag:'a ->
  ?docv:string ->
  ?doc:string ->
  ?synonyms:string list ->
  string ->
  'a param

param conv ~default ~docv ~doc name creates a parameter which is referred to on the command line, environment variable, and config file using the value of name, with the type defined by conv, using the default value if unspecified by user.

The default is optional, and falls back to the default defined by conv.

doc is the man page information of the argument. The variable "$(docv)" can be used to refer to the value of docv. docv is a variable name used in the man page to stand for their value.

A user can optionally add deprecated to a parameter that is to be deprecated soon. This will cause the parameter to be usable as normal, but will emit a warning to the user if they try to use it. Example usage: Config.(param ~deprecated int "--old").

Additionally, synonyms can be added to allow multiple arguments referring to the same parameters. However, this is usually discouraged, and considered proper usage only in rare scenarios.

Also, a developer can use the ~as_flag to specify a default value that the argument takes if it is used like a flag. This behaviour can be understood better through the following example.

Consider Config.(param (some int) ~as_flag:(Some 10) "x").

This results in 3 possible command line invocations:

1. No --x - Results in default value (specifically here, None).

2. Only --x - This causes it to have the value as_flag (specifically here,Some 10).

3. --x=20 - This causes it to have the value from the command line (specifically here, Some 20).

val param_all : 
  'a converter ->
  ?deprecated:string ->
  ?default:'a list ->
  ?as_flag:'a ->
  ?docv:string ->
  ?doc:string ->
  ?synonyms:string list ->
  string ->
  'a list param

Create a parameter which accepts a list at command line by repetition of argument. Similar to param (list 'a) ... in all other respects. Defaults to an empty list if unspecified.

val flag : 
  ?deprecated:string ->
  ?docv:string ->
  ?doc:string ->
  ?synonyms:string list ->
  string ->
  bool param

Create a boolean parameter that is set to true if user mentions it in the command line arguments

val determined : 'a param -> 'a Bap_future.Std.future

Provides a future determined on when the config can be read

type reader = {

get : 'a. 'a param -> 'a;

}

A witness that can read configured params

val when_ready : (reader -> unit) -> unit

when_ready f requests the system to call function f once configuration parameters are established and stabilized. An access function will be passed to the function f, that can be used to safely dereference parameters.

type manpage_block = [

| `I of string * string
| `Noblank
| `P of string
| `Pre of string
| `S of string

]

The type for a block of man page text.

`S s introduces a new section s.
`P t is a new paragraph with text t.
`Pre t is a new preformatted paragraph with text t.
`I (l,t) is an indented paragraph with label l and text t.
`Noblank suppresses the blank line introduced between two blocks.

Except in `Pre, whitespace and newlines are not significant and are all collapsed to a single space. In labels l and text strings t, the syntax "$(i,italic text)" and "$(b,bold text)" can be used to respectively produce italic and bold text.

val manpage : manpage_block list -> unit

Create a manpage for the plugin

val bool : bool converter

bool converts values with bool_of_string.

val char : char converter

char converts values by ensuring the argument has a single char.

val int : int converter

int converts values with int_of_string.

val nativeint : nativeint converter

nativeint converts values with Nativeint.of_string.

val int32 : int32 converter

int32 converts values with Int32.of_string.

val int64 : int64 converter

int64 converts values with Int64.of_string.

val float : float converter

float converts values with float_of_string.

val string : string converter

string converts values with the identity function.

val enum : (string * 'a) list -> 'a converter

enum l converts values such that unambiguous prefixes of string names in l map to the corresponding value of type 'a.

Warning. The type 'a must be comparable with Pervasives.compare.

raises Invalid_argument
if l is empty.

val doc_enum : ?quoted:bool -> (string * 'a) list -> string

doc_enum l documents the possible string names in the l map according to the number of alternatives. If quoted is true (default), the tokens are quoted. The resulting string can be used in sentences of the form "$(docv) must be %s".

val file : string converter

file converts a value with the identity function and checks with Sys.file_exists that a file with that name exists.

val dir : string converter

dir converts a value with the identity function and checks with Sys.file_exists and Sys.is_directory that a directory with that name exists.

val non_dir_file : string converter

non_dir_file converts a value with the identity function and checks with Sys.file_exists and Sys.is_directory that a non directory file with that name exists.

val list : ?sep:char -> 'a converter -> 'a list converter

list sep c splits the argument at each sep (defaults to ',') character and converts each substrings with c.

val array : ?sep:char -> 'a converter -> 'a array converter

array sep c splits the argument at each sep (defaults to ',') character and converts each substring with c.

val pair : ?sep:char -> 'a converter -> 'b converter -> ('a * 'b) converter

pair sep c0 c1 splits the argument at the first sep character (defaults to ',') and respectively converts the substrings with c0 and c1.

val t2 : ?sep:char -> 'a converter -> 'b converter -> ('a * 'b) converter

t2 is pair.

val t3 : 
  ?sep:char ->
  'a converter ->
  'b converter ->
  'c converter ->
  ('a * 'b * 'c) converter

t3 sep c0 c1 c2 splits the argument at the first two sep characters (defaults to ',') and respectively converts the substrings with c0, c1 and c2.

val t4 : 
  ?sep:char ->
  'a converter ->
  'b converter ->
  'c converter ->
  'd converter ->
  ('a * 'b * 'c * 'd) converter

t4 sep c0 c1 c2 c3 splits the argument at the first three sep characters (defaults to ',') respectively converts the substrings with c0, c1, c2 and c3.

val some : ?none:string -> 'a converter -> 'a option converter

some none c is like the converter c except it returns Some value. It is used for command line arguments that default to None when absent. none is what to print to document the absence (defaults to "").

package bap-std