Skip to content

Commit d5026e0

Browse files
DannyBenDannyBen
committed
- Add bashly doc command to show reference in the terminal
1 parent 5701dbd commit d5026e0

File tree

6 files changed

+596
-0
lines changed

6 files changed

+596
-0
lines changed

‎lib/bashly/cli.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ def self.runner
1414
runner.route 'validate', to: Commands::Validate
1515
runner.route 'generate', to: Commands::Generate
1616
runner.route 'add', to: Commands::Add
17+
runner.route 'doc', to: Commands::Doc
1718

1819
runner
1920
end

‎lib/bashly/commands/doc.rb‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
module Bashly
2+
module Commands
3+
class Doc < Base
4+
summary 'Show bashly reference documentation'
5+
help 'This command displays bite-sized help for all the bashly configuration options in the terminal.'
6+
7+
usage 'bashly doc [SEARCH] [--index]'
8+
usage 'bashly doc (-h|--help)'
9+
10+
option "-i --index", "Show option keys only"
11+
param 'SEARCH', 'Search for options that match this text'
12+
13+
example 'bashly doc command'
14+
example 'bashly doc command.flags'
15+
example 'bashly doc catch_all'
16+
17+
def run
18+
if args['--index']
19+
puts data.keys
20+
else
21+
show
22+
end
23+
end
24+
25+
private
26+
27+
def show
28+
data.each do |key, info|
29+
show_key key
30+
show_help info['help']
31+
show_example info['example'] if info['example']
32+
show_url info['url'] if info['url']
33+
end
34+
end
35+
36+
def show_key(key)
37+
say "!txtgrn!#{key}"
38+
say ''
39+
end
40+
41+
def show_url(url)
42+
say " See !undblu!#{url}"
43+
say ''
44+
end
45+
46+
def show_example(example)
47+
example = word_wrap " #{example}"
48+
example.gsub!(/^(\s*- )?(\s*\w+):/, '\1!txtblu!\2!txtrst!:')
49+
example.gsub!(/^(\s*\- )/, '!txtylw!\1!txtrst!')
50+
example.gsub!(/^(\s*#.+)/, '!txtpur!\1!txtrst!')
51+
say example
52+
say ''
53+
end
54+
55+
def show_help(help)
56+
help = word_wrap " #{help}"
57+
help.gsub!(/`([^`]+)`/, '!txtgrn!\1!txtrst!')
58+
say help
59+
say ''
60+
end
61+
62+
def data
63+
return raw_data unless args['SEARCH']
64+
65+
result = raw_data.select { |k, v| k. == args['SEARCH'] }
66+
return result if result.any?
67+
68+
result = raw_data.select { |k, v| k.include? args['SEARCH'] }
69+
return result if result.any?
70+
71+
say! "!txtred!No match"
72+
exit 1
73+
end
74+
75+
def raw_data
76+
@raw_data ||= begin
77+
result = {}
78+
Dir["#{docs_dir}/*.yml"].sort.each do |path|
79+
result.merge! YAML.load_file(path)
80+
end
81+
result
82+
end
83+
end
84+
85+
def docs_dir
86+
@docs_dir ||= File.expand_path "../docs", __dir__
87+
end
88+
end
89+
end
90+
end

‎lib/bashly/docs/arg.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
arg:
2+
help: Define positional arguments.
3+
url: https://bashly.dannyb.co/configuration/argument/
4+
example: |-
5+
args:
6+
- name: user
7+
help: AWS Username.
8+
required: true
9+
10+
- name: role
11+
help: User role.
12+
default: admin
13+
allowed:
14+
- admin
15+
- guest
16+
17+
arg.allowed:
18+
help: Specify a list of allowed values. Can be used in conjunction with `default` and `required`.
19+
url: https://bashly.dannyb.co/configuration/argument/#allowed
20+
example: |-
21+
args:
22+
- name: region
23+
help: Region to connect to
24+
25+
# allowed + required
26+
allowed: [eu, us]
27+
required: true
28+
29+
- name: environment
30+
help: Environment to connect to
31+
32+
# allowed + default
33+
allowed: [stage, production, development]
34+
default: development
35+
36+
arg.default:
37+
help: Specify the value to apply when not provided by the user.
38+
url: https://bashly.dannyb.co/configuration/argument/#default
39+
example: |-
40+
args:
41+
- name: images
42+
help: Image files to convert.
43+
default: "*.jpg"
44+
45+
arg.help:
46+
help: Specify the help message for this argument.
47+
url: https://bashly.dannyb.co/configuration/argument/#help
48+
example: |-
49+
args:
50+
- name: user
51+
help: AWS Username.
52+
required: true
53+
54+
arg.name:
55+
help: Specify the lowercase name of the argument.
56+
url: https://bashly.dannyb.co/configuration/argument/#name
57+
example: |-
58+
args:
59+
- name: user
60+
help: AWS Username.
61+
required: true
62+
63+
arg.repeatable:
64+
help: |-
65+
Specify that this argument can be provided multiple times.
66+
67+
The argument below will be received as a space-delimited string which needs to be converted to an array with:
68+
`eval "data=(${args[file]})"`
69+
70+
url: https://bashly.dannyb.co/configuration/argument/#repeatable
71+
example: |-
72+
args:
73+
- name: file
74+
help: One or more files to process
75+
required: true
76+
repeatable: true
77+
78+
arg.required:
79+
help: Specify that this argument is required.
80+
url: https://bashly.dannyb.co/configuration/argument/#required
81+
example: |-
82+
args:
83+
- name: region
84+
help: Region to connect to
85+
required: true
86+
87+
arg.validate:
88+
help: Apply custom validation functions.
89+
90+
url: https://bashly.dannyb.co/configuration/argument/#validate
91+
example: |-
92+
args:
93+
- name: path
94+
validate: file_exists

‎lib/bashly/docs/command.yml‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
command:
2+
help: Define the root command, or any sub-command.
3+
url: https://bashly.dannyb.co/configuration/command/
4+
example: |-
5+
name: rush
6+
help: Personal package manager
7+
version: 0.6.5
8+
9+
commands:
10+
- name: add
11+
alias: a
12+
help: Register a local repository
13+
args:
14+
- name: repo
15+
required: true
16+
help: Repository name.
17+
18+
command.alias:
19+
help: Specify one or more aliases for this sub-command.
20+
url: https://bashly.dannyb.co/configuration/command/#alias
21+
example: |-
22+
# Define a single alias
23+
command:
24+
name: download
25+
alias: d
26+
27+
# Define multiple aliases
28+
command:
29+
name: download
30+
alias: [d, pull]
31+
32+
# Run this commnad with anything that starts with 's'.
33+
command:
34+
name: server
35+
alias: s*
36+
37+
command.args:
38+
help: Define a list of positional arguments. See `arg` for reference.
39+
url: https://bashly.dannyb.co/configuration/command/#args
40+
example: |-
41+
args:
42+
- name: repo
43+
required: true
44+
help: Repository name.
45+
46+
command.catch_all:
47+
help: Specify that this command should allow for additional arbitrary arguments or flags.
48+
url: https://bashly.dannyb.co/configuration/command/#catch_all
49+
example: |-
50+
commands:
51+
- name: download
52+
help: Download one or more URLs
53+
54+
# Set to true to simply enable this option
55+
catch_all: true
56+
57+
- name: upload
58+
help: Upload one or more files
59+
60+
# Use this extended syntax in order to also provide a usage label
61+
# for these arguemnts, as well as specifying that at least one is
62+
# required.
63+
catch_all:
64+
label: Files
65+
help: Files to upload
66+
required: true
67+
68+
command.commands:
69+
help: Define a list of sub-commands. See `command` for reference.
70+
url: https://bashly.dannyb.co/configuration/command/#commands
71+
example: |-
72+
commands:
73+
- name: add
74+
alias: a
75+
help: Register a local repository
76+
77+
command.completions:
78+
help: Specify a list of additional completion suggestions when used in conjunction with `bashly add comp`.
79+
url: https://bashly.dannyb.co/configuration/command/#completions
80+
example: |-
81+
commands:
82+
- name: view
83+
help: View a directory, system user or a git branch
84+
completions:
85+
- <directory>
86+
- <user>
87+
- $(git branch 2> /dev/null)
88+
89+
command.default:
90+
help: Specify that this sub-command will be executed implicitely.
91+
url: https://bashly.dannyb.co/configuration/command/#default
92+
example: |-
93+
# This command will execute when the command line is not
94+
# recognized.
95+
commands:
96+
- name: upload
97+
help: Upload a file
98+
default: true
99+
100+
# This command will execute when the command line is not
101+
# recognized, or when it is empty.
102+
commands:
103+
- name: all
104+
help: Run all tests
105+
default: force
106+
107+
command.dependencies:
108+
help: Specify a list of required external commands that are needed to run this command.
109+
url: https://bashly.dannyb.co/configuration/command/#dependencies
110+
example: |-
111+
# Array syntax
112+
dependencies:
113+
- docker
114+
- curl
115+
116+
# Hash syntax, to provide additional help message
117+
dependencies:
118+
docker: see https://docker.com for installation instructions
119+
git: "install by running: sudo apt install git"
120+
121+
command.environment_variables:
122+
help: Define a list of environment variables. See `environment_variable` for reference.
123+
url: https://bashly.dannyb.co/configuration/command/#environment_variables
124+
example: |-
125+
environment_variables:
126+
- name: config_path
127+
help: Location of the config file
128+
default: ~/config.ini
129+
- name: api_key
130+
help: Your API key
131+
required: true
132+
133+
command.examples:
134+
help: Define one or more example messages.
135+
url: https://bashly.dannyb.co/configuration/command/#examples
136+
example: |-
137+
# Use an array of examples for simple one-liners.
138+
examples:
139+
- cli download example.com
140+
- cli download example.com ./output -f
141+
142+
# Use a multiline string when you need more control.
143+
# Note the use of the '|-' marker that tells YAML to use the
144+
# string as is, including the newlines it contains.
145+
examples: |-
146+
Upload a file
147+
$ cli upload profile.png -u admin -p s3cr3t
148+
149+
Upload a file (you will be prompted to provide a password)
150+
$ cli upload profile.png --user admin
151+
152+
command.flags:
153+
help: Define a list of option flags. See `flag` for reference.
154+
url: https://bashly.dannyb.co/configuration/command/#flags
155+
example: |-
156+
flags:
157+
- long: --purge
158+
short: -p
159+
help: Also remove the local directory.
160+
161+
command.footer:
162+
help: Specify a message to show at the bottom of the help text.
163+
url: https://bashly.dannyb.co/configuration/command/#footer
164+
example: |-
165+
footer: For further help visit https://my.docs-site.com
166+
167+
command.group:
168+
help: Specify the group that this command belongs to.
169+
url: https://bashly.dannyb.co/configuration/command/#group
170+
example: |-
171+
command:
172+
name: start
173+
help: Start the server
174+
group: Server
175+
176+
command.help:
177+
help: Specify the help text to show when showing uwags.
178+
url: https://bashly.dannyb.co/configuration/command/#help
179+
example: |-
180+
name: docker
181+
help: Runtime for containers
182+
183+
commands:
184+
- name: images
185+
help: Manage images
186+
187+
command.name:
188+
help: Specify the name of the command. This option is required.
189+
url: https://bashly.dannyb.co/configuration/command/#name
190+
example: |-
191+
name: docker
192+
help: Runtime for containers
193+
194+
commands:
195+
- name: images
196+
help: Manage images
197+
198+
command.version:
199+
help: Specify the version to show when running with `--version`.
200+
url: https://bashly.dannyb.co/configuration/command/#version
201+
example: |-
202+
name: rush
203+
help: Personal package manager
204+
version: 0.6.5

0 commit comments

Comments
 (0)