Name

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

Version

0.1.5_8 (yyyy-mm-dd)

Synopsis

# In App/bif/command/name.pm
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} );

    $self->start_pager;

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



    return bif_ok('CommandName');
}

Description

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.

Constructor

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

Attributes

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

Methods

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:; 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.
end_pager: 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.
run: 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:
start_work(%opts): Creates a new entry in the work_buffers table.
stop_work(%opts): Ensures nothing is worked, finalizing an open entry in the work_buffers table if one exists.
pause_work(): 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().
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."
save_new_work(%opts): 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:; An invalid uuid example:
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:

Author

Mark Lawrence <nomad@null.net>

Copyright And License

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.