/ 
Complete-Tcsh-0.030
River stage three • 9 direct dependents • 563 total dependents
/ Complete::Tcsh

NAME

Complete::Tcsh - Completion module for tcsh shell

VERSION

This document describes version 0.030 of Complete::Tcsh (from Perl distribution Complete-Tcsh), released on 2019-12-20.

DESCRIPTION

tcsh allows completion to come from various sources. One of the simplest is from a list of words:

% complete CMDNAME 'p/*/(one two three)/'

Another source is from an external command:

% complete CMDNAME 'p/*/`mycompleter --somearg`/'

The command receives one environment variables COMMAND_LINE (string, raw command-line). Unlike bash, tcsh does not (yet) provide something akin to COMP_POINT in bash. Command is expected to print completion entries, one line at a time.

% cat foo-complete
#!/usr/bin/perl
use Complete::Tcsh qw(parse_cmdline format_completion);
use Complete::Util qw(complete_array_elem);
my ($words, $cword) = @{ parse_cmdline() };
my $res = complete_array_elem(array=>[qw/--help --verbose --version/], word=>$words->[$cword]);
print format_completion($res);

% complete foo 'p/*/`foo-complete`/'
% foo --v<Tab>
--verbose --version

This module provides routines for you to be doing the above.

Also, unlike bash, currently tcsh does not allow delegating completion to a shell function.

FUNCTIONS

format_completion

Usage:

format_completion($completion) -> str|array

Format completion for output (for shell).

tcsh accepts completion reply in the form of one entry per line to STDOUT. Currently the formatting is done using Complete::Bash's format_completion because escaping rule and so on are not yet well defined in tcsh.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • $completion* => hash|array

    Completion answer structure.

    Either an array or hash, as described in Complete.

Return value: Formatted string (or array, if `as` is set to `array`) (str|array)

parse_cmdline

Usage:

parse_cmdline($cmdline) -> array

Parse shell command-line for processing by completion routines.

This function converts COMMAND_LINE (str) given by tcsh to become something like COMP_WORDS (array) and COMP_CWORD (int), like what bash supplies to shell functions. Currently implemented using Complete::Bash's parse_cmdline.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • $cmdline => str

    Command-line, defaults to COMMAND_LINE environment.

Return value: (array)

Return a 2-element array: [$words, $cword]. $words is array of str, equivalent to COMP_WORDS provided by bash to shell functions. $cword is an integer, equivalent to COMP_CWORD provided by bash to shell functions. The word to be completed is at $words->[$cword].

Note that COMP_LINE includes the command name. If you want the command-line arguments only (like in @ARGV), you need to strip the first element from $words and reduce $cword by 1.

HOMEPAGE

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

SOURCE

Source repository is at https://github.com/perlancar/perl-Complete-Tcsh.

BUGS

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

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.

SEE ALSO

Complete

Complete::Bash

tcsh manual.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2015, 2014 by perlancar@cpan.org.

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