README
1NAME
2 Complete::Sequence - Complete string from a sequence of choices
3
4VERSION
5 This document describes version 0.002 of Complete::Sequence (from Perl
6 distribution Complete-Sequence), released on 2019-12-17.
7
8FUNCTIONS
9 complete_sequence
10 Usage:
11
12 complete_sequence(%args) -> array
13
14 Complete string from a sequence of choices.
15
16 Sometime you want to complete a string where its parts (sequence items)
17 are formed from various pieces. For example, suppose your program
18 "delete-user-data" accepts an argument that is in the form of:
19
20 USERNAME
21 UID "(" "current" ")"
22 UID "(" "historical" ")"
23
24 "EVERYONE"
25
26 Supposed existing users include "budi", "ujang", and "wati" with UID
27 101, 102, 103.
28
29 This can be written as:
30
31 [
32 {
33 alternative => [
34 [qw/budi ujang wati/],
35 {sequence => [
36 [qw/101 102 103/],
37 ["(current)", "(historical)"],
38 ]},
39 "EVERYONE",
40 ],
41 }
42 ]
43
44 When word is empty (''), the offered completion is:
45
46 budi
47 ujang
48 wati
49
50 101
51 102
52 103
53
54 EVERYONE
55
56 When word is 101, the offered completion is:
57
58 101
59 101(current)
60 101(historical)
61
62 When word is "101(h", the offered completion is:
63
64 101(historical)
65
66 This function is not exported by default, but exportable.
67
68 Arguments ('*' denotes required arguments):
69
70 * sequence* => *array*
71
72 A sequence structure is an array of items. An item can be:
73
74 * a scalar/string (a single string to choose from)
75
76 * an array of strings (multiple strings to choose from)
77
78 * a coderef (will be called to extract an item)
79
80 Coderef will be called with $stash argument which contains
81 various information, e.g. the index of the sequence item
82 ("item_index"), the completed parts ("completed_item_words"),
83 the current word ("cur_word"), etc.
84
85 * a hash (another sequence or alternative of items)
86
87 If you want to specify another sub-sequence of items:
88
89 {sequence => [ ... ]} # put items in here
90
91 If you want to specify an alternative of sub-sequences or
92 sub-alternative:
93
94 {alternative => [ ... ]} # put items in here
95
96 * word* => *str* (default: "")
97
98 Word to complete.
99
100 Return value: (array)
101
102ENVIRONMENT
103 COMPLETE_SEQUENCE_TRACE
104 Bool. If set to true, will display more log statements for debugging.
105
106HOMEPAGE
107 Please visit the project's homepage at
108 <https://metacpan.org/release/Complete-Sequence>.
109
110SOURCE
111 Source repository is at
112 <https://github.com/perlancar/perl-Complete-Sequence>.
113
114BUGS
115 Please report any bugs or feature requests on the bugtracker website
116 <https://rt.cpan.org/Public/Dist/Display.html?Name=Complete-Sequence>
117
118 When submitting a bug or request, please include a test-file or a patch
119 to an existing test-file that illustrates the bug or desired feature.
120
121SEE ALSO
122 Complete::Path. Conceptually, "complete_sequence" is similar to
123 "complete_path" from Complete::Path. Except unlike a path, a sequence
124 does not (necessarily) have path separator.
125
126 Complete
127
128AUTHOR
129 perlancar <perlancar@cpan.org>
130
131COPYRIGHT AND LICENSE
132 This software is copyright (c) 2019 by perlancar@cpan.org.
133
134 This is free software; you can redistribute it and/or modify it under
135 the same terms as the Perl 5 programming language system itself.
136
137