/ 
App-karr-0.500
/ App::karr::Role::CliArgs

NAME

App::karr::Role::CliArgs - Role providing option-aware CLI positional-argument parsing

VERSION

version 0.500

DESCRIPTION

This role recovers the real positional arguments from the argv MooX::Cmd echoes back into a command's execute(). Because MooX::Options runs with protect_argv, that argv still holds every original token -- option flags, the values they consumed, and the positionals -- in their original order. positional_args subtracts the option tokens back out (using the consuming command's own _options_data) to yield the positionals, and check_positional_args rejects surplus positionals before a command does any work. A bare -- ends option processing, so everything after it is a positional however option-shaped it looks.

Command classes provide _options_data and _options_config via MooX::Options.

positional_args

my @positional = $self->positional_args($args_ref);

In a command class that composes this role, recovers the real positional arguments from $args_ref -- the argv MooX::Cmd echoes back into execute(), which under protect_argv still holds every original token: recognised option flags, the values they consumed, and the positionals, in their original order. Returns the positionals only, in order, as plain strings; unrecognised dash-prefixed tokens are treated defensively as non-consuming (a genuine typo is already rejected upstream by MooX::Options). A bare -- ends option processing, so every token after it is returned as a positional however option-shaped it looks. Never dies -- an argument list with no positionals returns an empty list.

check_positional_args

$self->check_positional_args($args_ref, $max);

In a command class that composes this role, dies with a usage message ("unexpected extra argument(s): '...'\n", followed by the command's usage string if it has one) when $args_ref resolves to more than $max positionals via "positional_args"; otherwise returns nothing. The message starts with the unexpected extra argument marker "is_usage_error" in App::karr::Error recognises, so bin/karr's central handler exits 2 (ADR 0002), not 1. There is no minimum-arity check here -- a missing required positional is each command's own concern -- this only rejects surplus. Call it before a command does any work: kanban-md's cobra Args validators run before RunE the same way, and karr's batch commands rely on the comma list (parsed by "parse_ids" in App::karr::Role::BoardAccess) as the one and only way to pass more than one id, so a second bare positional is always a mistake rather than an alternate batch syntax.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

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