Skip to content

Commit 9a8c558

Browse files
dearchapdearchap
committed
Cleanup docs
1 parent de2b0d1 commit 9a8c558

File tree

4 files changed

+148
-133
lines changed

4 files changed

+148
-133
lines changed

‎docs/v3/examples/completions/customizations.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
tags:
3+
- v3
4+
search:
5+
boost: 2
6+
---
7+
8+
If default completion isnt sufficient additional customizations are available
9+
10+
- custom auto-completion
11+
- customizing completion command
12+
13+
#### Custom auto-completion
14+
<!-- {
15+
"args": ["complete", "&#45;&#45;generate&#45;shell&#45;completion"],
16+
"output": "laundry"
17+
} -->
18+
```go
19+
package main
20+
21+
import (
22+
"fmt"
23+
"log"
24+
"os"
25+
"context"
26+
27+
"github.com/urfave/cli/v3"
28+
)
29+
30+
func main() {
31+
tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"}
32+
33+
cmd := &cli.Command{
34+
EnableShellCompletion: true,
35+
Commands: []*cli.Command{
36+
{
37+
Name: "complete",
38+
Aliases: []string{"c"},
39+
Usage: "complete a task on the list",
40+
Action: func(ctx context.Context, cmd *cli.Command) error {
41+
fmt.Println("completed task: ", cmd.Args().First())
42+
return nil
43+
},
44+
ShellComplete: func(ctx context.Context, cmd *cli.Command) {
45+
// This will complete if no args are passed
46+
if cmd.NArg() > 0 {
47+
return
48+
}
49+
for _, t := range tasks {
50+
fmt.Println(t)
51+
}
52+
},
53+
},
54+
},
55+
}
56+
57+
if err := cmd.Run(context.Background(), os.Args); err != nil {
58+
log.Fatal(err)
59+
}
60+
}
61+
```
62+
![](../../images/custom-bash-autocomplete.gif)
63+
64+
#### Customize a completion command
65+
66+
By default, a completion command is hidden, meaning the command isn't included in the help message.
67+
You can customize it by setting root Command's `ConfigureShellCompletionCommand`.
68+
69+
```go
70+
package main
71+
72+
import (
73+
"context"
74+
"fmt"
75+
"log"
76+
"os"
77+
78+
"github.com/urfave/cli/v3"
79+
)
80+
81+
func main() {
82+
cmd := &cli.Command{
83+
Name: "greet",
84+
// EnableShellCompletion is unnecessary
85+
ConfigureShellCompletionCommand: func(cmd *cli.Command) { // cmd is a completion command
86+
cmd.Hidden = false // Make a completion command public
87+
cmd.Usage = "..." // Customize Usage
88+
cmd.Description = "..." // Customize Description
89+
},
90+
Commands: []*cli.Command{
91+
{
92+
Name: "hello",
93+
Usage: "Say hello",
94+
Action: func(ctx context.Context, cmd *cli.Command) error {
95+
fmt.Println("Hello")
96+
return nil
97+
},
98+
},
99+
},
100+
}
101+
102+
if err := cmd.Run(context.Background(), os.Args); err != nil {
103+
log.Fatal(err)
104+
}
105+
}
106+
```
107+
108+
#### Customization
109+
110+
The default shell completion flag (`--generate-shell-completion`) is defined as
111+
`cli.EnableShellCompletion`, and may be redefined if desired, e.g.:
112+
113+
<!-- {
114+
"args": ["&#45;&#45;generate&#45;shell&#45;completion"],
115+
"output": "wat\nhelp\n"
116+
} -->
117+
```go
118+
package main
119+
120+
import (
121+
"log"
122+
"os"
123+
"context"
124+
125+
"github.com/urfave/cli/v3"
126+
)
127+
128+
func main() {
129+
cmd := &cli.Command{
130+
EnableShellCompletion: true,
131+
Commands: []*cli.Command{
132+
{
133+
Name: "wat",
134+
},
135+
},
136+
}
137+
138+
if err := cmd.Run(context.Background(), os.Args); err != nil {
139+
log.Fatal(err)
140+
}
141+
}
142+
```

‎docs/v3/examples/completions/shell-completions.md‎

Lines changed: 4 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,19 @@ The urfave/cli v3 library supports programmable completion for apps utilizing it
99
that the completion is generated dynamically at runtime by invokiong the app itself with a special hidden
1010
flag. The urfave/cli searches for this flag and activates a different flow for command paths than regular flow
1111
The following shells are supported
12+
1213
- bash
1314
- zsh
1415
- fish
1516
- powershell
1617

1718
Enabling auto complete requires 2 things
19+
1820
- Setting the `EnableShellCompletion` field on root `Command` object to `true`.
1921
- Sourcing the completion script for that particular shell.
2022

21-
The completion script for a particular shell can be retrieved by running the "completion" subcommand
22-
on the app after the `EnableShellCompletion` field on root `Command` object has been set to `true`.
23+
The completion script for a particular shell can be retrieved by running the "completion" subcommand
24+
on the app after the `EnableShellCompletion` field on root `Command` object has been set to `true`.
2325

2426
Consider the following program
2527

@@ -182,137 +184,6 @@ func main() {
182184
```
183185
![](../../images/default-bash-autocomplete.gif)
184186

185-
#### Custom auto-completion
186-
<!-- {
187-
"args": ["complete", "&#45;&#45;generate&#45;shell&#45;completion"],
188-
"output": "laundry"
189-
} -->
190-
```go
191-
package main
192-
193-
import (
194-
"fmt"
195-
"log"
196-
"os"
197-
"context"
198-
199-
"github.com/urfave/cli/v3"
200-
)
201-
202-
func main() {
203-
tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"}
204-
205-
cmd := &cli.Command{
206-
EnableShellCompletion: true,
207-
Commands: []*cli.Command{
208-
{
209-
Name: "complete",
210-
Aliases: []string{"c"},
211-
Usage: "complete a task on the list",
212-
Action: func(ctx context.Context, cmd *cli.Command) error {
213-
fmt.Println("completed task: ", cmd.Args().First())
214-
return nil
215-
},
216-
ShellComplete: func(ctx context.Context, cmd *cli.Command) {
217-
// This will complete if no args are passed
218-
if cmd.NArg() > 0 {
219-
return
220-
}
221-
for _, t := range tasks {
222-
fmt.Println(t)
223-
}
224-
},
225-
},
226-
},
227-
}
228-
229-
if err := cmd.Run(context.Background(), os.Args); err != nil {
230-
log.Fatal(err)
231-
}
232-
}
233-
```
234-
![](../../images/custom-bash-autocomplete.gif)
235-
236-
#### Customize a completion command
237-
238-
By default, a completion command is hidden, meaning the command isn't included in the help message.
239-
You can customize it by setting root Command's `ConfigureShellCompletionCommand`.
240-
241-
```go
242-
package main
243-
244-
import (
245-
"context"
246-
"fmt"
247-
"log"
248-
"os"
249-
250-
"github.com/urfave/cli/v3"
251-
)
252-
253-
func main() {
254-
cmd := &cli.Command{
255-
Name: "greet",
256-
// EnableShellCompletion is unnecessary
257-
ConfigureShellCompletionCommand: func(cmd *cli.Command) { // cmd is a completion command
258-
cmd.Hidden = false // Make a completion command public
259-
cmd.Usage = "..." // Customize Usage
260-
cmd.Description = "..." // Customize Description
261-
},
262-
Commands: []*cli.Command{
263-
{
264-
Name: "hello",
265-
Usage: "Say hello",
266-
Action: func(ctx context.Context, cmd *cli.Command) error {
267-
fmt.Println("Hello")
268-
return nil
269-
},
270-
},
271-
},
272-
}
273-
274-
if err := cmd.Run(context.Background(), os.Args); err != nil {
275-
log.Fatal(err)
276-
}
277-
}
278-
```
279-
280-
#### Customization
281-
282-
The default shell completion flag (`--generate-shell-completion`) is defined as
283-
`cli.EnableShellCompletion`, and may be redefined if desired, e.g.:
284-
285-
<!-- {
286-
"args": ["&#45;&#45;generate&#45;shell&#45;completion"],
287-
"output": "wat\nhelp\n"
288-
} -->
289-
```go
290-
package main
291-
292-
import (
293-
"log"
294-
"os"
295-
"context"
296-
297-
"github.com/urfave/cli/v3"
298-
)
299-
300-
func main() {
301-
cmd := &cli.Command{
302-
EnableShellCompletion: true,
303-
Commands: []*cli.Command{
304-
{
305-
Name: "wat",
306-
},
307-
},
308-
}
309-
310-
if err := cmd.Run(context.Background(), os.Args); err != nil {
311-
log.Fatal(err)
312-
}
313-
}
314-
```
315-
316187
#### ZSH Support
317188

318189
Adding the following lines to

‎docs/v3/examples/flags/basics.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,7 @@ Note that most flag can be invoked multiple times but only the last value entere
134134
will be provided to the user(with some exceptions. See flags-advanced.md)
135135

136136
The following basic flags are supported
137+
137138
- `IntFlag`
138139
- `Int8Flag`
139140
- `Int16Flag`

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ nav:
3535
- Categories: v3/examples/subcommands/categories.md
3636
- Completions:
3737
- Shell Completions: v3/examples/completions/shell-completions.md
38+
- Customizations: v3/examples/completions/customizations.md
3839
- Help Text:
3940
- Generated Help Text: v3/examples/help/generated-help-text.md
4041
- Suggestions: v3/examples/help/suggestions.md

0 commit comments

Comments
 (0)