App::bif - A base class for App::bif::* commands


0.1.5_8 (yyyy-mm-dd)


# In App/bif/command/
use strict;
use warnings;
use parent 'App::bif';

sub run {
    my $self = shift;
    my $db   = $self->db;
    my $data = $db->xarrayref(...);

    die bif_error( 'SomeFailure', 'something failed' )
      if ( $self->{command_option} );


    print $self->render_table( ' r  l  l ',
        [qw/ ID Title Status /], $data, );

    return bif_ok('CommandName');


App::bif provides a context/configuration class for bif commands to inherit from. The above synopsis is the basic template for any bif command. At run time the run method is called.

App::bif sets the encoding of STDOUT and STDIN to utf-8 when it is loaded.


new( opts => $opts )
Initializes the common elements of all bif scripts. Requires the options hashref as provided by OptArgs2 but also returns it.


repo_dir -> Path::Tiny
The location of the current working repository.
user_repo_dir -> Path::Tiny
The location of the user repository.


colours( @colours ) -> @codes
Calls color() from Term::ANSIColor on every string from @colours and returns the results. Returns empty strings if the environment variable $ANSI_COLORS_DISABLED is true (set by the --no-color option).
header( $key, $val, $val2 ) -> ArrayRef
Returns a two or three element arrayref formatted as so:
["$key:", $val, "<$val2>"]
Colours are used to make the $val2 variable darker. The result is generally used when rendering tables by log and show commands.
ago( $epoch, $offset ) -> $string, $timestamp
Uses App::bif::Time::Duration to generate a human readable $string indicating how long ago UTC $epoch was (with $offset in +/- seconds) plus a regular timestamp string.
start_pager([ $rows ])
Start a pager (less, more, etc) on STDOUT using IO::Pager, provided that --no-pager has not been used. The pager handle encoding is set to utf-8. If the optional $rows has been given then the pager will only be started if Term::Size reports the height of the terminal as being less than $rows.
Stops the pager on STDOUT if it was previously started.
user_repo -> Path::Tiny
Returns the location of the user repository directory. Raises a 'UserRepoNotFound' error on failure.
repo -> Path::Tiny
Return the path to the first '.bif' directory found starting from the current working directory and searching upwards. Raises a 'RepoNotFound' error on failure.
db -> Bif::DB::db
Returns a handle for the SQLite database in the current respository (as found by bif_repo). The handle is only good for read operations unless the dbw attribute is used.
You should manually import any DBIx::ThinSQL functions you need only after calling db, in order to keep startup time short for cases such as when the repository is not found.
dbw -> Bif::DB::db
Turns on read-write capability for the db attribute and returns it. After accessing this attribute both the dbw and the db attributes are good for read-write operations.
cmd($class, %attrs)
Loads $class and creates a new object from that class populated with the attributes from $self plus the attributes in the %attrs HASH. This allows the caller to dispatch another command using the same context values (database handles, etc) and continue execution.
dispatch($class, @args)
Loads the bif class $class, creates a new object populated with the attributes from $self plus @args and calls the run() method.
App::bif is responsible for expanding user aliases and redispatching to the actual command. Needs to be documented .... sorry.
user_id -> Int
Returns the node ID for the user (self) identity.
render_table( $format, \@header, \@data, [ $indent ] ) -> Str
Uses Text::FormatTable to construct a table of <@data>, aligned and spaced according to $format, preceded by a @header. If $indent is greater than zero then the entire table is indented by that number of spaces.
prompt_edit( %options ) -> Str
If the environment is interactive this function will invoke an editor and return the result. All comment lines (beginning with '#') are removed. TODO: describe %options.
lprint( $msg ) -> Int
If a pager is not active this method prints $msg to STDOUT and returns the cursor to the beginning of the line. The next call over-writes the previously printed text before printing the new $msg. In this way a continually updating status can be displayed.
get_change( $CID ) -> HashRef
Looks up the change identified by $CID (of the form ID or cID) and returns a hash reference containg the following keys:
An ChangeNotFound error will be raised if the change does not exist.
get_node( $TOKEN, [ @TYPES ] ) -> HashRef
Looks up the node identified by $TOKEN and returns undef or a hash reference containg the following keys:
An error is raised if the matching node is not one of type @TYPES when they are specified.
current_work -> HashRef
Returns a hashref representing the currently open work buffer:
Creates a new entry in the work_buffers table.
Ensures nothing is worked, finalizing an open entry in the work_buffers table if one exists.
Saves the item currently in the work buffer to $App::bif::work_buffer and then calls stop_work() on it. The saved work item can later be restarted with a call to resume_work().
Puts the work item previously saved into $App::bif::work_buffer by pause_work() back into the work buffer with a new start time of "now."
Calls func_new_work taking into account work that crosses the midnight boundary.
begin_change( %args ) -> Int
Creates a new row in the changes table according to the content of %args (must include at least a message value) and the current context (identity). Returns the integer ID of the change.
check( $id ) -> (Bool,Str)
Computes the uuid of the change $id and compares it against the stored uuid value. Returns two variables: the first is a true/false scalar indicating validity, and the second is a human-readable status string.
A valid uuid example:
[u.a83372c(.11)] some command string
An invalid uuid example:
[u.328ea8b(.12)] another command string INVALID
ms2hms($milliseconds) -> '+hh:mm:ss'
Converts the integer $milliseconds into a string representing the hours, minutes and seconds that make up the delta.
ms2hm($milliseconds) -> '+hh:mm'
Converts the integer $milliseconds into a string representing the hours and minutes that make up the delta.
datetime2ms($str) -> ($milliseconds,$tzoffsetms)
Converts a partial date/time string into a UNIX epoch and a timezone offset both in milliseconds, with certain assumptions as to the date. Accepts the following variations:

See Also



Mark Lawrence <>

Copyright And License

Copyright 2013-2017 Mark Lawrence <>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.