rbcli 0.1.10 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +31 -0
  3. data/CODE_OF_CONDUCT.md +1 -1
  4. data/Gemfile.lock +12 -12
  5. data/LICENSE.txt +674 -21
  6. data/README.md +80 -443
  7. data/bin/console +19 -0
  8. data/bin/setup +20 -0
  9. data/docs/404.html +639 -0
  10. data/docs/advanced/automatic_updates/index.html +791 -0
  11. data/docs/advanced/command_types/index.html +946 -0
  12. data/docs/advanced/distributed_state_locking/index.html +777 -0
  13. data/docs/advanced/hooks/index.html +836 -0
  14. data/docs/advanced/state_storage/index.html +957 -0
  15. data/docs/advanced/user_config_files/index.html +818 -0
  16. data/docs/assets/fonts/font-awesome.css +4 -0
  17. data/docs/assets/fonts/material-icons.css +13 -0
  18. data/docs/assets/fonts/specimen/FontAwesome.ttf +0 -0
  19. data/docs/assets/fonts/specimen/FontAwesome.woff +0 -0
  20. data/docs/assets/fonts/specimen/FontAwesome.woff2 +0 -0
  21. data/docs/assets/fonts/specimen/MaterialIcons-Regular.ttf +0 -0
  22. data/docs/assets/fonts/specimen/MaterialIcons-Regular.woff +0 -0
  23. data/docs/assets/fonts/specimen/MaterialIcons-Regular.woff2 +0 -0
  24. data/docs/assets/images/favicon.png +0 -0
  25. data/docs/assets/images/icons/bitbucket.1b09e088.svg +20 -0
  26. data/docs/assets/images/icons/github.f0b8504a.svg +18 -0
  27. data/docs/assets/images/icons/gitlab.6dd19c00.svg +38 -0
  28. data/docs/assets/javascripts/application.a59e2a89.js +1 -0
  29. data/docs/assets/javascripts/lunr/lunr.da.js +1 -0
  30. data/docs/assets/javascripts/lunr/lunr.de.js +1 -0
  31. data/docs/assets/javascripts/lunr/lunr.du.js +1 -0
  32. data/docs/assets/javascripts/lunr/lunr.es.js +1 -0
  33. data/docs/assets/javascripts/lunr/lunr.fi.js +1 -0
  34. data/docs/assets/javascripts/lunr/lunr.fr.js +1 -0
  35. data/docs/assets/javascripts/lunr/lunr.hu.js +1 -0
  36. data/docs/assets/javascripts/lunr/lunr.it.js +1 -0
  37. data/docs/assets/javascripts/lunr/lunr.jp.js +1 -0
  38. data/docs/assets/javascripts/lunr/lunr.multi.js +1 -0
  39. data/docs/assets/javascripts/lunr/lunr.no.js +1 -0
  40. data/docs/assets/javascripts/lunr/lunr.pt.js +1 -0
  41. data/docs/assets/javascripts/lunr/lunr.ro.js +1 -0
  42. data/docs/assets/javascripts/lunr/lunr.ru.js +1 -0
  43. data/docs/assets/javascripts/lunr/lunr.stemmer.support.js +1 -0
  44. data/docs/assets/javascripts/lunr/lunr.sv.js +1 -0
  45. data/docs/assets/javascripts/lunr/lunr.tr.js +1 -0
  46. data/docs/assets/javascripts/lunr/tinyseg.js +1 -0
  47. data/docs/assets/javascripts/modernizr.1aa3b519.js +1 -0
  48. data/docs/assets/stylesheets/application-palette.6079476c.css +2 -0
  49. data/docs/assets/stylesheets/application.ba0fd1a6.css +2 -0
  50. data/docs/development/code_of_conduct/index.html +883 -0
  51. data/docs/development/contributing/index.html +744 -0
  52. data/docs/development/license/index.html +715 -0
  53. data/docs/imported/changelog/index.html +853 -0
  54. data/docs/imported/quick_reference/index.html +1057 -0
  55. data/docs/index.html +732 -0
  56. data/docs/search/search_index.json +569 -0
  57. data/docs/sitemap.xml +93 -0
  58. data/docs/tutorial/10-getting_started/index.html +806 -0
  59. data/docs/tutorial/20-project_layout/index.html +972 -0
  60. data/docs/tutorial/30-your_first_command/index.html +906 -0
  61. data/docs/tutorial/40-options_parameters_and_arguments/index.html +1049 -0
  62. data/docs/tutorial/50-publishing/index.html +838 -0
  63. data/docs/whoami/index.html +709 -0
  64. data/docs-src/docs/advanced/automatic_updates.md +42 -0
  65. data/docs-src/docs/advanced/command_types.md +144 -0
  66. data/docs-src/docs/advanced/distributed_state_locking.md +33 -0
  67. data/docs-src/docs/advanced/hooks.md +65 -0
  68. data/docs-src/docs/advanced/logging.md +35 -0
  69. data/docs-src/docs/advanced/state_storage.md +117 -0
  70. data/docs-src/docs/advanced/user_config_files.md +47 -0
  71. data/docs-src/docs/development/code_of_conduct.md +74 -0
  72. data/docs-src/docs/development/contributing.md +49 -0
  73. data/docs-src/docs/development/license.md +10 -0
  74. data/docs-src/docs/imported/changelog.md +31 -0
  75. data/docs-src/docs/imported/quick_reference.md +150 -0
  76. data/docs-src/docs/index.md +38 -0
  77. data/docs-src/docs/tutorial/10-getting_started.md +41 -0
  78. data/docs-src/docs/tutorial/20-project_layout.md +115 -0
  79. data/docs-src/docs/tutorial/30-your_first_command.md +126 -0
  80. data/docs-src/docs/tutorial/40-options_parameters_and_arguments.md +251 -0
  81. data/docs-src/docs/tutorial/50-publishing.md +47 -0
  82. data/docs-src/docs/whoami.md +28 -0
  83. data/docs-src/makesite.sh +14 -0
  84. data/docs-src/mkdocs.yml +76 -0
  85. data/docs-src/runsite.sh +3 -0
  86. data/exe/rbcli +76 -5
  87. data/lib/rbcli/autoupdate/autoupdate.rb +24 -4
  88. data/lib/rbcli/autoupdate/gem_updater.rb +23 -2
  89. data/lib/rbcli/autoupdate/github_updater.rb +22 -1
  90. data/lib/rbcli/configuration/config.rb +22 -1
  91. data/lib/rbcli/configuration/configurate.rb +24 -2
  92. data/lib/rbcli/engine/command.rb +26 -6
  93. data/lib/rbcli/engine/load_project.rb +29 -3
  94. data/lib/rbcli/engine/parser.rb +25 -4
  95. data/lib/rbcli/logging/logging.rb +21 -0
  96. data/lib/rbcli/scriptwrapping/scriptwrapper.rb +30 -11
  97. data/lib/rbcli/stateful_systems/configuratestorage.rb +20 -0
  98. data/lib/rbcli/stateful_systems/state_storage.rb +20 -0
  99. data/lib/rbcli/stateful_systems/storagetypes/localstate.rb +20 -0
  100. data/lib/rbcli/stateful_systems/storagetypes/remote_state_connectors/dynamodb.rb +20 -0
  101. data/lib/rbcli/stateful_systems/storagetypes/remotestate_dynamodb.rb +20 -0
  102. data/lib/rbcli/util/hash_deep_symbolize.rb +43 -22
  103. data/lib/rbcli/util/string_colorize.rb +20 -0
  104. data/lib/rbcli/version.rb +21 -1
  105. data/lib/rbcli-tool/generators.rb +20 -0
  106. data/lib/rbcli-tool/mdless_fix.rb +20 -0
  107. data/lib/rbcli-tool/project.rb +27 -2
  108. data/lib/rbcli-tool/util.rb +20 -0
  109. data/lib/rbcli-tool.rb +20 -0
  110. data/lib/rbcli.rb +20 -0
  111. data/lib-sh/lib-rbcli.sh +19 -0
  112. data/rbcli.gemspec +22 -3
  113. data/skeletons/project/CODE_OF_CONDUCT.md +1 -1
  114. data/skeletons/project/README.md +17 -2
  115. data/skeletons/project/application/commands/command.erb +10 -8
  116. data/skeletons/project/application/commands/script.erb +3 -1
  117. data/skeletons/project/application/commands/scripts/script.sh +2 -2
  118. data/skeletons/project/application/options.rb +12 -3
  119. data/skeletons/project/config/autoupdate.rb +5 -2
  120. data/skeletons/project/config/storage.rb +7 -6
  121. data/skeletons/project/config/userspace.rb +6 -1
  122. data/skeletons/project/exe/executable +1 -1
  123. data/skeletons/project/lib/.keep +0 -0
  124. data/skeletons/project/untitled.gemspec +4 -4
  125. data/skeletons/project/{default_user_configs → userconf}/user_defaults.yml +0 -0
  126. metadata +85 -9
  127. data/examples/defaults.yml +0 -4
  128. data/examples/myscript.sh +0 -23
  129. data/examples/mytool +0 -95
@@ -0,0 +1,1049 @@
1
+
2
+
3
+
4
+
5
+ <!DOCTYPE html>
6
+ <html lang="en" class="no-js">
7
+ <head>
8
+
9
+ <meta charset="utf-8">
10
+ <meta name="viewport" content="width=device-width,initial-scale=1">
11
+ <meta http-equiv="x-ua-compatible" content="ie=edge">
12
+
13
+ <meta name="description" content="Description">
14
+
15
+
16
+
17
+ <meta name="author" content="Andrew Khoury">
18
+
19
+
20
+ <meta name="lang:clipboard.copy" content="Copy to clipboard">
21
+
22
+ <meta name="lang:clipboard.copied" content="Copied to clipboard">
23
+
24
+ <meta name="lang:search.language" content="en">
25
+
26
+ <meta name="lang:search.pipeline.stopwords" content="True">
27
+
28
+ <meta name="lang:search.pipeline.trimmer" content="True">
29
+
30
+ <meta name="lang:search.result.none" content="No matching documents">
31
+
32
+ <meta name="lang:search.result.one" content="1 matching document">
33
+
34
+ <meta name="lang:search.result.other" content="# matching documents">
35
+
36
+ <meta name="lang:search.tokenizer" content="[\s\-]+">
37
+
38
+ <link rel="shortcut icon" href="../../assets/images/favicon.png">
39
+ <meta name="generator" content="mkdocs-0.17.5, mkdocs-material-2.9.2">
40
+
41
+
42
+
43
+ <title>Options, Parameters, and Arguments - RBCli Documentation</title>
44
+
45
+
46
+
47
+ <link rel="stylesheet" href="../../assets/stylesheets/application.ba0fd1a6.css">
48
+
49
+
50
+
51
+
52
+ <script src="../../assets/javascripts/modernizr.1aa3b519.js"></script>
53
+
54
+
55
+ <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
56
+
57
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
58
+ <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
59
+
60
+
61
+ <link rel="stylesheet" href="../../assets/fonts/material-icons.css">
62
+
63
+
64
+ </head>
65
+
66
+ <body dir="ltr">
67
+
68
+ <svg class="md-svg">
69
+ <defs>
70
+
71
+
72
+ <svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
73
+ viewBox="0 0 416 448" id="__github">
74
+ <path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
75
+ 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
76
+ 18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
77
+ 19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
78
+ 18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
79
+ 304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
80
+ 2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
81
+ 38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
82
+ 37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
83
+ 82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
84
+ 1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
85
+ 0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
86
+ 30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
87
+ 46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
88
+ 99.5z" />
89
+ </svg>
90
+
91
+ </defs>
92
+ </svg>
93
+ <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
94
+ <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
95
+ <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
96
+
97
+ <a href="#options-paramters-and-arguments" tabindex="1" class="md-skip">
98
+ Skip to content
99
+ </a>
100
+
101
+
102
+ <header class="md-header" data-md-component="header">
103
+ <nav class="md-header-nav md-grid">
104
+ <div class="md-flex">
105
+ <div class="md-flex__cell md-flex__cell--shrink">
106
+ <a href="../.." title="RBCli Documentation" class="md-header-nav__button md-logo">
107
+
108
+ <i class="md-icon">devices</i>
109
+
110
+ </a>
111
+ </div>
112
+ <div class="md-flex__cell md-flex__cell--shrink">
113
+ <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
114
+ </div>
115
+ <div class="md-flex__cell md-flex__cell--stretch">
116
+ <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
117
+
118
+
119
+ <span class="md-header-nav__topic">
120
+ RBCli Documentation
121
+ </span>
122
+ <span class="md-header-nav__topic">
123
+ Options, Parameters, and Arguments
124
+ </span>
125
+
126
+
127
+ </div>
128
+ </div>
129
+ <div class="md-flex__cell md-flex__cell--shrink">
130
+
131
+
132
+ <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
133
+
134
+ <div class="md-search" data-md-component="search" role="dialog">
135
+ <label class="md-search__overlay" for="__search"></label>
136
+ <div class="md-search__inner" role="search">
137
+ <form class="md-search__form" name="search">
138
+ <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
139
+ <label class="md-icon md-search__icon" for="__search"></label>
140
+ <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
141
+ &#xE5CD;
142
+ </button>
143
+ </form>
144
+ <div class="md-search__output">
145
+ <div class="md-search__scrollwrap" data-md-scrollfix>
146
+ <div class="md-search-result" data-md-component="result">
147
+ <div class="md-search-result__meta">
148
+ Type to start searching
149
+ </div>
150
+ <ol class="md-search-result__list"></ol>
151
+ </div>
152
+ </div>
153
+ </div>
154
+ </div>
155
+ </div>
156
+
157
+
158
+ </div>
159
+
160
+ <div class="md-flex__cell md-flex__cell--shrink">
161
+ <div class="md-header-nav__source">
162
+
163
+
164
+
165
+
166
+
167
+
168
+ <a href="https://github.com/akhoury6/rbcli/" title="Go to repository" class="md-source" data-md-source="github">
169
+
170
+ <div class="md-source__icon">
171
+ <svg viewBox="0 0 24 24" width="24" height="24">
172
+ <use xlink:href="#__github" width="24" height="24"></use>
173
+ </svg>
174
+ </div>
175
+
176
+ <div class="md-source__repository">
177
+ GitHub
178
+ </div>
179
+ </a>
180
+
181
+ </div>
182
+ </div>
183
+
184
+ </div>
185
+ </nav>
186
+ </header>
187
+
188
+ <div class="md-container">
189
+
190
+
191
+
192
+
193
+
194
+
195
+
196
+
197
+ <nav class="md-tabs md-tabs--active" data-md-component="tabs">
198
+ <div class="md-tabs__inner md-grid">
199
+ <ul class="md-tabs__list">
200
+
201
+
202
+ <li class="md-tabs__item">
203
+
204
+ <a href="../.." title="Home" class="md-tabs__link">
205
+ Home
206
+ </a>
207
+
208
+ </li>
209
+
210
+
211
+
212
+
213
+
214
+
215
+
216
+ <li class="md-tabs__item">
217
+
218
+ <a href="../10-getting_started/" title="Tutorial" class="md-tabs__link md-tabs__link--active">
219
+ Tutorial
220
+ </a>
221
+
222
+ </li>
223
+
224
+
225
+
226
+
227
+
228
+
229
+ <li class="md-tabs__item">
230
+
231
+ <a href="../../advanced/command_types/" title="Advanced Features" class="md-tabs__link">
232
+ Advanced Features
233
+ </a>
234
+
235
+ </li>
236
+
237
+
238
+
239
+
240
+
241
+
242
+ <li class="md-tabs__item">
243
+
244
+ <a href="../../development/contributing/" title="Development" class="md-tabs__link">
245
+ Development
246
+ </a>
247
+
248
+ </li>
249
+
250
+
251
+
252
+
253
+
254
+ </ul>
255
+ </div>
256
+ </nav>
257
+
258
+ <main class="md-main">
259
+ <div class="md-main__inner md-grid" data-md-component="container">
260
+
261
+
262
+ <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
263
+ <div class="md-sidebar__scrollwrap">
264
+ <div class="md-sidebar__inner">
265
+ <nav class="md-nav md-nav--primary" data-md-level="0">
266
+ <label class="md-nav__title md-nav__title--site" for="__drawer">
267
+ <span class="md-nav__button md-logo">
268
+
269
+ <i class="md-icon">devices</i>
270
+
271
+ </span>
272
+ RBCli Documentation
273
+ </label>
274
+
275
+ <div class="md-nav__source">
276
+
277
+
278
+
279
+
280
+
281
+
282
+ <a href="https://github.com/akhoury6/rbcli/" title="Go to repository" class="md-source" data-md-source="github">
283
+
284
+ <div class="md-source__icon">
285
+ <svg viewBox="0 0 24 24" width="24" height="24">
286
+ <use xlink:href="#__github" width="24" height="24"></use>
287
+ </svg>
288
+ </div>
289
+
290
+ <div class="md-source__repository">
291
+ GitHub
292
+ </div>
293
+ </a>
294
+
295
+ </div>
296
+
297
+ <ul class="md-nav__list" data-md-scrollfix>
298
+
299
+
300
+
301
+
302
+
303
+
304
+ <li class="md-nav__item">
305
+ <a href="../.." title="Home" class="md-nav__link">
306
+ Home
307
+ </a>
308
+ </li>
309
+
310
+
311
+
312
+
313
+
314
+
315
+
316
+ <li class="md-nav__item">
317
+ <a href="../../imported/quick_reference/" title="Quick Reference" class="md-nav__link">
318
+ Quick Reference
319
+ </a>
320
+ </li>
321
+
322
+
323
+
324
+
325
+
326
+
327
+
328
+
329
+
330
+ <li class="md-nav__item md-nav__item--active md-nav__item--nested">
331
+
332
+ <input class="md-toggle md-nav__toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3" checked>
333
+
334
+ <label class="md-nav__link" for="nav-3">
335
+ Tutorial
336
+ </label>
337
+ <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
338
+ <label class="md-nav__title" for="nav-3">
339
+ Tutorial
340
+ </label>
341
+ <ul class="md-nav__list" data-md-scrollfix>
342
+
343
+
344
+
345
+
346
+
347
+
348
+
349
+ <li class="md-nav__item">
350
+ <a href="../10-getting_started/" title="Getting Started" class="md-nav__link">
351
+ Getting Started
352
+ </a>
353
+ </li>
354
+
355
+
356
+
357
+
358
+
359
+
360
+
361
+ <li class="md-nav__item">
362
+ <a href="../20-project_layout/" title="The Project Layout" class="md-nav__link">
363
+ The Project Layout
364
+ </a>
365
+ </li>
366
+
367
+
368
+
369
+
370
+
371
+
372
+
373
+ <li class="md-nav__item">
374
+ <a href="../30-your_first_command/" title="Your First Command" class="md-nav__link">
375
+ Your First Command
376
+ </a>
377
+ </li>
378
+
379
+
380
+
381
+
382
+
383
+
384
+
385
+
386
+
387
+ <li class="md-nav__item md-nav__item--active">
388
+
389
+ <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
390
+
391
+
392
+
393
+
394
+ <label class="md-nav__link md-nav__link--active" for="__toc">
395
+ Options, Parameters, and Arguments
396
+ </label>
397
+
398
+ <a href="./" title="Options, Parameters, and Arguments" class="md-nav__link md-nav__link--active">
399
+ Options, Parameters, and Arguments
400
+ </a>
401
+
402
+
403
+ <nav class="md-nav md-nav--secondary">
404
+
405
+
406
+
407
+
408
+
409
+ <label class="md-nav__title" for="__toc">Table of contents</label>
410
+ <ul class="md-nav__list" data-md-scrollfix>
411
+
412
+ <li class="md-nav__item">
413
+ <a href="#command-line-structure" title="Command Line Structure" class="md-nav__link">
414
+ Command Line Structure
415
+ </a>
416
+
417
+ </li>
418
+
419
+ <li class="md-nav__item">
420
+ <a href="#options" title="Options" class="md-nav__link">
421
+ Options
422
+ </a>
423
+
424
+ </li>
425
+
426
+ <li class="md-nav__item">
427
+ <a href="#parameters" title="Parameters" class="md-nav__link">
428
+ Parameters
429
+ </a>
430
+
431
+ </li>
432
+
433
+ <li class="md-nav__item">
434
+ <a href="#arguments" title="Arguments" class="md-nav__link">
435
+ Arguments
436
+ </a>
437
+
438
+ </li>
439
+
440
+ <li class="md-nav__item">
441
+ <a href="#simplified-reference-tldr" title="Simplified Reference (TLDR)" class="md-nav__link">
442
+ Simplified Reference (TLDR)
443
+ </a>
444
+
445
+ </li>
446
+
447
+ <li class="md-nav__item">
448
+ <a href="#next-steps" title="Next Steps" class="md-nav__link">
449
+ Next Steps
450
+ </a>
451
+
452
+ </li>
453
+
454
+
455
+
456
+
457
+
458
+ </ul>
459
+
460
+ </nav>
461
+
462
+ </li>
463
+
464
+
465
+
466
+
467
+
468
+
469
+
470
+ <li class="md-nav__item">
471
+ <a href="../50-publishing/" title="Publishing and Distribution" class="md-nav__link">
472
+ Publishing and Distribution
473
+ </a>
474
+ </li>
475
+
476
+
477
+ </ul>
478
+ </nav>
479
+ </li>
480
+
481
+
482
+
483
+
484
+
485
+
486
+
487
+ <li class="md-nav__item md-nav__item--nested">
488
+
489
+ <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4">
490
+
491
+ <label class="md-nav__link" for="nav-4">
492
+ Advanced Features
493
+ </label>
494
+ <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
495
+ <label class="md-nav__title" for="nav-4">
496
+ Advanced Features
497
+ </label>
498
+ <ul class="md-nav__list" data-md-scrollfix>
499
+
500
+
501
+
502
+
503
+
504
+
505
+
506
+ <li class="md-nav__item">
507
+ <a href="../../advanced/command_types/" title="Command Types" class="md-nav__link">
508
+ Command Types
509
+ </a>
510
+ </li>
511
+
512
+
513
+
514
+
515
+
516
+
517
+
518
+ <li class="md-nav__item">
519
+ <a href="../../advanced/user_config_files/" title="User Config Files" class="md-nav__link">
520
+ User Config Files
521
+ </a>
522
+ </li>
523
+
524
+
525
+
526
+
527
+
528
+
529
+
530
+ <li class="md-nav__item">
531
+ <a href="../../advanced/hooks/" title="Hooks" class="md-nav__link">
532
+ Hooks
533
+ </a>
534
+ </li>
535
+
536
+
537
+
538
+
539
+
540
+
541
+
542
+ <li class="md-nav__item">
543
+ <a href="../../advanced/automatic_updates/" title="Automatic Updates" class="md-nav__link">
544
+ Automatic Updates
545
+ </a>
546
+ </li>
547
+
548
+
549
+
550
+
551
+
552
+
553
+
554
+ <li class="md-nav__item">
555
+ <a href="../../advanced/state_storage/" title="State Storage" class="md-nav__link">
556
+ State Storage
557
+ </a>
558
+ </li>
559
+
560
+
561
+
562
+
563
+
564
+
565
+
566
+ <li class="md-nav__item">
567
+ <a href="../../advanced/distributed_state_locking/" title="Distributed State Locking" class="md-nav__link">
568
+ Distributed State Locking
569
+ </a>
570
+ </li>
571
+
572
+
573
+ </ul>
574
+ </nav>
575
+ </li>
576
+
577
+
578
+
579
+
580
+
581
+
582
+
583
+ <li class="md-nav__item md-nav__item--nested">
584
+
585
+ <input class="md-toggle md-nav__toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5">
586
+
587
+ <label class="md-nav__link" for="nav-5">
588
+ Development
589
+ </label>
590
+ <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
591
+ <label class="md-nav__title" for="nav-5">
592
+ Development
593
+ </label>
594
+ <ul class="md-nav__list" data-md-scrollfix>
595
+
596
+
597
+
598
+
599
+
600
+
601
+
602
+ <li class="md-nav__item">
603
+ <a href="../../development/contributing/" title="Contribution Guide" class="md-nav__link">
604
+ Contribution Guide
605
+ </a>
606
+ </li>
607
+
608
+
609
+
610
+
611
+
612
+
613
+
614
+ <li class="md-nav__item">
615
+ <a href="../../development/license/" title="License Info" class="md-nav__link">
616
+ License Info
617
+ </a>
618
+ </li>
619
+
620
+
621
+
622
+
623
+
624
+
625
+
626
+ <li class="md-nav__item">
627
+ <a href="../../development/code_of_conduct/" title="Code of Conduct" class="md-nav__link">
628
+ Code of Conduct
629
+ </a>
630
+ </li>
631
+
632
+
633
+
634
+
635
+
636
+
637
+
638
+ <li class="md-nav__item">
639
+ <a href="../../imported/changelog/" title="Changelog" class="md-nav__link">
640
+ Changelog
641
+ </a>
642
+ </li>
643
+
644
+
645
+ </ul>
646
+ </nav>
647
+ </li>
648
+
649
+
650
+
651
+
652
+
653
+
654
+
655
+ <li class="md-nav__item">
656
+ <a href="../../whoami/" title="$ whoami" class="md-nav__link">
657
+ $ whoami
658
+ </a>
659
+ </li>
660
+
661
+
662
+ </ul>
663
+ </nav>
664
+ </div>
665
+ </div>
666
+ </div>
667
+
668
+
669
+ <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
670
+ <div class="md-sidebar__scrollwrap">
671
+ <div class="md-sidebar__inner">
672
+
673
+ <nav class="md-nav md-nav--secondary">
674
+
675
+
676
+
677
+
678
+
679
+ <label class="md-nav__title" for="__toc">Table of contents</label>
680
+ <ul class="md-nav__list" data-md-scrollfix>
681
+
682
+ <li class="md-nav__item">
683
+ <a href="#command-line-structure" title="Command Line Structure" class="md-nav__link">
684
+ Command Line Structure
685
+ </a>
686
+
687
+ </li>
688
+
689
+ <li class="md-nav__item">
690
+ <a href="#options" title="Options" class="md-nav__link">
691
+ Options
692
+ </a>
693
+
694
+ </li>
695
+
696
+ <li class="md-nav__item">
697
+ <a href="#parameters" title="Parameters" class="md-nav__link">
698
+ Parameters
699
+ </a>
700
+
701
+ </li>
702
+
703
+ <li class="md-nav__item">
704
+ <a href="#arguments" title="Arguments" class="md-nav__link">
705
+ Arguments
706
+ </a>
707
+
708
+ </li>
709
+
710
+ <li class="md-nav__item">
711
+ <a href="#simplified-reference-tldr" title="Simplified Reference (TLDR)" class="md-nav__link">
712
+ Simplified Reference (TLDR)
713
+ </a>
714
+
715
+ </li>
716
+
717
+ <li class="md-nav__item">
718
+ <a href="#next-steps" title="Next Steps" class="md-nav__link">
719
+ Next Steps
720
+ </a>
721
+
722
+ </li>
723
+
724
+
725
+
726
+
727
+
728
+ </ul>
729
+
730
+ </nav>
731
+ </div>
732
+ </div>
733
+ </div>
734
+
735
+
736
+ <div class="md-content">
737
+ <article class="md-content__inner md-typeset">
738
+
739
+
740
+
741
+ <h1 id="options-paramters-and-arguments">Options, Paramters, and Arguments</h1>
742
+ <p>If you're already an experienced coder, you can jump to the last section of this document, the <a href="#simplified-reference-tldr">Simplified Reference (TLDR)</a></p>
743
+ <h2 id="command-line-structure">Command Line Structure</h2>
744
+ <p>In the previous section, you saw two parts of the RBCli command line structure - the executable followed by the command. However, RBCli is capable of more complex interaction. The structure is as follows:</p>
745
+ <pre><code>toolname [options] command [parameters] argument1 argument2...
746
+ </code></pre>
747
+
748
+ <ul>
749
+ <li><strong>Options</strong> are command line parameters such as <code>-f</code>, or <code>--force</code>. These are available globally to every command. You can create your own, though several are already built-in and reserved for RBCli:<ul>
750
+ <li><code>--config-file=&lt;filename&gt;</code> allows specifying a config file location manually.</li>
751
+ <li><code>--generate-config</code> generates a config file for the user by writing out the defaults to a YAML file. This option will only appear if a config file has been set. The location is configurable, with more on that in the documentation on <a href="../../advanced/user_config_files/">User Config Files</a>).</li>
752
+ <li><code>-v / --version</code> shows the version.</li>
753
+ <li><code>-h / --help</code> shows the help.</li>
754
+ </ul>
755
+ </li>
756
+ <li><strong>Command</strong> represents the subcommands that you will create, such as <code>list</code>, <code>test</code>, or <code>apply</code>.</li>
757
+ <li><strong>Parameters</strong> are the same as options, but only apply to the specific subcommand being executed. In this case only the <code>-h / --help</code> parameter is provided automatically.</li>
758
+ <li><strong>Arguments</strong> are strings that don't begin with a '-', and are passed to the command's code as an array. These can be used as subcommands or additional parameters for your command. </li>
759
+ </ul>
760
+ <p>So a valid command could look something like these:</p>
761
+ <pre><code class="shell">mytool -n load --filename=foo.txt
762
+ mytool parse foo.txt
763
+ mytool show -l
764
+ </code></pre>
765
+
766
+ <p>Note that all options and parameters will have both a short and long version of the parameter available for use.</p>
767
+ <p>So let's take a look at how we define them.</p>
768
+ <h2 id="options">Options</h2>
769
+ <p>You can find the options declarations under <code>application/options.rb</code>. You'll see the example in the code:</p>
770
+ <pre><code class="ruby">option :name, 'Give me your name', short: 'n', type: :string, default: 'Jack', required: false, permitted: ['Jack', 'Jill']
771
+ </code></pre>
772
+
773
+ <p>This won't do for our tool, so let's change it. Remember that these options will be applicable to all of our commands, so lets make it something appropriate:</p>
774
+ <pre><code class="ruby">option :color, 'Enable color output', short: 'c', type: :boolean, default: false
775
+ </code></pre>
776
+
777
+ <p>So now, let's take advantage of this flag in our <code>list</code> command. Let's change our block to:</p>
778
+ <pre><code class="ruby"> action do |params, args, global_opts, config|
779
+ Dir.glob &quot;./*&quot; do |filename|
780
+ outname = filename.split('/')[1]
781
+ outname += '/' if File.directory? filename
782
+
783
+ # We change the color based on the kind of file shown
784
+ if global_opts[:color]
785
+ if File.directory? filename
786
+ outname = outname.light_blue
787
+ elsif File.executable? filename
788
+ outname = outname.light_green
789
+ end
790
+ end
791
+
792
+ puts outname
793
+ end
794
+ end
795
+ </code></pre>
796
+
797
+ <p>Notice how we referenced the value by using <code>global_opts[:color]</code>. It's that simple. To see it in action, run:</p>
798
+ <pre><code class="bash">mytool -c list
799
+ </code></pre>
800
+
801
+ <h2 id="parameters">Parameters</h2>
802
+ <p>Parameters work the same way as options, but they are localized to only the selected command. They are declared - as you probably guessed by now - in the command's class. So let's add the following lines to our list command within the class declaration:</p>
803
+ <pre><code class="ruby">parameter :sort, 'Sort output alphabetically', type: :boolean, default: false
804
+ parameter :all, 'Show hidden files', type: :boolean, default: false
805
+ parameter :directoriesfirst, 'Show directories on top', type: :boolean, default: false
806
+ </code></pre>
807
+
808
+ <p>And let's modify our action block to utilize them:</p>
809
+ <pre><code class="ruby"> action do |params, args, global_opts, config|
810
+ filelist = []
811
+
812
+ # We include dotfiles if specified
813
+ include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0
814
+
815
+ # We store a list of the files in an array, including dotfiles if specified
816
+ Dir.glob &quot;./*&quot;, include_dotfiles do |filename|
817
+ outname = filename.split('/')[1]
818
+ outname += '/' if File.directory? filename
819
+ filelist.append outname
820
+ end
821
+
822
+ # Sort alphabetically if specified
823
+ filelist.sort! if params[:sort]
824
+
825
+ # Put directories first if specified
826
+ if params[:directoriesfirst]
827
+ files = []; dirs = []
828
+ filelist.each do |filename|
829
+ if File.directory? filename
830
+ dirs.append(filename)
831
+ else
832
+ files.append(filename)
833
+ end
834
+ end
835
+ filelist = dirs + files
836
+ end
837
+
838
+ # Apply color. We do this at the end now because color codes can alter the sorting.
839
+ filelist.map! do |filename|
840
+ if File.directory? filename
841
+ filename.light_blue
842
+ elsif File.executable? filename
843
+ filename.light_green
844
+ else
845
+ filename
846
+ end
847
+ end if global_opts[:color]
848
+
849
+ puts filelist
850
+ end
851
+ </code></pre>
852
+
853
+ <p>You should be able to run it now:</p>
854
+ <pre><code class="bash">mytool -c list -asd
855
+ </code></pre>
856
+
857
+ <p>Note how the parameters come after the <code>list</code> command in the syntax above. As you create more commands, each will have its own unique set of parameters, while the options remain <em>before</em> the command and are available to all of them.</p>
858
+ <h2 id="arguments">Arguments</h2>
859
+ <p>Lastly on the command line, there are arguments. Arguments are simply strings without the <code>-</code> character in front, and automatically get passed into an array in your applicaiton. Let's take a look at how we can use them.</p>
860
+ <p>Unlike options and parameters, arguments require no setup. So let's assume that we want any arguments passed to the <code>list</code> command to be filenames that you want to display, and that you can pass multiple ones. Since arguments aren't listed automatically by the help function, this is a good example of what to put in your usage text. Let's take a look at what our class looks like now:</p>
861
+ <pre><code class="ruby">class List &lt; Rbcli::Command
862
+ description %q{List files in current directory}
863
+ usage &lt;&lt;-EOF
864
+ To list only specific files, you can enter filenames as arguments
865
+
866
+ mytool list filename1 filename2...
867
+ EOF
868
+ parameter :sort, 'Sort output alphabetically', type: :boolean, default: false
869
+ parameter :all, 'Show hidden files', type: :boolean, default: false
870
+ parameter :directoriesfirst, 'Show directories on top', type: :boolean, default: false
871
+
872
+ action do |params, args, global_opts, config|
873
+ filelist = []
874
+
875
+ # We include dotfiles if specified
876
+ include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0
877
+
878
+ # We store a list of the files in an array, including dotfiles if specified
879
+ Dir.glob &quot;./*&quot;, include_dotfiles do |filename|
880
+ outname = filename.split('/')[1]
881
+ next unless args.include? outname if args.length &gt; 0
882
+ outname += '/' if File.directory? filename
883
+ filelist.append outname
884
+ end
885
+
886
+ # Sort alphabetically if specified
887
+ filelist.sort! if params[:sort]
888
+
889
+ # Put directories first if specified
890
+ if params[:directoriesfirst]
891
+ files = []; dirs = []
892
+ filelist.each do |filename|
893
+ if File.directory? filename
894
+ dirs.append(filename)
895
+ else
896
+ files.append(filename)
897
+ end
898
+ end
899
+ filelist = dirs + files
900
+ end
901
+
902
+ # Apply color. We do this at the end because color codes can alter the sorting
903
+ filelist.map! do |filename|
904
+ if File.directory? filename
905
+ filename.light_blue
906
+ elsif File.executable? filename
907
+ filename.light_green
908
+ else
909
+ filename
910
+ end
911
+ end if global_opts[:color]
912
+
913
+ puts filelist
914
+ end
915
+ end
916
+ </code></pre>
917
+
918
+ <h2 id="simplified-reference-tldr">Simplified Reference (TLDR)</h2>
919
+ <p>RBCli enforces a CLI structure of:</p>
920
+ <pre><code>toolname [options] command [parameters] argument1 argument2...
921
+ </code></pre>
922
+
923
+ <p><strong>Options</strong> are declared in <code>application/options.rb</code> file.</p>
924
+ <p><strong>Parameters</strong> are declared in the respective command's class declaration.</p>
925
+ <p><strong>Arguments</strong> don't need to be declared, and are passed in as an array to your commands. It is helpful to describe the argument purpose in the <code>usage</code> text declaration so that the user can see what to do in the help.</p>
926
+ <p><strong>Options</strong> and <strong>parameters</strong> both use the same format:</p>
927
+ <pre><code class="ruby">option :&lt;name&gt;, &quot;&lt;description_string&gt;&quot;, short: '&lt;character&gt;', type: &lt;variable_type&gt;, default: &lt;default_value&gt;, permitted: [&lt;array_of_permitted_values]
928
+
929
+ parameter :&lt;name&gt;, &quot;&lt;description_string&gt;&quot;, short: '&lt;character&gt;', type: &lt;variable_type&gt;, default: &lt;default_value&gt;, permitted: [&lt;array_of_permitted_values]
930
+ </code></pre>
931
+
932
+ <ul>
933
+ <li><code>name</code><ul>
934
+ <li>(Required) The long name of the option, as a symbol. This will be represented as <code>--name</code> on the command line</li>
935
+ </ul>
936
+ </li>
937
+ <li><code>description_string</code><ul>
938
+ <li>(Required) A short description of the command that will appear in the help text for the user</li>
939
+ </ul>
940
+ </li>
941
+ <li><code>type</code><ul>
942
+ <li>(Required) The following types are supported: <code>:string</code>, <code>:boolean</code> or <code>:flag</code>, <code>:integer</code>, and <code>:float</code></li>
943
+ </ul>
944
+ </li>
945
+ <li><code>default</code><ul>
946
+ <li>(Optional) A default value for the option if one isn't entered (default: nil)</li>
947
+ </ul>
948
+ </li>
949
+ <li><code>short</code><ul>
950
+ <li>(Optional) A letter that acts as a shortcut for the option. This will allow users to apply the command as <code>-n</code></li>
951
+ <li>To not have a short value, set this to :none (default: the first letter of the long name)</li>
952
+ </ul>
953
+ </li>
954
+ <li><code>required</code><ul>
955
+ <li>(Optional) Specify whether the option is required from the user (default: false)</li>
956
+ </ul>
957
+ </li>
958
+ <li><code>permitted</code><ul>
959
+ <li>(Optional) An array of whitelisted values for the option (default: nil)</li>
960
+ </ul>
961
+ </li>
962
+ </ul>
963
+ <h2 id="next-steps">Next Steps</h2>
964
+ <p>Next, we're going to take a quick look at how to publish and distribute your application, both publicly and within your organization.</p>
965
+
966
+
967
+
968
+
969
+
970
+
971
+
972
+
973
+
974
+ </article>
975
+ </div>
976
+ </div>
977
+ </main>
978
+
979
+
980
+ <footer class="md-footer">
981
+
982
+ <div class="md-footer-nav">
983
+ <nav class="md-footer-nav__inner md-grid">
984
+
985
+ <a href="../30-your_first_command/" title="Your First Command" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
986
+ <div class="md-flex__cell md-flex__cell--shrink">
987
+ <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
988
+ </div>
989
+ <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
990
+ <span class="md-flex__ellipsis">
991
+ <span class="md-footer-nav__direction">
992
+ Previous
993
+ </span>
994
+ Your First Command
995
+ </span>
996
+ </div>
997
+ </a>
998
+
999
+
1000
+ <a href="../50-publishing/" title="Publishing and Distribution" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
1001
+ <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
1002
+ <span class="md-flex__ellipsis">
1003
+ <span class="md-footer-nav__direction">
1004
+ Next
1005
+ </span>
1006
+ Publishing and Distribution
1007
+ </span>
1008
+ </div>
1009
+ <div class="md-flex__cell md-flex__cell--shrink">
1010
+ <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
1011
+ </div>
1012
+ </a>
1013
+
1014
+ </nav>
1015
+ </div>
1016
+
1017
+ <div class="md-footer-meta md-typeset">
1018
+ <div class="md-footer-meta__inner md-grid">
1019
+ <div class="md-footer-copyright">
1020
+
1021
+ <div class="md-footer-copyright__highlight">
1022
+ Copyright © 2018 Andrew Khoury
1023
+ </div>
1024
+
1025
+ powered by
1026
+ <a href="https://www.mkdocs.org">MkDocs</a>
1027
+ and
1028
+ <a href="https://squidfunk.github.io/mkdocs-material/">
1029
+ Material for MkDocs</a>
1030
+ </div>
1031
+
1032
+
1033
+
1034
+ </div>
1035
+ </div>
1036
+ </footer>
1037
+
1038
+ </div>
1039
+
1040
+ <script src="../../assets/javascripts/application.a59e2a89.js"></script>
1041
+
1042
+ <script>app.initialize({version:"0.17.5",url:{base:"../.."}})</script>
1043
+
1044
+
1045
+
1046
+
1047
+
1048
+ </body>
1049
+ </html>