The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-shcompgen-0.325
River stage one • 4 direct dependents • 4 total dependents
2 ++
/ App::shcompgen

NAME

App::shcompgen - Generate shell completion scripts

VERSION

This document describes version 0.325 of App::shcompgen (from Perl distribution App-shcompgen), released on 2022-10-07.

FUNCTIONS

detect_prog

Usage:

 detect_prog(%args) -> [$status_code, $reason, $payload, \%result_meta]

Detect a program.

This function is not exported.

Arguments ('*' denotes required arguments):

  • prog* => str

  • shell => str

    Override guessing and select shell manually.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

generate

Usage:

 generate(%args) -> [$status_code, $reason, $payload, \%result_meta]

Generate shell completion scripts for detectable programs.

This function is not exported.

Arguments ('*' denotes required arguments):

  • bash_global_dir => array[str] (default: ["/etc/bash/completions"])

    Directory to put completions scripts.

  • bash_per_user_dir => array[str]

    Directory to put completions scripts.

  • fish_global_dir => array[str] (default: ["/etc/fish/completions"])

    Directory to put completions scripts.

  • fish_per_user_dir => array[str]

    Directory to put completions scripts.

  • global => bool

    Use global completions directory.

    Shell has global (system-wide) completions directory as well as per-user. For example, in fish the global directory is by default /etc/fish/completions and the per-user directory is ~/.config/fish/completions.

    By default, if running as root, the global is chosen. And if running as normal user, per-user directory is chosen. Using --global or --per-user overrides that and manually select which.

  • helper_global_dir => str (default: "/etc/shcompgen/helpers")

    Directory to put helper scripts.

  • helper_per_user_dir => str

    Directory to put helper scripts.

  • per_option => bool

    Create per-option completion script if possible.

    If set to true, then attempt to create completion script that register each option. This creates nicer completion in some shells, e.g. fish and zsh. For example, option description can be shown.

    This is possible for only some types of scripts, e.g. Perinci::CmdLine- (that does not have subcommands) or Getopt::Long::Descriptive-based ones.

  • prog => array[str]

    Program(s) to generate completion for.

    Can contain path (e.g. ../foo) or a plain word (foo) in which case will be searched from PATH.

  • remove => bool

    Remove completion for script that (now) is not detected to have completion.

    The default behavior is to simply ignore existing completion script if the program is not detected to have completion. When the remove setting is enabled, however, such existing completion script will be removed.

  • replace => bool

    Replace existing script.

    The default behavior is to skip if an existing completion script exists.

  • shell => str

    Override guessing and select shell manually.

  • stdout => bool

    Output completion script to STDOUT.

  • tcsh_global_dir => array[str] (default: ["/etc/tcsh/completions"])

    Directory to put completions scripts.

  • tcsh_per_user_dir => array[str]

    Directory to put completions scripts.

  • zsh_global_dir => array[str] (default: ["/usr/local/share/zsh/site-functions"])

    Directory to put completions scripts.

  • zsh_per_user_dir => array[str]

    Directory to put completions scripts.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

guess_shell

Usage:

 guess_shell() -> [$status_code, $reason, $payload, \%result_meta]

Guess running shell.

This function is not exported.

No arguments.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

init

Usage:

 init(%args) -> [$status_code, $reason, $payload, \%result_meta]

Initialize shcompgen.

This subcommand creates the completion directories and initialization shell script, as well as run generate.

This function is not exported.

Arguments ('*' denotes required arguments):

  • bash_global_dir => array[str] (default: ["/etc/bash/completions"])

    Directory to put completions scripts.

  • bash_per_user_dir => array[str]

    Directory to put completions scripts.

  • fish_global_dir => array[str] (default: ["/etc/fish/completions"])

    Directory to put completions scripts.

  • fish_per_user_dir => array[str]

    Directory to put completions scripts.

  • global => bool

    Use global completions directory.

    Shell has global (system-wide) completions directory as well as per-user. For example, in fish the global directory is by default /etc/fish/completions and the per-user directory is ~/.config/fish/completions.

    By default, if running as root, the global is chosen. And if running as normal user, per-user directory is chosen. Using --global or --per-user overrides that and manually select which.

  • helper_global_dir => str (default: "/etc/shcompgen/helpers")

    Directory to put helper scripts.

  • helper_per_user_dir => str

    Directory to put helper scripts.

  • per_option => bool

    Create per-option completion script if possible.

    If set to true, then attempt to create completion script that register each option. This creates nicer completion in some shells, e.g. fish and zsh. For example, option description can be shown.

    This is possible for only some types of scripts, e.g. Perinci::CmdLine- (that does not have subcommands) or Getopt::Long::Descriptive-based ones.

  • shell => str

    Override guessing and select shell manually.

  • tcsh_global_dir => array[str] (default: ["/etc/tcsh/completions"])

    Directory to put completions scripts.

  • tcsh_per_user_dir => array[str]

    Directory to put completions scripts.

  • zsh_global_dir => array[str] (default: ["/usr/local/share/zsh/site-functions"])

    Directory to put completions scripts.

  • zsh_per_user_dir => array[str]

    Directory to put completions scripts.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

list

Usage:

 list(%args) -> [$status_code, $reason, $payload, \%result_meta]

List all shell completion scripts generated by this script.

This function is not exported.

Arguments ('*' denotes required arguments):

  • bash_global_dir => array[str] (default: ["/etc/bash/completions"])

    Directory to put completions scripts.

  • bash_per_user_dir => array[str]

    Directory to put completions scripts.

  • detail => bool

  • fish_global_dir => array[str] (default: ["/etc/fish/completions"])

    Directory to put completions scripts.

  • fish_per_user_dir => array[str]

    Directory to put completions scripts.

  • global => bool

    Use global completions directory.

    Shell has global (system-wide) completions directory as well as per-user. For example, in fish the global directory is by default /etc/fish/completions and the per-user directory is ~/.config/fish/completions.

    By default, if running as root, the global is chosen. And if running as normal user, per-user directory is chosen. Using --global or --per-user overrides that and manually select which.

  • helper_global_dir => str (default: "/etc/shcompgen/helpers")

    Directory to put helper scripts.

  • helper_per_user_dir => str

    Directory to put helper scripts.

  • per_option => bool

    Create per-option completion script if possible.

    If set to true, then attempt to create completion script that register each option. This creates nicer completion in some shells, e.g. fish and zsh. For example, option description can be shown.

    This is possible for only some types of scripts, e.g. Perinci::CmdLine- (that does not have subcommands) or Getopt::Long::Descriptive-based ones.

  • shell => str

    Override guessing and select shell manually.

  • tcsh_global_dir => array[str] (default: ["/etc/tcsh/completions"])

    Directory to put completions scripts.

  • tcsh_per_user_dir => array[str]

    Directory to put completions scripts.

  • zsh_global_dir => array[str] (default: ["/usr/local/share/zsh/site-functions"])

    Directory to put completions scripts.

  • zsh_per_user_dir => array[str]

    Directory to put completions scripts.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

remove

Usage:

 remove(%args) -> [$status_code, $reason, $payload, \%result_meta]

Remove shell completion scripts generated by this script.

This function is not exported.

Arguments ('*' denotes required arguments):

  • bash_global_dir => array[str] (default: ["/etc/bash/completions"])

    Directory to put completions scripts.

  • bash_per_user_dir => array[str]

    Directory to put completions scripts.

  • fish_global_dir => array[str] (default: ["/etc/fish/completions"])

    Directory to put completions scripts.

  • fish_per_user_dir => array[str]

    Directory to put completions scripts.

  • global => bool

    Use global completions directory.

    Shell has global (system-wide) completions directory as well as per-user. For example, in fish the global directory is by default /etc/fish/completions and the per-user directory is ~/.config/fish/completions.

    By default, if running as root, the global is chosen. And if running as normal user, per-user directory is chosen. Using --global or --per-user overrides that and manually select which.

  • helper_global_dir => str (default: "/etc/shcompgen/helpers")

    Directory to put helper scripts.

  • helper_per_user_dir => str

    Directory to put helper scripts.

  • per_option => bool

    Create per-option completion script if possible.

    If set to true, then attempt to create completion script that register each option. This creates nicer completion in some shells, e.g. fish and zsh. For example, option description can be shown.

    This is possible for only some types of scripts, e.g. Perinci::CmdLine- (that does not have subcommands) or Getopt::Long::Descriptive-based ones.

  • prog => array[str]

    Program(s) to remove completion script of.

    Can contain path (e.g. ../foo) or a plain word (foo) in which case will be searched from PATH.

  • shell => str

    Override guessing and select shell manually.

  • tcsh_global_dir => array[str] (default: ["/etc/tcsh/completions"])

    Directory to put completions scripts.

  • tcsh_per_user_dir => array[str]

    Directory to put completions scripts.

  • zsh_global_dir => array[str] (default: ["/usr/local/share/zsh/site-functions"])

    Directory to put completions scripts.

  • zsh_per_user_dir => array[str]

    Directory to put completions scripts.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

HOMEPAGE

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

SOURCE

Source repository is at https://github.com/perlancar/perl-App-shcompgen.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2020, 2018, 2017, 2016, 2015, 2014 by perlancar <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.

BUGS

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

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.