polyctl 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,686 @@
1
+ """Shell completion: `polyctl completion bash|zsh|fish|powershell` prints a script that completes polyctl (SHELL-COMPLETION).
2
+
3
+ A part of src/polyctl/cli.py, run in its namespace by `_part` as the parts moved out of it are (#44); it is not
4
+ importable on its own. The script is generated from build_parser() each time the command runs, so it holds the
5
+ commands, the long options and the fixed choices of the polyctl that printed it, and completing a word runs no
6
+ program, polyctl included, and reads no project. Every word taken from the parser is written into the script as a
7
+ literal quoted for its shell, and every word the script completes is quoted again on the command line, so an
8
+ option or a choice holding a quote, a `$` or a backquote can neither break the script nor run anything.
9
+ """
10
+
11
+ COMPLETION_SHELLS = ("bash", "zsh", "fish", "powershell")
12
+ COMPLETION_WIDTH = 100 # the column a generated line breaks before, where a word fits
13
+
14
+
15
+ def cmd_completion(cfg, args):
16
+ """Print the completion script for one shell, generated from this polyctl's own command line (SHELL-COMPLETION).
17
+
18
+ It goes to standard output with line feeds alone on every platform: bash, zsh and fish read a carriage
19
+ return as part of a word, and PowerShell reads either. An unknown shell never reaches here: the parser
20
+ refuses it, exit 2, naming the four.
21
+ """
22
+ script = completion_script(build_parser(), args.shell)
23
+ try:
24
+ sys.stdout.reconfigure(newline="\n")
25
+ except (AttributeError, OSError, ValueError): # a stream that is not a text file: written as it is
26
+ pass
27
+ sys.stdout.write(script)
28
+ sys.stdout.flush()
29
+ return 0
30
+
31
+
32
+ def completion_script(parser, shell):
33
+ """The completion script for `shell`, one of COMPLETION_SHELLS, generated from an argparse parser (SHELL-COMPLETION)."""
34
+ writers = {"bash": _completion_bash, "zsh": _completion_zsh, "fish": _completion_fish,
35
+ "powershell": _completion_powershell}
36
+ if shell not in writers:
37
+ raise ValueError(f"no completion script for {shell!r}: one of {', '.join(COMPLETION_SHELLS)}")
38
+ return "\n".join(writers[shell](_completion_model(parser))) + "\n"
39
+
40
+
41
+ # ---- what the parser offers --------------------------------------------------------------------------------------
42
+
43
+ def _completable(word):
44
+ """Whether a word can be offered: not empty, and no control character, which no shell lists safely and fish
45
+ takes for the end of a completion (SHELL-COMPLETION). A word polyctl cannot offer is left out of the script."""
46
+ return bool(word) and not any(ord(ch) < 32 or 127 <= ord(ch) < 160 for ch in word)
47
+
48
+
49
+ def _completion_choices(action):
50
+ """The choices argparse declares for an action, as the words a person types, once each; [] for none."""
51
+ if action.choices is None or action.help == argparse.SUPPRESS:
52
+ return []
53
+ try:
54
+ words = [str(choice) for choice in action.choices]
55
+ except TypeError: # a container that answers `in` and cannot be listed
56
+ return []
57
+ return [word for word in dict.fromkeys(words) if _completable(word)]
58
+
59
+
60
+ def _completion_arity(nargs):
61
+ """How many words an option takes past its own, as the scripts read it: "1" for the next word alone, None for
62
+ none, and otherwise "?" for one that does not begin with -, "*" for each up to one that does, "..." for every
63
+ word after it, or the count (LEADS-OPS)."""
64
+ if nargs == 0:
65
+ return None
66
+ if nargs is None or nargs == 1:
67
+ return "1"
68
+ if nargs == "?":
69
+ return "?"
70
+ if nargs in ("*", "+"):
71
+ return "*"
72
+ if nargs in (argparse.REMAINDER, argparse.PARSER):
73
+ return "..."
74
+ return str(nargs) if isinstance(nargs, int) and nargs > 1 else "1"
75
+
76
+
77
+ def _completion_words(parser):
78
+ """What one parser offers, as the scripts read it (SHELL-COMPLETION).
79
+
80
+ {options, valued, arity, values, slots, repeat}: its long options, less those whose help is suppressed;
81
+ every option string that takes the next word alone as its value, and how many words each other one that
82
+ takes any takes, suppressed ones too, so no word an option takes is counted as an argument; the choices of
83
+ each option that declares them; the choices of each positional word in order, None where it has none; and
84
+ whether the last slot takes every word after it, as nargs *, + and ... do. A subcommand's name is one slot,
85
+ whose choices are the subcommands.
86
+
87
+ An option's words were one bit, takes the next word or not: the word after `polyctl review --paths a.py` was
88
+ counted as the command's first positional word, and `polyctl review`'s actions offered for a path (LEADS-OPS).
89
+ """
90
+ options, valued, arity, values, slots, repeat = set(), set(), {}, {}, [], False
91
+ for action in parser._actions:
92
+ choices = _completion_choices(action)
93
+ if action.option_strings:
94
+ takes = _completion_arity(action.nargs)
95
+ for flag in filter(_completable, action.option_strings):
96
+ if takes == "1":
97
+ valued.add(flag)
98
+ elif takes:
99
+ arity[flag] = takes
100
+ if takes and choices:
101
+ values[flag] = choices
102
+ if flag.startswith("--") and action.help != argparse.SUPPRESS:
103
+ options.add(flag)
104
+ elif not repeat:
105
+ if action.nargs in ("*", "+", argparse.REMAINDER):
106
+ slots.append(choices or None)
107
+ repeat = True
108
+ else:
109
+ slots.extend([choices or None] * (action.nargs if isinstance(action.nargs, int) else 1))
110
+ return {"options": sorted(options), "valued": sorted(valued), "arity": arity, "values": values, "slots": slots,
111
+ "repeat": repeat}
112
+
113
+
114
+ def _completion_model(parser):
115
+ """{"": what the top level offers, name: what each subcommand offers} (SHELL-COMPLETION).
116
+
117
+ The subcommands are the action whose choices map each name to its parser, as tests/test_docs_commands.py
118
+ finds them. A name is never empty, so the empty key stands for the words before any command.
119
+ """
120
+ model = {"": _completion_words(parser)}
121
+ for action in parser._actions:
122
+ if isinstance(action.choices, dict):
123
+ for name, command in action.choices.items():
124
+ if _completable(name) and name not in model:
125
+ model[name] = _completion_words(command)
126
+ return model
127
+
128
+
129
+ def _completion_arms(model):
130
+ """(command, kind, key, words) for every list a script holds, kind one of valued, arity, options, values and
131
+ slot.
132
+
133
+ key is the option for arity and values, the slot's index for slot, and None otherwise; a slot that takes every
134
+ word after it has the key (index, "and after"). An arity's words are one, what _completion_arity says.
135
+ """
136
+ arms = []
137
+ for name, words in model.items():
138
+ if words["valued"]:
139
+ arms.append((name, "valued", None, words["valued"]))
140
+ arms.extend((name, "arity", flag, [takes]) for flag, takes in sorted(words["arity"].items()))
141
+ if words["options"]:
142
+ arms.append((name, "options", None, words["options"]))
143
+ arms.extend((name, "values", flag, choices) for flag, choices in sorted(words["values"].items()))
144
+ last = len(words["slots"]) - 1
145
+ arms.extend((name, "slot", (index, "and after") if words["repeat"] and index == last else index, choices)
146
+ for index, choices in enumerate(words["slots"]) if choices)
147
+ return arms
148
+
149
+
150
+ def _completion_wrapped(tokens, indent, more=None):
151
+ """The tokens on lines that start with `indent`, and `more` after the first where given, a line broken before
152
+ a token that would pass COMPLETION_WIDTH."""
153
+ lines, line = [], ""
154
+ for token in tokens:
155
+ lead = more if lines and more else indent
156
+ if line and len(lead) + len(line) + 1 + len(token) > COMPLETION_WIDTH:
157
+ lines.append(lead + line)
158
+ line = ""
159
+ line += (" " if line else "") + token
160
+ if line:
161
+ lines.append((more if lines and more else indent) + line)
162
+ return lines
163
+
164
+
165
+ def _completion_header(shell, name, install, notes=()):
166
+ """The comment a script opens with: what it is, that it goes stale with polyctl, and how it is installed."""
167
+ return [f"# {name} completion for polyctl, printed by `polyctl completion {shell}` (SHELL-COMPLETION).",
168
+ "# It holds the commands, the long options and the fixed choices of the polyctl that printed it:",
169
+ "# print it again after updating polyctl. Completing a word runs no program. Install it with",
170
+ *(f"# {line}" for line in install), *(f"# {line}" for line in notes)]
171
+
172
+
173
+ # ---- bash and zsh --------------------------------------------------------------------------------------------------
174
+
175
+ def _completion_sh_quote(word):
176
+ """A single-quoted literal that bash and zsh read back as exactly `word`: nothing in it is expanded."""
177
+ return "'" + word.replace("'", "'\\''") + "'"
178
+
179
+
180
+ def _completion_sh_functions(model):
181
+ """The functions the bash and the zsh script share, each setting the array `reply` (SHELL-COMPLETION).
182
+
183
+ `_polyctl_valued COMMAND` sets the option strings that take the next word alone as their value, `_polyctl_arity
184
+ COMMAND OPTION` how many words another option takes (LEADS-OPS), `_polyctl_options COMMAND` the long options,
185
+ `_polyctl_values COMMAND OPTION` an option's choices and `_polyctl_arguments COMMAND SLOT` a positional word's;
186
+ COMMAND is empty before the command. Each selects by `case` on quoted patterns, which both shells match as
187
+ written, and sets reply from quoted literals, so a word is never read as syntax.
188
+ """
189
+ q, arms = _completion_sh_quote, _completion_arms(model)
190
+
191
+ def assign(pattern, words, indent, guard=""):
192
+ literals = [q(word) for word in words]
193
+ line = f"{indent}{pattern}) {guard}reply=({' '.join(literals)});;"
194
+ if len(line) <= COMPLETION_WIDTH:
195
+ return [line]
196
+ return [f"{indent}{pattern}) {guard}reply=("] + _completion_wrapped(literals, indent + " ") + [f"{indent});;"]
197
+
198
+ def function(name, what, kind, keyed):
199
+ lines = [f"# {what}", f"{name}() {{", " reply=()", " case $1 in"]
200
+ for command in dict.fromkeys(arm[0] for arm in arms if arm[1] == kind):
201
+ mine = [arm for arm in arms if arm[:2] == (command, kind)]
202
+ if not keyed:
203
+ lines += assign(q(command), mine[0][3], " ")
204
+ continue
205
+ lines += [f" {q(command)})", " case $2 in"]
206
+ for _, _, key, words in mine:
207
+ if kind in ("values", "arity"):
208
+ lines += assign(q(key), words, " ")
209
+ elif isinstance(key, tuple):
210
+ lines += assign("*", words, " ", f'[ "$2" -ge {key[0]} ] && ')
211
+ else:
212
+ lines += assign(str(key), words, " ")
213
+ lines += [" esac;;"]
214
+ return lines + [" esac", "}", ""]
215
+
216
+ return (function("_polyctl_valued", "The option strings of command $1 that take the next word alone as their value.",
217
+ "valued", False)
218
+ + function("_polyctl_arity", "How many words option $2 of command $1 takes, when not the next alone: a "
219
+ "count, ?, * or ...", "arity", True)
220
+ + function("_polyctl_options", "The long options of command $1; before any command, those of polyctl itself.",
221
+ "options", False)
222
+ + function("_polyctl_values", "The choices option $2 of command $1 declares.", "values", True)
223
+ + function("_polyctl_arguments", "The choices of positional word $2 (from 0) of command $1; before any "
224
+ "command, the commands.", "slot", True))
225
+
226
+
227
+ _COMPLETION_SH_TAKES_VALUE = r'''# Whether word $2 takes the next word alone as its value, among the words of command $1 or before any.
228
+ _polyctl_takes_value() {
229
+ local option
230
+ _polyctl_valued "$1"
231
+ for option in "${reply[@]}"; do
232
+ [[ $option == "$2" ]] && return 0
233
+ done
234
+ return 1
235
+ }
236
+ '''
237
+
238
+ # Readline quotes the words a completion function offers only when it is told they are file names (`-o
239
+ # filenames`), which `complete -o default -F _polyctl polyctl` does not say: offered as %q printed it, `a\ b` was read
240
+ # back as one word, `a b`, and offered bare, as two (LEADS-OPS).
241
+ _COMPLETION_BASH = r'''
242
+ # The words before the cursor name the command, then the positional word the cursor is on, or the
243
+ # option whose value it is. With = in COMP_WORDBREAKS, bash splits --option=value into three words.
244
+ # An option takes up to `take` words after it; one that `stops` takes none that begins with -.
245
+ _polyctl() {
246
+ local cur="${COMP_WORDS[COMP_CWORD]}" cmd= rest= option= stops= word= quoted= i=1 slot=0 n=0 take=0
247
+ local -a reply
248
+ COMPREPLY=()
249
+ while [[ $i -lt $COMP_CWORD ]]; do
250
+ word="${COMP_WORDS[i]}"
251
+ if [[ -z $rest && -n $cmd && $word == "--" ]]; then
252
+ rest=1
253
+ elif [[ -z $rest && $word == -?* ]]; then
254
+ take=0
255
+ stops=
256
+ if [[ ${COMP_WORDS[i+1]-} == "=" ]]; then
257
+ take=2
258
+ elif _polyctl_takes_value "$cmd" "$word"; then
259
+ take=1
260
+ else
261
+ _polyctl_arity "$cmd" "$word"
262
+ case ${reply[0]-} in
263
+ '') ;;
264
+ '?') take=1 stops=1;;
265
+ '*') take=$COMP_CWORD stops=1;;
266
+ '...') take=$COMP_CWORD;;
267
+ *) take=${reply[0]};;
268
+ esac
269
+ fi
270
+ n=1
271
+ while [[ $n -le $take && $((i + n)) -lt $COMP_CWORD ]]; do
272
+ [[ -n $stops && ${COMP_WORDS[i+n]} == -?* ]] && break
273
+ n=$((n + 1))
274
+ done
275
+ if [[ $n -le $take && $((i + n)) -eq $COMP_CWORD ]]; then
276
+ option="$word"
277
+ break
278
+ fi
279
+ i=$((i + n - 1))
280
+ elif [[ -z $cmd ]]; then
281
+ cmd="$word"
282
+ else
283
+ slot=$((slot + 1))
284
+ fi
285
+ i=$((i + 1))
286
+ done
287
+ if [[ -n $option && ( -z $stops || $cur != -* ) ]]; then
288
+ [[ $cur == "=" ]] && cur=
289
+ _polyctl_values "$cmd" "$option"
290
+ elif [[ -z $rest && $cur == -* ]]; then
291
+ _polyctl_options "$cmd"
292
+ else
293
+ _polyctl_arguments "$cmd" "$slot"
294
+ fi
295
+ # Each word that begins with what is typed, quoted so the command line reads it back as it is;
296
+ # %q leaves a leading ~ bare in older bash, where the command line would expand it.
297
+ for word in "${reply[@]}"; do
298
+ if [[ $word == "$cur"* ]]; then
299
+ printf -v quoted %q "$word"
300
+ [[ $quoted == "~"* ]] && quoted="\\$quoted"
301
+ COMPREPLY+=("$quoted")
302
+ fi
303
+ done
304
+ }
305
+
306
+ complete -o default -F _polyctl polyctl
307
+ '''
308
+
309
+ _COMPLETION_ZSH = r'''
310
+ # The words before the cursor name the command, then the positional word the cursor is on, or the
311
+ # option whose value it is. An option takes up to `take` words after it; one that `stops` takes none
312
+ # that begins with -.
313
+ _polyctl() {
314
+ local cmd= rest= option= stops= word=
315
+ local -a reply
316
+ local -i i=2 slot=0 n=0 take=0
317
+ while (( i < CURRENT )); do
318
+ word="${words[i]}"
319
+ if [[ -z $rest && -n $cmd && $word == "--" ]]; then
320
+ rest=1
321
+ elif [[ -z $rest && $word == -?* ]]; then
322
+ take=0
323
+ stops=
324
+ if _polyctl_takes_value "$cmd" "$word"; then
325
+ take=1
326
+ else
327
+ _polyctl_arity "$cmd" "$word"
328
+ case ${reply[1]-} in
329
+ '') ;;
330
+ '?') take=1 stops=1;;
331
+ '*') take=CURRENT stops=1;;
332
+ '...') take=CURRENT;;
333
+ *) take=${reply[1]};;
334
+ esac
335
+ fi
336
+ n=1
337
+ while (( n <= take && i + n < CURRENT )); do
338
+ [[ -n $stops && ${words[i+n]} == -?* ]] && break
339
+ n=$(( n + 1 ))
340
+ done
341
+ if (( n <= take && i + n == CURRENT )); then
342
+ option="$word"
343
+ break
344
+ fi
345
+ i=$(( i + n - 1 ))
346
+ elif [[ -z $cmd ]]; then
347
+ cmd="$word"
348
+ else
349
+ slot=$(( slot + 1 ))
350
+ fi
351
+ i=$(( i + 1 ))
352
+ done
353
+ if [[ -z $option && -z $rest && $PREFIX == -?*=* ]]; then
354
+ option="${PREFIX%%=*}"
355
+ stops=
356
+ compset -P 1 '*='
357
+ fi
358
+ if [[ -n $option && ( -z $stops || $PREFIX != -* ) ]]; then
359
+ _polyctl_values "$cmd" "$option"
360
+ elif [[ -z $rest && $PREFIX == -* ]]; then
361
+ _polyctl_options "$cmd"
362
+ else
363
+ _polyctl_arguments "$cmd" "$slot"
364
+ fi
365
+ # compadd keeps the words that match what is typed and quotes the one it inserts; with none, files.
366
+ if (( ${#reply} )); then
367
+ compadd -- "${reply[@]}"
368
+ else
369
+ _files
370
+ fi
371
+ }
372
+
373
+ # Loaded from fpath, this file is the body of _polyctl, and runs it; sourced, it registers _polyctl for polyctl.
374
+ if [[ ${funcstack[1]} == _polyctl ]]; then
375
+ _polyctl "$@"
376
+ else
377
+ compdef _polyctl polyctl
378
+ fi
379
+ '''
380
+
381
+
382
+ def _completion_bash(model):
383
+ return (_completion_header("bash", "bash", ["mkdir -p ~/.local/share/bash-completion/completions",
384
+ "polyctl completion bash > ~/.local/share/bash-completion/completions/polyctl"],
385
+ ["which bash-completion loads the first time polyctl is completed; without that package,",
386
+ "source the file from ~/.bashrc."])
387
+ + [""] + _completion_sh_functions(model) + _COMPLETION_SH_TAKES_VALUE.splitlines()
388
+ + _COMPLETION_BASH.splitlines())
389
+
390
+
391
+ def _completion_zsh(model):
392
+ return (["#compdef polyctl"]
393
+ + _completion_header("zsh", "zsh", ["mkdir -p ~/.zfunc && polyctl completion zsh > ~/.zfunc/_polyctl"],
394
+ ["and, in ~/.zshrc before compinit runs: fpath=(~/.zfunc $fpath)"])
395
+ + [""] + _completion_sh_functions(model) + _COMPLETION_SH_TAKES_VALUE.splitlines()
396
+ + _COMPLETION_ZSH.splitlines())
397
+
398
+
399
+ # ---- fish ----------------------------------------------------------------------------------------------------------
400
+
401
+ def _completion_fish_quote(word):
402
+ """A single-quoted fish literal: fish reads back exactly `word`, escaping only a backslash and a quote there."""
403
+ return "'" + word.replace("\\", "\\\\").replace("'", "\\'") + "'"
404
+
405
+
406
+ def _completion_fish_functions(model):
407
+ """fish functions that print, one a line, what _completion_sh_functions sets (SHELL-COMPLETION).
408
+
409
+ fish has no case that matches literally - its switch reads * and ? in a quoted pattern - so each function
410
+ is a chain of `contains`, which compares strings exactly, and prints quoted literals with printf.
411
+ """
412
+ q, arms = _completion_fish_quote, _completion_arms(model)
413
+
414
+ def printed(words, indent):
415
+ literals = [q(word) for word in words]
416
+ lines = _completion_wrapped(["printf", "'%s\\n'"] + literals, indent, indent + " ")
417
+ return [line + " \\" for line in lines[:-1]] + lines[-1:]
418
+
419
+ def function(name, parameters, kind):
420
+ lines, first = [f"function {name} --argument-names {parameters}"], True
421
+ for command, _, key, words in (arm for arm in arms if arm[1] == kind):
422
+ test = f'contains -- "$cmd" {q(command)}'
423
+ if kind in ("values", "arity"):
424
+ test += f'; and contains -- "$option" {q(key)}'
425
+ elif kind == "slot":
426
+ test += f'; and test "$slot" -ge {key[0]}' if isinstance(key, tuple) else f'; and test "$slot" -eq {key}'
427
+ lines += [(" if " if first else " else if ") + test] + printed(words, " ")
428
+ first = False
429
+ return lines + ([] if first else [" end"]) + ["end", ""]
430
+
431
+ return (["# The option strings of a command that take the next word alone as their value."]
432
+ + function("__polyctl_valued", "cmd", "valued")
433
+ + ["# How many words an option of a command takes, when not the next alone: a count, ?, * or ..."]
434
+ + function("__polyctl_arity", "cmd option", "arity")
435
+ + ["# The long options of a command; before any command, those of polyctl itself."]
436
+ + function("__polyctl_options", "cmd", "options")
437
+ + ["# The choices an option of a command declares."]
438
+ + function("__polyctl_values", "cmd option", "values")
439
+ + ["# The choices of a positional word (from 0) of a command; before any command, the commands."]
440
+ + function("__polyctl_arguments", "cmd slot", "slot"))
441
+
442
+
443
+ _COMPLETION_FISH = r'''# What completes the word at the cursor: the command, a long option, or the choices of an option or a
444
+ # positional word. It fails when there is none, and fish then completes files. An option takes up to
445
+ # `take` words after it; one that `stops` takes none that begins with -.
446
+ function __polyctl_candidates
447
+ set -l tokens (commandline -opc)
448
+ set -l cur (commandline -ct)
449
+ set -l cmd ''
450
+ set -l rest ''
451
+ set -l option ''
452
+ set -l stops ''
453
+ set -l prefix ''
454
+ set -l slot 0
455
+ set -l take 0
456
+ set -l n 0
457
+ set -l i 2
458
+ while test $i -le (count $tokens)
459
+ set -l word $tokens[$i]
460
+ if test -z "$rest"; and test -n "$cmd"; and contains -- "$word" '--'
461
+ set rest 1
462
+ else if test -z "$rest"; and string match -q -- '-?*' "$word"
463
+ set take 0
464
+ set stops ''
465
+ if contains -- "$word" (__polyctl_valued "$cmd")
466
+ set take 1
467
+ else
468
+ set -l arity (__polyctl_arity "$cmd" "$word")
469
+ if test "$arity" = '?'
470
+ set take 1
471
+ set stops 1
472
+ else if test "$arity" = '*'
473
+ set take (count $tokens)
474
+ set stops 1
475
+ else if test "$arity" = '...'
476
+ set take (count $tokens)
477
+ else if test -n "$arity"
478
+ set take $arity
479
+ end
480
+ end
481
+ set n 1
482
+ while test $n -le $take; and test (math $i + $n) -le (count $tokens)
483
+ if test -n "$stops"; and string match -q -- '-?*' $tokens[(math $i + $n)]
484
+ break
485
+ end
486
+ set n (math $n + 1)
487
+ end
488
+ if test $n -le $take; and test (math $i + $n) -gt (count $tokens)
489
+ set option "$word"
490
+ break
491
+ end
492
+ set i (math $i + $n - 1)
493
+ else if test -z "$cmd"
494
+ set cmd "$word"
495
+ else
496
+ set slot (math $slot + 1)
497
+ end
498
+ set i (math $i + 1)
499
+ end
500
+ if test -z "$option"; and test -z "$rest"; and string match -q -- '-?*=*' "$cur"
501
+ set option (string split -m 1 -- '=' "$cur")[1]
502
+ set prefix "$option="
503
+ set stops ''
504
+ end
505
+ set -l reply
506
+ if test -n "$option"; and begin; test -z "$stops"; or not string match -q -- '-*' "$cur"; end
507
+ set reply (__polyctl_values "$cmd" "$option")
508
+ else if test -z "$rest"; and string match -q -- '-*' "$cur"
509
+ set reply (__polyctl_options "$cmd")
510
+ else
511
+ set reply (__polyctl_arguments "$cmd" "$slot")
512
+ end
513
+ set -q reply[1]; or return 1
514
+ printf '%s\n' "$prefix"$reply
515
+ end
516
+
517
+ complete -c polyctl -n '__polyctl_candidates >/dev/null' -f -a '(__polyctl_candidates)'
518
+ '''
519
+
520
+
521
+ def _completion_fish(model):
522
+ return (_completion_header("fish", "fish", ["polyctl completion fish > ~/.config/fish/completions/polyctl.fish"])
523
+ + [""] + _completion_fish_functions(model) + _COMPLETION_FISH.splitlines())
524
+
525
+
526
+ # ---- PowerShell ----------------------------------------------------------------------------------------------------
527
+
528
+ # PowerShell reads each of these as a single quote, and a doubled one as the character itself.
529
+ _COMPLETION_PS_QUOTES = "'\u2018\u2019\u201a\u201b"
530
+
531
+
532
+ def _completion_ps_quote(word):
533
+ """A single-quoted PowerShell literal: PowerShell reads back exactly `word`, where nothing is expanded."""
534
+ return "'" + "".join(ch * 2 if ch in _COMPLETION_PS_QUOTES else ch for ch in word) + "'"
535
+
536
+
537
+ def _completion_ps_functions(model):
538
+ """PowerShell functions that return what _completion_sh_functions sets (SHELL-COMPLETION).
539
+
540
+ Each selects by `switch -Exact -CaseSensitive` on quoted literals, which compares strings exactly, as polyctl's
541
+ parser does, and returns an array of quoted literals.
542
+ """
543
+ q, arms = _completion_ps_quote, _completion_arms(model)
544
+
545
+ def returned(words, indent, guard=None):
546
+ literals = [q(word) for word in words]
547
+ opening, closing = (f"if ({guard}) {{ return @(", ") }") if guard else ("return @(", ")")
548
+ line = f"{indent}{opening}{', '.join(literals)}{closing}"
549
+ if len(line) <= COMPLETION_WIDTH:
550
+ return [line]
551
+ tokens = [literal + "," for literal in literals[:-1]] + literals[-1:]
552
+ return [indent + opening] + _completion_wrapped(tokens, indent + " ") + [indent + closing.strip()]
553
+
554
+ def function(name, parameters, kind):
555
+ lines = [f" function {name}({parameters}) {{"]
556
+ commands = list(dict.fromkeys(arm[0] for arm in arms if arm[1] == kind))
557
+ if commands:
558
+ lines += [" switch -Exact -CaseSensitive ($Command) {"]
559
+ for command in commands:
560
+ lines += [f" {q(command)} {{"]
561
+ mine = [arm for arm in arms if arm[:2] == (command, kind)]
562
+ if kind in ("values", "arity"):
563
+ lines += [" switch -Exact -CaseSensitive ($Option) {"]
564
+ for _, _, flag, words in mine:
565
+ lines += [f" {q(flag)} {{"] + returned(words, " ") \
566
+ + [" }"]
567
+ lines += [" }"]
568
+ elif kind == "slot":
569
+ for _, _, key, words in mine:
570
+ guard = f"$Slot -ge {key[0]}" if isinstance(key, tuple) else f"$Slot -eq {key}"
571
+ lines += returned(words, " ", guard)
572
+ else:
573
+ lines += returned(mine[0][3], " ")
574
+ lines += [" }"]
575
+ if commands:
576
+ lines += [" }"]
577
+ return lines + [" return @()", " }", ""]
578
+
579
+ return ([" # The option strings of a command that take the next word alone as their value."]
580
+ + function("Get-PolyctlValued", "[string]$Command", "valued")
581
+ + [" # How many words an option of a command takes, when not the next alone: a count, ?, * or ..."]
582
+ + function("Get-PolyctlArity", "[string]$Command, [string]$Option", "arity")
583
+ + [" # The long options of a command; before any command, those of polyctl itself."]
584
+ + function("Get-PolyctlOptions", "[string]$Command", "options")
585
+ + [" # The choices an option of a command declares."]
586
+ + function("Get-PolyctlValues", "[string]$Command, [string]$Option", "values")
587
+ + [" # The choices of a positional word (from 0) of a command; before any command, the commands."]
588
+ + function("Get-PolyctlArguments", "[string]$Command, [int]$Slot", "slot"))
589
+
590
+
591
+ _COMPLETION_POWERSHELL = r'''
592
+ # The words before the cursor name the command, then the positional word the cursor is on, or the
593
+ # option whose value it is. Every comparison is ordinal and case-sensitive, as argparse compares.
594
+ $words = @()
595
+ foreach ($element in $commandAst.CommandElements) {
596
+ if ($element.Extent.EndOffset -ge $cursorPosition) { break }
597
+ if ($element -is [System.Management.Automation.Language.StringConstantExpressionAst]) {
598
+ $words += $element.Value
599
+ } else {
600
+ $words += $element.Extent.Text
601
+ }
602
+ }
603
+ # An option takes up to $take words after it; one that $stops takes none that begins with -.
604
+ $command = ''
605
+ $rest = $false
606
+ $option = $null
607
+ $stops = $false
608
+ $slot = 0
609
+ $i = 1
610
+ while ($i -lt $words.Count) {
611
+ $word = [string]$words[$i]
612
+ if (-not $rest -and $command -cne '' -and $word -ceq '--') {
613
+ $rest = $true
614
+ } elseif (-not $rest -and $word.Length -gt 1 -and $word.StartsWith('-', [System.StringComparison]::Ordinal)) {
615
+ $take = 0
616
+ $stops = $false
617
+ if (@(Get-PolyctlValued $command) -ccontains $word) {
618
+ $take = 1
619
+ } else {
620
+ $arity = [string](@(Get-PolyctlArity $command $word) | Select-Object -First 1)
621
+ if ($arity -ceq '?') {
622
+ $take = 1
623
+ $stops = $true
624
+ } elseif ($arity -ceq '*') {
625
+ $take = $words.Count
626
+ $stops = $true
627
+ } elseif ($arity -ceq '...') {
628
+ $take = $words.Count
629
+ } elseif ($arity -cne '') {
630
+ $take = [int]$arity
631
+ }
632
+ }
633
+ $n = 1
634
+ while ($n -le $take -and $i + $n -lt $words.Count) {
635
+ $next = [string]$words[$i + $n]
636
+ if ($stops -and $next.Length -gt 1 -and $next.StartsWith('-', [System.StringComparison]::Ordinal)) {
637
+ break
638
+ }
639
+ $n++
640
+ }
641
+ if ($n -le $take -and $i + $n -ge $words.Count) {
642
+ $option = $word
643
+ break
644
+ }
645
+ $i += $n - 1
646
+ } elseif ($command -ceq '') {
647
+ $command = $word
648
+ } else {
649
+ $slot++
650
+ }
651
+ $i++
652
+ }
653
+ $current = [string]$wordToComplete
654
+ $prefix = ''
655
+ if ($null -eq $option -and -not $rest -and $current -cmatch '^(-[^=]+)=') {
656
+ $option = $Matches[1]
657
+ $prefix = $option + '='
658
+ $current = $current.Substring($prefix.Length)
659
+ $stops = $false
660
+ }
661
+ if ($null -ne $option -and -not ($stops -and $current.StartsWith('-', [System.StringComparison]::Ordinal))) {
662
+ $candidates = @(Get-PolyctlValues $command $option)
663
+ } elseif (-not $rest -and $current.StartsWith('-', [System.StringComparison]::Ordinal)) {
664
+ $candidates = @(Get-PolyctlOptions $command)
665
+ } else {
666
+ $candidates = @(Get-PolyctlArguments $command $slot)
667
+ }
668
+ # Each word that begins with what is typed; one PowerShell would read as syntax goes in single quotes.
669
+ foreach ($candidate in $candidates) {
670
+ if (-not $candidate.StartsWith($current, [System.StringComparison]::Ordinal)) { continue }
671
+ $text = $candidate
672
+ if ($candidate -cnotmatch '^[\w./-]+$') {
673
+ $text = "'" + ($candidate -replace "['\u2018\u2019\u201a\u201b]", '$0$0') + "'"
674
+ }
675
+ [System.Management.Automation.CompletionResult]::new($prefix + $text, $candidate, 'ParameterValue', $candidate)
676
+ }
677
+ }
678
+ '''
679
+
680
+
681
+ def _completion_powershell(model):
682
+ return (_completion_header("powershell", "PowerShell", ["polyctl completion powershell | Out-String | Invoke-Expression"],
683
+ ["as a line of your PowerShell profile, the file $PROFILE names."])
684
+ + ["", "Register-ArgumentCompleter -Native -CommandName 'polyctl' -ScriptBlock {",
685
+ " param($wordToComplete, $commandAst, $cursorPosition)", ""]
686
+ + _completion_ps_functions(model) + _COMPLETION_POWERSHELL.strip("\n").splitlines())