NAME

BenchmarkAnything::Storage::Frontend::Lib - Basic functions to access a BenchmarkAnything store

new

Instantiate a new object.

• cfgfile

  Path to config file. If not provided it uses env variable BENCHMARKANYTHING_CONFIGFILE or $home/.benchmarkanything.cfg.

• noconfig

  If set to 1, do not initialize configuration.

• noconnect

  If set to 1, do not automatically connect to backend store.

• really

  Used for critical functions like createdb. Provide a true value or, in case of "createdb", the DSN of the database that you are about to (re-)create.

• skipvalidation

  Disables schema validation checking, e.g., when you know your data is correct and want to save execution time, ususally for add().

• verbose

  Print out progress messages.

• debug

  Pass through debug option to used modules, like BenchmarkAnything::Storage::Backend::SQL.

• separator

  Used for output format flat. Sub entry separator (default=;).

• fb

  Used for output format flat. If set it generates [brackets] around outer arrays (default=0).

• fi

  Used for output format flat. If set it prefixes outer array lines with index.

_output_format

This function converts a data structure into requested output format.

Output formats

The following output formats are allowed:

 yaml   - YAML::Any
 json   - JSON (default)
 xml    - XML::Simple
 ini    - Config::INI::Serializer
 dumper - Data::Dumper (including the leading $VAR1 variable assignment)
 flat   - pragmatic flat output for typical unixish cmdline usage

The 'flat' output format

The flat output format is meant to support typical unixish command line uses. It is not a strong serialization format but works well for simple values nested max 2 levels.

Output looks like this:

Plain values

 Affe
 Tiger
 Birne

Outer hashes

One outer key per line, key at the beginning of line with a colon (:), inner values separated by semicolon ;:

inner scalars:

 coolness:big
 size:average
 Eric:The flat one from the 90s

inner hashes:

Tuples of key=value separated by semicolon ;:

 Affe:coolness=big;size=average
 Zomtec:coolness=bit anachronistic;size=average

inner arrays:

Values separated by semicolon ;:

 Birne:bissel;hinterher;manchmal

Outer arrays

One entry per line, entries separated by semicolon ;:

Outer arrays / inner scalars:

 single report string
 foo
 bar
 baz

Outer arrays / inner hashes:

Tuples of key=value separated by semicolon ;:

 Affe=amazing moves in the jungle;Zomtec=slow talking speed;Birne=unexpected in many respects

Outer arrays / inner arrays:

Entries separated by semicolon ;:

 line A-1;line A-2;line A-3;line A-4;line A-5
 line B-1;line B-2;line B-3;line B-4
 line C-1;line C-2;line C-3

Additional markup for arrays:

 --fb            ... use [brackets] around outer arrays
 --fi            ... prefix outer array lines with index
 --separator=;   ... use given separator between array entries (defaults to ";")

Such additional markup lets outer arrays look like this:

 0:[line A-1;line A-2;line A-3;line A-4;line A-5]
 1:[line B-1;line B-2;line B-3;line B-4]
 2:[line C-1;line C-2;line C-3]
 3:[Affe=amazing moves in the jungle;Zomtec=slow talking speed;Birne=unexpected in many respects]
 4:[single report string]

connect

Connects to the database according to the DB handle from config.

Returns the object to allow chained method calls.

disconnect

Commits and disconnects the current DB handle from the database.

Returns the object to allow chained method calls.

_are_you_sure

Internal method.

Find out if you are really sure. Usually used in "createdb". You need to have provided an option really which matches the DSN of the database that your are about to (re-)create.

If the DSN does not match it asks interactively on STDIN - have this in mind on non-interactive backend programs, like a web application.

createdb

Initializes the DB, as configured by backend and dsn. On the backend this means executing the DROP TABLE and CREATE TABLE statements that come with BenchmarkAnything::Storage::Backend::SQL. Because that is a severe operation it verifies an "are you sure" test, by comparing the parameter really against the DSN from the config, or if that doesn't match, asking interactively on STDIN.

init_workdir

Initializes a work directory ~/.benchmarkanything/ with config files, which should work by default and can be tweaked by the user.

add ($data)

Adds all data points of a BenchmarkAnything structure to the backend store.

search ($query)

Execute a search query against the backend store, currently BenchmarkAnything::Storage::Backend::SQL, and returns the list of found data points, as configured by the search query.

listnames ($pattern)

Returns an array ref with all metric NAMEs. Optionally allows to restrict the search by a SQL LIKE search pattern, allowing % as wildcard.

gc()

Run garbage collector. This cleans up potential garbage that might have piled up, in particular qeued raw results that are already processed but still in the storage.

Initially the garbage collection is made for the queing functionality (see "process_raw_result_queue" until we are confident it is waterproof. However, generally there might be new code arriving in the future for which garbage collection might also make sense, so we provide this function as general entry point to do The Right Thing - whatever that is by that time.

process_raw_result_queue($count)

Works on the queued entries created by add in queuemode=1. It finishes as soon as there are no more unprocessed raw entries, or it processed $count entries (default=10).

getpoint ($value_id)

Returns a single benchmark point with all its key/value pairs.

AUTHOR

Steffen Schwigon <ss5@renormalist.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Steffen Schwigon.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm BenchmarkAnything::Storage::Frontend::Lib

perl -MCPAN -e shell
install BenchmarkAnything::Storage::Frontend::Lib