1/**
2 * The `Completions` module turns a plain description of an Effect CLI command
3 * tree into shell completion scripts for Bash, Zsh, and Fish. It is the
4 * low-level script generation surface used by the unstable CLI package and by
5 * the built-in completions global flag.
6 *
7 * @stability unstable
8 * @since 4.0.0
9 */
10import * as Bash from "./internal/completions/bash.ts"
11import * as Fish from "./internal/completions/fish.ts"
12import * as Zsh from "./internal/completions/zsh.ts"
13
14/**
15 * Shell type used to generate completion scripts.
16 *
17 * @stability unstable
18 * @category models
19 * @since 4.0.0
20 */
21export type Shell = "bash" | "zsh" | "fish"
22
23/**
24 * Describes a command for completion script generation.
25 *
26 * @stability unstable
27 * @category models
28 * @since 4.0.0
29 */
30export interface CommandDescriptor {
31 readonly name: string
32 readonly description: string | undefined
33 readonly flags: ReadonlyArray<FlagDescriptor>
34 readonly arguments: ReadonlyArray<ArgumentDescriptor>
35 readonly subcommands: ReadonlyArray<CommandDescriptor>
36}
37
38/**
39 * Describes a command flag for completions.
40 *
41 * @stability unstable
42 * @category models
43 * @since 4.0.0
44 */
45export interface FlagDescriptor {
46 readonly name: string
47 readonly aliases: ReadonlyArray<string>
48 readonly description: string | undefined
49 readonly type: FlagType
50}
51
52/**
53 * Describes the supported flag value shapes.
54 *
55 * @stability unstable
56 * @category models
57 * @since 4.0.0
58 */
59export type FlagType =
60 | { readonly _tag: "Boolean" }
61 | { readonly _tag: "String" }
62 | { readonly _tag: "Int" }
63 | { readonly _tag: "Finite" }
64 | { readonly _tag: "Date" }
65 | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
66 | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
67
68/**
69 * Describes a positional argument for completions.
70 *
71 * @stability unstable
72 * @category models
73 * @since 4.0.0
74 */
75export interface ArgumentDescriptor {
76 readonly name: string
77 readonly description: string | undefined
78 readonly required: boolean
79 readonly variadic: boolean
80 readonly type: ArgumentType
81}
82
83/**
84 * Describes the supported argument value shapes.
85 *
86 * @stability unstable
87 * @category models
88 * @since 4.0.0
89 */
90export type ArgumentType =
91 | { readonly _tag: "String" }
92 | { readonly _tag: "Int" }
93 | { readonly _tag: "Finite" }
94 | { readonly _tag: "Date" }
95 | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
96 | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
97
98/**
99 * Generates a shell completion script for a command descriptor.
100 *
101 * **When to use**
102 *
103 * Use when you need an installable completion script from an existing
104 * `CommandDescriptor`.
105 *
106 * **Details**
107 *
108 * Dispatches by `shell` to Bash, Zsh, or Fish generation and returns a static
109 * script string for `executableName`.
110 *
111 * @see {@link Shell} for supported shell names
112 * @see {@link CommandDescriptor} for the command shape used by completion generation
113 *
114 * @stability unstable
115 * @category constructors
116 * @since 4.0.0
117 */
118export const generate = (
119 executableName: string,
120 shell: Shell,
121 descriptor: CommandDescriptor
122): string => {
123 switch (shell) {
124 case "bash":
125 return Bash.generate(executableName, descriptor)
126 case "zsh":
127 return Zsh.generate(executableName, descriptor)
128 case "fish":
129 return Fish.generate(executableName, descriptor)
130 }
131}