Complete::Util - General completion routine


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



arrayify_answer(%args) -> array

Make sure we return completion answer in array form.

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

Return value: (array)

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

Given two or more answers, combine them into one.

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)

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

Complete from array.

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

Complete from environment variables.

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

Complete file and directory from local filesystem.

Arguments ('*' denotes required arguments):

  • allow_dot => bool (default: 1)

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

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

  • ci => bool

    Case-insensitive matching.

  • dig_leaf => bool

  • exp_im_path => bool

  • file_regex_filter => re

    Filter shortcut for file regex.

    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

    Only return items matching this filter.

    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

Complete from hash keys.

Arguments ('*' denotes required arguments):

  • ci => bool

  • hash* => hash

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

Return value: (array)

complete_program(%args) -> array

Complete program name found in PATH.

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

Make sure we return completion answer in hash form.

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

  • meta => hash

    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.