usage-lib 6.0.0

Library for working with usage specs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

{%- set source_code_link = source_code_link(spec=spec, cmd=cmd) %}
{%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
{%- if multi -%}
{{- "#" | repeat(count=header_level) }} `{{ (spec.bin ~ " " ~ full_cmd) | trim }}`
{%- endif %}
{%- if cmd.before_help_md %}

{{ cmd.before_help_md | escape_md }}
{%- endif %}

- **Usage**: `{{ (spec.bin ~ " " ~ cmd.usage) | trim }}`
{%- if cmd.deprecated or cmd.deprecated_warn_at or cmd.deprecated_remove_at %}
- **Deprecated**:{% if cmd.deprecated %} {{ cmd.deprecated }}{% if cmd.deprecated_warn_at or cmd.deprecated_remove_at %};{% endif %}{% endif %}{% if cmd.deprecated_warn_at %} Warns at {{ cmd.deprecated_warn_at }}.{% endif %}{% if cmd.deprecated_remove_at %} Removed at {{ cmd.deprecated_remove_at }}.{% endif %}
{%- endif %}
{%- if cmd.aliases %}
- **Aliases**: `{{ cmd.aliases | join(sep="`, `") }}`
{%- endif %}
{%- if cmd.effect %}
- **Effect**: {% if cmd.effect == "read" %}read-only{% elif cmd.effect == "destructive" %}destructive — may delete or irreversibly overwrite{% else %}modifies state{% endif %}
{%- endif %}
{%- if source_code_link %}
- **Source code**: {{ source_code_link }}
{%- endif %}

{%- if cmd.help_md %}

{{ cmd.help_md | escape_md }}
{%- endif %}

{%- set args = cmd.args | filter(attribute="hide", value=false) %}
{%- set flags = cmd.flags | filter(attribute="hide", value=false) %}
{%- set global_flags = flags | filter(attribute="global", value=true) %}
{%- set local_flags = flags | filter(attribute="global", value=false) %}
{#- if no subcommands, don't display flags as global #}
{%- if not cmd.subcommands %}
{%- set local_flags = flags %}
{%- set global_flags = [] %}
{%- endif %}

{%- for arg_group in cmd.arg_groups %}
{%- set group_args = arg_group.items | filter(attribute="hide", value=false) %}
{%- if group_args %}

{{ "#" | repeat(count=header_level) }}# {{ arg_group.heading | default(value="Arguments") }}

{%- for arg in group_args %}

{{ "#" | repeat(count=header_level) }}## `{{ arg.usage }}`
{%- include "arg_template.md.tera" %}
{%- endfor %}
{%- endif %}
{%- endfor %}

{%- for flag_group in cmd.flag_groups %}
{%- set visible = flag_group.items | filter(attribute="hide", value=false) %}
{%- set group_globals = visible | filter(attribute="global", value=true) %}
{#- A heading beats the default title, so a grouped global flag lands in the same
    section it does in help output rather than in a generic "Global Flags". #}
{%- if cmd.subcommands and group_globals %}

{{ "#" | repeat(count=header_level) }}# {{ flag_group.heading | default(value="Global Flags") }}

{%- for flag in group_globals %}

{{ "#" | repeat(count=header_level) }}## `{{ flag.usage }}`
{%- include "flag_template.md.tera" %}
{%- endfor %}
{%- endif %}
{%- endfor %}

{%- for flag_group in cmd.flag_groups %}
{%- set visible = flag_group.items | filter(attribute="hide", value=false) %}
{%- set group_flags = visible | filter(attribute="global", value=false) %}
{%- if not cmd.subcommands %}
{%- set group_flags = visible %}
{%- endif %}
{%- if group_flags %}

{{ "#" | repeat(count=header_level) }}# {{ flag_group.heading | default(value="Flags") }}

{%- for flag in group_flags %}

{{ "#" | repeat(count=header_level) }}## `{{ flag.usage }}`
{%- include "flag_template.md.tera" %}
{%- endfor %}
{%- endif %}
{%- endfor %}

{%- if cmd.examples %}

{{ "#" | repeat(count=header_level) }}# Examples

{%- for example in cmd.examples %}
{%- if example.header %}

**{{ example.header }}**
{%- endif %}
{%- if example.help %}

{{ example.help }}
{%- endif %}

```{{ example.lang }}
{{ example.code }}
```
{%- endfor %}
{%- endif %}

{%- if multi %}
{%- for cmd in cmd.subcommands | values | sort(attribute="usage") %}
{%- if not cmd.hide or cmd.hide == false %}
{%- if loop.first %}

{{ "#" | repeat(count=header_level) }}# Subcommands
{% endif %}
- [`{{ (spec.bin ~ " " ~ cmd.usage) | trim }}`]({{ url_prefix }}/{{ cmd.full_cmd | join(sep="/") }}.md)
{%- endif -%}
{%- endfor -%}
{%- endif -%}

{%- if cmd.after_help_md %}

{{ cmd.after_help_md | escape_md }}
{%- endif -%}