The unpac monorepo manager self-hosting as a monorepo using unpac
Add cookbook entry for contextual completion
+43
+43
vendor/opam/cmdliner/doc/cookbook.mld
+43
vendor/opam/cmdliner/doc/cookbook.mld
···
401
401
parameter overrides the two previous ways. See
402
402
{{!args_detect_absent}this} example. }}
403
403
404
+
{2:args_completion How can I customize positional and option value completion?}
405
+
406
+
Positional argument values and option values are completed according
407
+
to the {{!Cmdliner.Arg.argconv}argument converter} you use for defining
408
+
the optional or positional argument.
409
+
410
+
A couple of predefined argument converter like {!Cmdliner.Arg.path},
411
+
{!Cmdliner.Arg.filepath} and {!Cmdliner.Arg.dirpath} or
412
+
{!Cmdliner.Arg.enum} automatically handle this for you.
413
+
414
+
If you would like to perform custom or more elaborate context
415
+
sensitive completions you can define your own argument converter with
416
+
with a completion defined with {!Cmdliner.Arg.Completion.make}.
417
+
418
+
Here is an example where the first positional argument is completed
419
+
with the filenames found in a directory specified via the [--dir]
420
+
option (which defaults to the current working directory if unspecified).
421
+
{[
422
+
let dir = Arg.(value & opt dirpath "." & info ["d"; "dir"])
423
+
let dir_filenames_conv =
424
+
let complete dir ~token = match dir with
425
+
| None -> Error "Could not determine directory to lookup"
426
+
| Some dir ->
427
+
match Array.to_list (Sys.readdir dir) with
428
+
| exception Sys_error e -> Error (String.concat ": " [dir; e])
429
+
| fnames ->
430
+
let fnames = List.filter (String.starts_with ~prefix:token) fnames in
431
+
Ok (List.map Arg.Completion.string fnames)
432
+
in
433
+
let completion = Arg.Completion.make ~context:dir complete in
434
+
Arg.Conv.of_conv ~completion Arg.string
435
+
436
+
let pos0 = Arg.(required & pos 0 (some dir_filenames_conv) None & info [])
437
+
]}
438
+
439
+
Note that when you use [pos0] in a command line definition you also
440
+
need to make sure [dir] is part of the term otherwise the context will
441
+
always be [None]:
442
+
443
+
{[
444
+
let+ pos0 and+ dir and+ … in …
445
+
]}
446
+
404
447
{1:envs Environment variables}
405
448
406
449
{2:env_args How can environment variables define defaults?}