view release on metacpan or  search on metacpan

lib/App/karr/Config.pm  view on Meta::CPAN

code that works with the temporary materialized config view directly.

=head2 statuses

  my @statuses = $config->statuses;

Returns the configured status names in board order, accepting both the
mapping form C<< { name => 'in-progress', require_claim => 1 } >> and a bare
string. L</classes> follows the same convention over the classes list.

This is the list L</validate> checks for a minimum of two entries and no
duplicates, and that L</validate_status> and C<status_requires_claim> look a
single name up against.

=head2 status_config

  my $sc = $config->status_config('in-progress');
  # { name => 'in-progress', require_claim => 1 }

Returns the full configuration entry for one status: the mapping as
configured, or a synthesized C<< { name => $name } >> when the board wrote it
as a bare string, or C<undef> when no status by that name exists. Contrast
with L</statuses>, which returns every name and none of the per-status
detail.

This is the one place a single status name is resolved to what the board says
about it; L</status_requires_claim> is a boolean view of the C<require_claim>
key of what it returns, and any further per-status option belongs here too
rather than in a second walk over C<statuses> (ticket #121). Note that the
synthesized entry for a bare string carries nothing but C<name> -- that is
what makes a bare status require no claim.

=head2 priorities

  my @priorities = $config->priorities;

Returns the configured priority names in order, or the built-in C<low medium
high critical> when the config carries none. Unlike L</statuses> and
L</classes>, entries are always bare strings -- kanban-md's priority list has
no per-entry options to carry.

=head2 classes

Returns the configured class-of-service names in board order, accepting both
the mapping form C<< { name => 'expedite' } >> and a bare string, the same way
L</statuses> does. The name is the only thing karr reads off a class entry: a
class decides pick order (L<App::karr::Role::PickRules>) and nothing else, so a
board whose entry carries more -- kanban-md's C<wip_limit> and
C<bypass_column_wip>, say -- keeps those keys stored and unread.

    my @classes = $config->classes;

=head2 claim_timeout

  my $raw = $config->claim_timeout;   # '1h', unparsed

Returns the board's configured claim-expiry duration as the raw string from
the config (C<'1h'> when unset), in kanban-md's C<time.ParseDuration> grammar
-- not seconds. Pass it to L</parse_duration> to get a number. Governs how
long C<karr pick> and the C<move>/C<edit>/C<handoff> claim check
(L<App::karr::Role::ClaimTimeout>) honour an existing C<claimed_by> before
treating it as expired; C<'0s'> disables expiry, exactly as it does for
C<lock_timeout>, and means a claim is honoured until it is released. Distinct
from C<lock_timeout>, which bounds a single C<karr pick> transaction rather
than a whole work session.

=head2 foundation_enabled

Returns true when automated agent runs (L<App::karr::Foundation>) are allowed on
this board. The flag lives in the board config under C<foundation.enabled> and
therefore travels with C<refs/karr/config>; a board that never set it is
enabled.

    if ($config->foundation_enabled) {
        # karr-foundation may drain this board
    }

=head2 foundation_reason

Returns the free-text reason recorded alongside C<foundation.enabled>, or undef
when none was given. Only meaningful while the board is disabled.

    my $why = $config->foundation_reason;

=head2 parse_bool

Coerces a CLI-supplied boolean string to C<1> or C<0>, dying on anything else.
Needed because a bare C<"false"> from the command line is true in Perl.

    my $bool = App::karr::Config->parse_bool('false');   # 0

=head2 parse_duration

Parses a Go C<time.ParseDuration> string into seconds, returning C<undef> when
it is not a duration at all. kanban-md writes C<claim_timeout> in that grammar,
so a compound value such as C<1h30m> has to mean ninety minutes on both sides
of the interop boundary (ticket #78).

    my $secs = App::karr::Config->parse_duration('1h30m');   # 5400
    my $secs = App::karr::Config->parse_duration('7d');      # undef -- no day unit

=head2 validate_status

Dies unless the value is one of the board's configured statuses, returning the
value otherwise so it can be used inline.

    $task->status( $config->validate_status($wanted) );

=head2 validate_status_filter

Dies unless the value is one of the board's configured statuses or C<archived>,
returning the value otherwise so it can be used inline. The one extra name is
C<ARCHIVED_STATUS>: it is a real status karr hardcodes, so a C<--status>
filter may name it even on a board that does not configure a column for it
(ticket #271). L</validate_status> stays the stricter check for a status a task
is moved to.

    $config->validate_status_filter($wanted);

=head2 validate_priority