Complete::Util - General completion routine


This document describes version 0.32 of Complete::Util (from Perl distribution Complete-Util), released on 2015-08-11.



arrayify_answer(%args) -> array

{en_US Make sure we return completion answer in array form}.

{en_US This is the reverse of hashify_answer. It accepts a hash or an array. If it receives a hash, will return its words key. }

Arguments ('*' denotes required arguments):

  • arg* => array|hash

    {en_US }.

Return value: (array)

combine_answers($answers, ...) -> hash

{en_US Given two or more answers, combine them into one}.

{en_US This function is useful if you want to provide a completion answer that is gathered from multiple sources. For example, say you are providing completion for the Perl tool cpanm, which accepts a filename (a tarball like *.tar.gz), a directory, or a module name. You can do something like this:

     complete_file(word=>$word, ci=>1),
     complete_module(word=>$word, ci=>1),

If a completion answer has a metadata final set to true, then that answer is used as the final answer without any combining with the other answers. }

Arguments ('*' denotes required arguments):

  • answers* => array[hash|array]

Return value: (hash)

{en_US Return a combined completion answer. Words from each input answer will be combined, order preserved and duplicates removed. The other keys from each answer will be merged. }

complete_array_elem(%args) -> array

{en_US Complete from array}.

{en_US Will sort the resulting completion list, so you don't have to presort the array. }

Arguments ('*' denotes required arguments):

  • array* => array[str]

  • ci => bool

  • exclude => array

  • word* => str (default: "")

Return value: (array)

complete_env(%args) -> array

{en_US Complete from environment variables}.

{en_US On Windows, environment variable names are all converted to uppercase. You can use case-insensitive option (ci) to match against original casing. }

Arguments ('*' denotes required arguments):

  • ci => bool

  • word* => str (default: "")

Return value: (array)

complete_file(%args) -> array

{en_US Complete file and directory from local filesystem}.

Arguments ('*' denotes required arguments):

  • allow_dot => bool (default: 1)

    {en_US If turned off, will not allow "." or ".." in path}.

    {en_US This is most useful when combined with starting_path option to prevent user going up/outside the starting path. }

  • ci => bool

    {en_US Case-insensitive matching}.

  • dig_leaf => bool

  • exp_im_path => bool

  • file_regex_filter => re

    {en_US Filter shortcut for file regex}.

    {en_US This is a shortcut for constructing a filter. So instead of using filter, you use this option. This will construct a filter of including only directories or regular files, and the file must match a regex pattern. This use-case is common. }

  • filter => str|code

    {en_US Only return items matching this filter}.

    {en_US Filter can either be a string or a code.

    For string filter, you can specify a pipe-separated groups of sequences of these characters: f, d, r, w, x. Dash can appear anywhere in the sequence to mean not/negate. An example: f means to only show regular files, -f means only show non-regular files, drwx means to show only directories which are readable, writable, and executable (cd-able). wf|wd means writable regular files or writable directories.

    For code filter, you supply a coderef. The coderef will be called for each item with these arguments: $name. It should return true if it wants the item to be included. }

  • handle_tilde => bool (default: 1)

  • map_case => bool

  • starting_path => str (default: ".")

  • word* => str (default: "")

Return value: (array)

complete_hash_key(%args) -> array

{en_US Complete from hash keys}.

Arguments ('*' denotes required arguments):

  • ci => bool

  • hash* => hash

  • word* => str (default: "")

Return value: (array)

complete_program(%args) -> array

{en_US Complete program name found in PATH}.

{en_US Windows is supported, on Windows PATH will be split using /;/ instead of /:/. }

Arguments ('*' denotes required arguments):

  • ci => bool

  • word* => str (default: "")

Return value: (array)

hashify_answer(%args) -> hash

{en_US Make sure we return completion answer in hash form}.

{en_US This function accepts a hash or an array. If it receives an array, will convert the array into `{words=>$ary}' first to make sure the completion answer is in hash form.

Then will add keys from meta to the hash. }

Arguments ('*' denotes required arguments):

  • arg* => array|hash

    {en_US }.

  • meta => hash

    {en_US Metadata (extra keys) for the hash}.

Return value: (hash)



If you want to do bash tab completion with Perl, take a look at Complete::Bash or Getopt::Long::Complete or Perinci::CmdLine.

Other Complete::* modules.


Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

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.


perlancar <>


This software is copyright (c) 2015 by

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