Steven Haryanto > Perinci-Sub-Complete-0.53 > Perinci::Sub::Complete

Download:
Perinci-Sub-Complete-0.53.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.53   Source  

NAME ^

Perinci::Sub::Complete - Shell completion routines using Rinci metadata

VERSION ^

This document describes version 0.53 of Perinci::Sub::Complete (from Perl distribution Perinci-Sub-Complete), released on 2014-07-02.

SYNOPSIS ^

DESCRIPTION ^

This module provides functionality for doing shell completion. It is meant to be used by Perinci::CmdLine and other Rinci/Riap-based CLI shell like App::riap.

FUNCTIONS ^

complete_arg_elem(%args) -> array

Given argument name and function metadata, complete array element.

Arguments ('*' denotes required arguments):

Return value:

complete_arg_val(%args) -> array

Given argument name and function metadata, complete value.

Arguments ('*' denotes required arguments):

Return value:

complete_cli_arg(%args) -> hash

Complete command-line argument using Rinci function metadata.

Assuming that command-line like:

    foo a b c

is executing some function, and the command-line arguments will be parsed using Perinci::Sub::GetArgs::Argv, then try to complete command-line arguments using information from Rinci metadata.

Algorithm:

  1. If word begins with $, we complete from environment variables and are done.
  2. Call get_args_from_argv() to extract hash arguments from the given words.
  3. Determine whether we need to complete argument name (e.g. --arg<tab>) or argument value (e.g. --arg1 <tab> or <tab> at 1st word where there is an argument specified at pos=0) or an element for an array argument (e.g. a <tab> where there is an argument with spec pos=0 and greedy=1, which means we are trying to complete the value of the second element (index=1) of that argument).
  4. Call custom_completer if defined. If a list of words is returned, we're done. This can be used for, e.g. nested function call, e.g.:

    somecmd --opt-for-cmd ... subcmd --opt-for-subcmd ...

5a. If we are completing argument name, then supply a list of possible argument names, or fallback to completing filenames.

5b. If we are completing argument value, first check if custom_arg_completer is defined. If yes, call that routine. If a list of words is returned, we're done. Fallback to completing argument values from information in Rinci metadata (using complete_arg_val() function).

5c. If we are completing value for an element, first check if custom_arg_element_completer is defined. If yes, call that routine. If a list of words is returned, we're done. Fallback to completing argument values from information in Rinci metadata (using complete_arg_val() function).

Arguments ('*' denotes required arguments):

Return value:

complete_from_schema(%args) -> [status, msg, result, meta]

Complete a value from schema.

Employ some heuristics to complete a value from Sah schema. For example, if schema is [str = in => [qw/new open resolved rejected/]]>, then we can complete from the in clause. Or for something like [int = between => [1, 20]]> we can complete using values from 1 to 20.

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array).

First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

BUGS/LIMITATIONS/TODOS ^

Completing --foo=X not yet supported

Unclosed quoted

Due to parsing limitation (invokes subshell), can't complete unclosed quotes, e.g.

 foo "bar <tab>

while shell function can complete this because they are provided COMP_WORDS and COMP_CWORD by bash.

SEE ALSO ^

Complete

Perinci::CmdLine

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/Perinci-Sub-Complete.

SOURCE ^

Source repository is at https://github.com/sharyanto/perl-Perinci-Sub-Complete.

BUGS ^

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Sub-Complete

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR ^

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2014 by Steven Haryanto.

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

syntax highlighting: