Module ds

Description
Data Types
Function Index
Function Details

The public user and API interface module of dumpsterl.

Description

The public user and API interface module of dumpsterl.

All usage of dumpsterl, both programmatic and user-initiated, should be done via this module.

This module exports three API-s, from highest to lowest level:

User API: Launch interactive user interface components (the dumpsterl shell and gui).
Probe API: Run the probe and obtain a spec. These functions are invoked by the dumpsterl shell (see User API) but might also be used manually from the Erlang shell, or called directly by third-party code.
Spec API: Low level spec manipulations, or adding terms to a spec "by hand".

Each function is marked with the API it belongs to. For API usage examples, please see the User Guide, section API examples.

Data Types

attr_spec()

attr_spec() = {AttrName::atom(), field_spec()}

Specify attributes to be attached to each spec'd term. AttrName may be arbitrary, but the following receive special attention from the GUI:

key: The primary key from the raw record. This is useful to be able to pull the complete, original record from the table in case you find an oddball value while browsing the spec in the GUI.
ts: Timestamp from the record (creation or modification time). The only restriction the probe places on this is that its Erlang term ordering must correspond to temporal order (later timestamps must compare larger than earlier ones) in order to be useful. However, for the GUI to understand them, timestamps must be in one of the supported formats as listed in the User Guide, section Timestamp format support.

field_spec()

field_spec() = [] | non_neg_integer() | fun((Record::term()) -> Field::term()) | [field_spec()]

The field spec is used to select the data that is to be taken and spec'd from the raw terms fed to the probe. Normally, the raw term is a Record from a database table, and the field spec selects a certain Field. However, more elaborate scemes are also possible:

[] or 0: select whole record (or term)
N where N > 0: select the field N.
fun(): User-defined selection. The fun takes the record as its single argument and returns the selected value.
List of accessors: multiple accessors may be chained and supplied in a list. The accessors are applied from left to right, always taking the result of the previous one as their input. E.g., [3,2] is interpreted as: "Take the third field from the record read from the table, then take the second field of the result, and spec that."

Any runtime error within the accessor will cause the record to be skipped, so a fun() accessor can also act as a filter via deliberate throw()-ing. Even if a record is skipped, it still counts toward the probe limit and shows up in the output count.

options()

options() = [proplists:property()]

Options to influence dumpsterl's behaviour.

The easiest way to get a full reference (including commands, params and options) is to start the dumpsterl shell via ds:shell() and then enter help all. The resulting listing is also available as the shell reference.

probe_spec()

probe_spec() = field_spec() | {field_spec(), [attr_spec()]}

The probe specification tells the probe what to spec from the raw records read, and what attributes to associate with it. The attributes are optional, and reference the whole, raw record read from the table, even if the field spec selects a part of that. Hence, it is possible to have parts of the original record stored as attributes that are not part of the spec'd data.

spec()

abstract datatype: spec()

The spec data structure created by the probe and consumed by the GUI.

This should be treated primarily as an opaque data structure. However, for those wishing to understand the internals of dumpsterl, a high-level description is available in the User Guide, The spec.

table_id()

table_id() = atom() | ets:tid() | dets:tab_name() | file:filename()

The table to read. Its accepted format depends on the type setting:

mnesia or ets table name (atom);
ets table id (integer);
dets table name (any term) for an already opened dets table;
filename of a dets table file or disk_log file.

table_type()

table_type() = mnesia | ets | dets | disk_log

The type of table to read. This selects the table iterator functions for the probe.

Function Index

add/2	[Spec API] Add a term (without attributes) to the spec.
add/3	[Spec API] Add a term (with attributes) to the spec.
gui/0	[User API] Start the GUI on the default dump file.
gui/1	[User API] Start the GUI on the supplied Spec.
join/2	[Spec API] Join two specs into one.
new/0	[Spec API] Create a new spec.
postproc/1	[Spec API] Postprocess a spec.
pretty_print/1	[Spec API] Pretty-print a spec.
probe/3	[Probe API] Launch the probe to run in the background, using default options.
probe/4	[Probe API] Like `probe/3`, but also specify options.
shell/0	[User API] Start the interactive probe shell.
spec/3	[Probe API] Run the probe to create a spec, using default options.
spec/4	[Probe API] Like `spec/3`, but also specify options.
spec_to_form/1	[Spec API] Convert a spec to Erlang abstract from.

Function Details

add/2

add(Term::term(), Spec::spec()) -> spec()

Equivalent to add(Term, [], Spec).

[Spec API] Add a term (without attributes) to the spec. Due to the order of the arguments, this function can be directly passed to lists:foldl/3.

add/3

add(Term::term(), Attrs::[{AttrName::atom(), AttrValue::term()}], Spec::spec()) -> spec()

[Spec API] Add a term (with attributes) to the spec. The attributes must be passed directly as a list of key-value tuples.

gui/0

gui() -> wx:wx_object() | {error, term()}

[User API] Start the GUI on the default dump file. This is "ds.bin" in the current directory.

gui/1

gui(Spec::spec() | file:filename()) -> wx:wx_object() | {error, term()}

[User API] Start the GUI on the supplied Spec. Spec might be a spec data structure or a dump filename.

join/2

join(Spec1::spec(), Spec2::spec()) -> spec()

[Spec API] Join two specs into one. This is useful in case the set of terms to be spec'd was partitioned into subsets that were independently spec'd. By joining these specs, the spec for the whole set of terms can be obtained.

NB. joining must be done on the "raw" spec tree, one that was created only via new/0 and add/2,3. In such a tree, all the abstract nodes starting from the root 'term' are always present. See postproc/1 for a tree that does not qualify for this condition.

new/0

new() -> spec()

[Spec API] Create a new spec.

postproc/1

postproc(Spec::spec()) -> spec()

[Spec API] Postprocess a spec. This is performed as a pre-load step in the GUI, but could be useful in other scenarios. It has a few separate steps:

compact the tree by cutting empty abstract types;
propagating and joining metadata up from the leaf nodes;
sorting the children of unions by decreasing count.

NB. The result of this function generally cannot be passed to the add/2-3 and join/2 functions.

pretty_print/1

pretty_print(Spec::spec()) -> string()

[Spec API] Pretty-print a spec. Returns a string produced via converting the spec to the Erlang abstract form of the type definition and pretty-printing that with the Erlang pretty-printer.

Naturally, this only contains a type definition and does not show anything of the samples and statistics contained in the spec.

probe/3

probe(Type::table_type(), Tab::table_id(), ProbeSpec::probe_spec()) -> {pid(), reference()}

[Probe API] Launch the probe to run in the background, using default options. The call returns (almost) immediately with a value that can be used to stop the probe before completion:

      {Pid, _} = ds:probe(...).
      ...
      Pid ! finish.

The second value in the returned tuple is a monitor reference; the probe will be monitored by the caller. This means that the caller will receive a message when the probe completes:

      {Pid, MonitorRef} = ds:probe(...),
      receive
          {'DOWN', MonitorRef, process, Pid, Info} ->
              io:format("probe done: ~p~n", [Info])
      end.

probe/4

probe(Type, Tab, ProbeSpec, Opts) -> any()

[Probe API] Like probe/3, but also specify options.

shell/0

shell() -> ok

[User API] Start the interactive probe shell. The function returns only when the user quits the shell.

spec/3

spec(Type::table_type(), Tab::table_id(), ProbeSpec::probe_spec()) -> spec()

[Probe API] Run the probe to create a spec, using default options. The function blocks the caller while the probe is running. The result spec is returned as a return value (but might also be dumped to file according to the options; the default is to dump to "ds.bin").

spec/4

spec(Type::table_type(), Tab::table_id(), ProbeSpec::probe_spec(), Opts::options()) -> spec()

[Probe API] Like spec/3, but also specify options.

spec_to_form/1

spec_to_form(Spec::spec()) -> erl_parse:abstract_form()

[Spec API] Convert a spec to Erlang abstract from. The abstract form contains a type definition equivalent to the spec tree. Its primary use is passing it to the Erlang pretty-printer to obtain a nicely formatted spec type definition. If that is your end goal, you should use the function pretty_print/1 instead.

Generated by EDoc, May 25 2017, 20:32:21.