cliutils 1.0.0 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (87) hide show
  1. checksums.yaml +4 -4
  2. data/.yardoc/checksums +11 -0
  3. data/.yardoc/object_types +0 -0
  4. data/.yardoc/objects/root.dat +0 -0
  5. data/.yardoc/proxy_types +0 -0
  6. data/doc/CLIUtils/Configuration.html +373 -0
  7. data/doc/CLIUtils/Configurator.html +873 -0
  8. data/doc/CLIUtils/LoggerDelegator.html +560 -0
  9. data/doc/CLIUtils/Messenging.html +396 -0
  10. data/doc/CLIUtils/Prefs.html +609 -0
  11. data/doc/CLIUtils/PrettyIO.html +1333 -0
  12. data/doc/CLIUtils.html +131 -0
  13. data/doc/Hash.html +672 -0
  14. data/doc/Logger.html +233 -0
  15. data/doc/String.html +562 -0
  16. data/doc/_index.html +207 -0
  17. data/doc/class_list.html +54 -0
  18. data/doc/css/common.css +1 -0
  19. data/doc/css/full_list.css +57 -0
  20. data/doc/css/style.css +339 -0
  21. data/doc/file.README.html +415 -0
  22. data/doc/file_list.html +56 -0
  23. data/doc/frames.html +26 -0
  24. data/doc/index.html +415 -0
  25. data/doc/js/app.js +219 -0
  26. data/doc/js/full_list.js +178 -0
  27. data/doc/js/jquery.js +4 -0
  28. data/doc/method_list.html +389 -0
  29. data/doc/top-level-namespace.html +114 -0
  30. data/lib/cliutils/version.rb +1 -1
  31. metadata +29 -57
  32. data/.DS_Store +0 -0
  33. data/README.rdoc +0 -19
  34. data/html/CLIUtils/Configuration.html +0 -271
  35. data/html/CLIUtils/Configurator.html +0 -504
  36. data/html/CLIUtils/LoggerDelegator.html +0 -344
  37. data/html/CLIUtils/Messenging.html +0 -284
  38. data/html/CLIUtils/Prefs.html +0 -330
  39. data/html/CLIUtils/PrettyIO.html +0 -799
  40. data/html/CLIUtils.html +0 -112
  41. data/html/Hash.html +0 -453
  42. data/html/Logger.html +0 -183
  43. data/html/Object.html +0 -120
  44. data/html/README_md.html +0 -454
  45. data/html/String.html +0 -413
  46. data/html/created.rid +0 -13
  47. data/html/fonts/Lato-Light.ttf +0 -0
  48. data/html/fonts/Lato-LightItalic.ttf +0 -0
  49. data/html/fonts/Lato-Regular.ttf +0 -0
  50. data/html/fonts/Lato-RegularItalic.ttf +0 -0
  51. data/html/fonts/SourceCodePro-Bold.ttf +0 -0
  52. data/html/fonts/SourceCodePro-Regular.ttf +0 -0
  53. data/html/fonts.css +0 -167
  54. data/html/images/add.png +0 -0
  55. data/html/images/arrow_up.png +0 -0
  56. data/html/images/brick.png +0 -0
  57. data/html/images/brick_link.png +0 -0
  58. data/html/images/bug.png +0 -0
  59. data/html/images/bullet_black.png +0 -0
  60. data/html/images/bullet_toggle_minus.png +0 -0
  61. data/html/images/bullet_toggle_plus.png +0 -0
  62. data/html/images/date.png +0 -0
  63. data/html/images/delete.png +0 -0
  64. data/html/images/find.png +0 -0
  65. data/html/images/loadingAnimation.gif +0 -0
  66. data/html/images/macFFBgHack.png +0 -0
  67. data/html/images/package.png +0 -0
  68. data/html/images/page_green.png +0 -0
  69. data/html/images/page_white_text.png +0 -0
  70. data/html/images/page_white_width.png +0 -0
  71. data/html/images/plugin.png +0 -0
  72. data/html/images/ruby.png +0 -0
  73. data/html/images/tag_blue.png +0 -0
  74. data/html/images/tag_green.png +0 -0
  75. data/html/images/transparent.png +0 -0
  76. data/html/images/wrench.png +0 -0
  77. data/html/images/wrench_orange.png +0 -0
  78. data/html/images/zoom.png +0 -0
  79. data/html/index.html +0 -455
  80. data/html/js/darkfish.js +0 -140
  81. data/html/js/jquery.js +0 -18
  82. data/html/js/navigation.js +0 -142
  83. data/html/js/search.js +0 -109
  84. data/html/js/search_index.js +0 -1
  85. data/html/js/searcher.js +0 -228
  86. data/html/rdoc.css +0 -580
  87. data/html/table_of_contents.html +0 -399
data/doc/index.html ADDED
@@ -0,0 +1,415 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.7.4
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ hasFrames = window.top.frames.main ? true : false;
19
+ relpath = '';
20
+ framesUrl = "frames.html#!file.README.html";
21
+ </script>
22
+
23
+
24
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
+
26
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
+
28
+
29
+ </head>
30
+ <body>
31
+ <div id="header">
32
+ <div id="menu">
33
+
34
+ <a href="_index.html">Index</a> &raquo;
35
+ <span class="title">File: README</span>
36
+
37
+
38
+ <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
39
+ </div>
40
+
41
+ <div id="search">
42
+
43
+ <a class="full_list_link" id="class_list_link"
44
+ href="class_list.html">
45
+ Class List
46
+ </a>
47
+
48
+ <a class="full_list_link" id="method_list_link"
49
+ href="method_list.html">
50
+ Method List
51
+ </a>
52
+
53
+ <a class="full_list_link" id="file_list_link"
54
+ href="file_list.html">
55
+ File List
56
+ </a>
57
+
58
+ </div>
59
+ <div class="clear"></div>
60
+ </div>
61
+
62
+ <iframe id="search_frame"></iframe>
63
+
64
+ <div id="content"><div id='filecontents'>
65
+ <h1 id="label-CLIUtils">CLIUtils</h1>
66
+
67
+ <p>CLIUtils is a library of functionality designed to alleviate common tasks
68
+ and headaches when developing command-line (CLI) apps in Ruby.</p>
69
+
70
+ <h1 id="label-Why%3F">Why?</h1>
71
+
72
+ <p>It&#39;s fairly simple:</p>
73
+ <ol><li>
74
+ <p>I love developing Ruby-based CLI apps.</p>
75
+ </li><li>
76
+ <p>I found myself copy/pasting common code from one to another.</p>
77
+ </li><li>
78
+ <p>I decided to do something about it.</p>
79
+ </li></ol>
80
+
81
+ <h1 id="label-Installation">Installation</h1>
82
+
83
+ <p>Add this line to your application&#39;s Gemfile:</p>
84
+
85
+ <pre class="code ruby"><code class="ruby">$ gem &#39;cliutils&#39;</code></pre>
86
+
87
+ <p>And then execute:</p>
88
+
89
+ <pre class="code ruby"><code class="ruby">$ bundle</code></pre>
90
+
91
+ <p>Or install it yourself:</p>
92
+
93
+ <pre class="code ruby"><code class="ruby">$ gem install cliutils</code></pre>
94
+
95
+ <h1 id="label-Usage">Usage</h1>
96
+
97
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>cliutils</span><span class='tstring_end'>&#39;</span></span>
98
+ </code></pre>
99
+
100
+ <p>If you want to mix in everything that CLIUtils has to offer:</p>
101
+
102
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_include'>include</span> <span class='const'>CLIUtils</span></code></pre>
103
+
104
+ <p>Alternatively, as described below, mix in only the libraries that you want.</p>
105
+
106
+ <p>Note that although this README.md is extensive, it may not cover all
107
+ methods. Check out the <a
108
+ href="https://github.com/bachya/cli-utils/tree/master/test">tests</a> to
109
+ see more examples.</p>
110
+
111
+ <h1 id="label-Libraries">Libraries</h1>
112
+
113
+ <p>CLIUtils offers:</p>
114
+ <ul><li>
115
+ <p><a href="https://github.com/bachya/cli-utils#prettyio">PrettyIO</a>:
116
+ nicer-looking CLI messages</p>
117
+ </li><li>
118
+ <p><a href="https://github.com/bachya/cli-utils#messenging">Messenging</a>: a
119
+ full-featured Logger</p>
120
+ </li><li>
121
+ <p><a
122
+ href="https://github.com/bachya/cli-utils#configuration">Configuration</a>:
123
+ a app configuration manager</p>
124
+ </li><li>
125
+ <p><a href="https://github.com/bachya/cli-utils#prefs">Prefs</a>: a
126
+ preferences prompter and manager</p>
127
+ </li></ul>
128
+
129
+ <h2 id="label-PrettyIO">PrettyIO</h2>
130
+
131
+ <p>First stop on our journey is better client IO. To activate, simply mix into
132
+ your project:</p>
133
+
134
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_include'>include</span> <span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>PrettyIO</span>
135
+ </code></pre>
136
+
137
+ <p>PrettyIO affords you colorized strings:</p>
138
+
139
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>A sample string</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_red'>red</span>
140
+ </code></pre>
141
+
142
+ <p><img
143
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prettyio-red-text.png"></p>
144
+
145
+ <p>PrettyIO gives you utility methods for the common ANSI color codes:</p>
146
+
147
+ <pre class="code ruby"><code class="ruby"><span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_blue'>blue</span>
148
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_cyan'>cyan</span>
149
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_green'>green</span>
150
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_purple'>purple</span>
151
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_red'>red</span>
152
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_white'>white</span>
153
+ <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_yellow'>yellow</span>
154
+ </code></pre>
155
+
156
+ <p>You also get the <code>colorize</code> method, which allows you to define
157
+ more complex color combinations. For example, to get some nice purple text
158
+ on a gnarly green background:</p>
159
+
160
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>A sample string</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_colorize'>colorize</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>35;42</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
161
+ </code></pre>
162
+
163
+ <p><img
164
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prettyio-gnarly-text.png"></p>
165
+
166
+ <p>Naturally, memorizing the ANSI color scheme is a pain, so PrettyIO gives
167
+ you a convenient method to look up these color combinations:</p>
168
+
169
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_color_chart'>color_chart</span>
170
+ </code></pre>
171
+
172
+ <p><img
173
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prettyio-color-chart.png"></p>
174
+
175
+ <h2 id="label-Messenging">Messenging</h2>
176
+
177
+ <p>Throughout the life of your application, you will most likely want to send
178
+ several messages to your user (warnings, errors, info, etc.). Messenging
179
+ makes this a snap. It, too, is a mixin:</p>
180
+
181
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_include'>include</span> <span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>Messenging</span>
182
+ </code></pre>
183
+
184
+ <p>Once mixed in, you get access to <code>messenger</code>, a type of Logger
185
+ that uses PrettyIO to send nicely-formatted messages to your user. For
186
+ example, if you&#39;d like to warn your user:</p>
187
+
188
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Hey pal, you need to be careful.</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
189
+ </code></pre>
190
+
191
+ <p><img
192
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/messenger-warn.png"></p>
193
+
194
+ <h3 id="label-Messenging+Methods">Messenging Methods</h3>
195
+
196
+ <p><code>messenger</code> gives you access to several basic methods:</p>
197
+ <ul><li>
198
+ <p><code>messenger.error</code>: used to show a formatted-red error message.</p>
199
+ </li><li>
200
+ <p><code>messenger.info</code>: used to show a formatted-blue infomational
201
+ message.</p>
202
+ </li><li>
203
+ <p><code>messenger.section</code>: used to show a formatted-purple sectional
204
+ message.</p>
205
+ </li><li>
206
+ <p><code>messenger.success</code>: used to show a formatted-green success
207
+ message.</p>
208
+ </li><li>
209
+ <p><code>messenger.yellow</code>: used to show a formatted-yellow warning
210
+ message.</p>
211
+ </li></ul>
212
+
213
+ <p>Let&#39;s see an example that uses them all:</p>
214
+
215
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_section'>section</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>STARTING ATTACK RUN...</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
216
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Beginning strafing run...</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
217
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>WARNING: Tie Fighters approaching!</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
218
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Porkins died :(</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
219
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>But Luke still blew up the Death Star!</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span></code></pre>
220
+
221
+ <p><img
222
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/messenger-types-1.png"></p>
223
+
224
+ <p><code>messenger</code> also includes two “block” methods that allow you to
225
+ wrap program execution in messages that are “longer-term”.</p>
226
+
227
+ <pre class="code ruby"><code class="ruby">messenger.info_block(&#39;Starting up...&#39;, &#39;Done!&#39;, multiline = false) { # do stuff here }</code></pre>
228
+
229
+ <p><code>messenger</code> outputs &#39;Starting up…&#39;, runs the code in
230
+ <code># do stuff here</code>, and once complete, outputs &#39;Done!&#39; on
231
+ the same line. Note that <code>section_block</code> is the same exact
232
+ signature (except for the method name, of course!).</p>
233
+
234
+ <h3 id="label-Message+Wrapping">Message Wrapping</h3>
235
+
236
+ <p>PrettyIO also gives <code>messenger</code> the ability to wrap your
237
+ messages so that they don&#39;t span off into infinity. You can even
238
+ control what the wrap limit (in characters) is:</p>
239
+
240
+ <pre class="code ruby"><code class="ruby"><span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>PrettyIO</span><span class='op'>::</span><span class='id identifier rubyid_wrap_at'>wrap_at</span><span class='lparen'>(</span><span class='int'>50</span><span class='rparen'>)</span>
241
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
242
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_end'>&#39;</span></span>
243
+ <span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>PrettyIO</span><span class='op'>::</span><span class='id identifier rubyid_wrap_at'>wrap_at</span><span class='lparen'>(</span><span class='int'>20</span><span class='rparen'>)</span>
244
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
245
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_end'>&#39;</span></span>
246
+ <span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>PrettyIO</span><span class='op'>::</span><span class='id identifier rubyid_wrap'>wrap</span><span class='lparen'>(</span><span class='kw'>false</span><span class='rparen'>)</span>
247
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This is a really long message, okay? It should wrap at some point. Seriously. Wrapping is nice.</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span></code></pre>
248
+
249
+ <p><img
250
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/wrapping.png"></p>
251
+
252
+ <h3 id="label-Prompting">Prompting</h3>
253
+
254
+ <p><code>messenger</code> also carries a convenient method to prompt your
255
+ users to give input (including an optional default). It makes use of
256
+ <code>readline</code>, so you can do cool things like text expansion of
257
+ paths.</p>
258
+
259
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_p'>p</span> <span class='op'>=</span> <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_prompt'>prompt</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Are you a fan of Battlestar Galactica?</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='id identifier rubyid_default'>default</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Y</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
260
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>You answered: </span><span class='embexpr_beg'>#{</span> <span class='id identifier rubyid_p'>p</span> <span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span></code></pre>
261
+
262
+ <p><img
263
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/prompting.png"></p>
264
+
265
+ <h3 id="label-Logging">Logging</h3>
266
+
267
+ <p>Often, it&#39;s desirable to log messages as they appear to your user.
268
+ <code>messenging</code> makes this a breeze by allowing you to attach and
269
+ detach Logger instances at will.</p>
270
+
271
+ <p>For instance, let&#39;s say you wanted to log a few messages to both your
272
+ user&#39;s STDOUT and to <code>file.txt</code>:</p>
273
+
274
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_file_logger'>file_logger</span> <span class='op'>=</span> <span class='const'>Logger</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>file.txt</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
275
+
276
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This should only appear in STDOUT.</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
277
+
278
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_attach'>attach</span><span class='lparen'>(</span><span class='id identifier rubyid_file_logger'>file_logger</span><span class='rparen'>)</span>
279
+
280
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This warning should appear in STDOUT and file.txt</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
281
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This error should appear in STDOUT and file.txt</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
282
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_debug'>debug</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This debug message should only appear in file.txt</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
283
+
284
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_detach'>detach</span><span class='lparen'>(</span><span class='id identifier rubyid_file_logger'>file_logger</span><span class='rparen'>)</span>
285
+
286
+ <span class='id identifier rubyid_messenger'>messenger</span><span class='period'>.</span><span class='id identifier rubyid_section'>section</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This section message should appear only in STDOUT</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span></code></pre>
287
+
288
+ <p>In STDOUT:</p>
289
+
290
+ <p><img
291
+ src="https://raw.githubusercontent.com/bachya/cli-utils/master/res/readme-images/multi-logger.png"></p>
292
+
293
+ <p>…and in <code>file.txt</code>:</p>
294
+
295
+ <pre class="code ruby"><code class="ruby">W, [2014-03-29T15:14:34.844406 #4497] WARN -- : This warning should appear in STDOUT and file.txt
296
+ E, [2014-03-29T15:14:34.844553 #4497] ERROR -- : This error should appear in STDOUT and file.txt
297
+ D, [2014-03-29T15:14:34.844609 #4497] DEBUG -- : This debug message should only appear in file.txt</code></pre>
298
+
299
+ <p>Since you can attach Logger objects, each can have it&#39;s own format and
300
+ severity level. Cool!</p>
301
+
302
+ <h2 id="label-Configuration">Configuration</h2>
303
+
304
+ <p>CLIUtils offers two “things” – a <code>Configurator</code> class and a
305
+ <code>Configuration</code> module that provides access to a shared instance
306
+ of <code>Configurator</code> – that make managing a user&#39;s
307
+ configuration parameters easy. Mix it in!</p>
308
+
309
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_include'>include</span> <span class='const'>CLIUtils</span><span class='op'>::</span><span class='const'>Configuration</span></code></pre>
310
+
311
+ <h3 id="label-Loading+a+Configuration+File">Loading a Configuration File</h3>
312
+
313
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_load_configuration'>load_configuration</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>~/.my-app-config</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span></code></pre>
314
+
315
+ <p>If there&#39;s data in there, it will be consumed into
316
+ <code>configuration</code>&#39;s <code>data</code> property.</p>
317
+
318
+ <h3 id="label-Adding%2FRemoving+Sections">Adding/Removing Sections</h3>
319
+
320
+ <p>Sections are top levels of the configuration file and are managed via the
321
+ <code>configuration</code> object:</p>
322
+
323
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_add_section'>add_section</span><span class='lparen'>(</span><span class='symbol'>:user_data</span><span class='rparen'>)</span>
324
+ <span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_add_section'>add_section</span><span class='lparen'>(</span><span class='symbol'>:program_data</span><span class='rparen'>)</span>
325
+ <span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_delete_section'>delete_section</span><span class='lparen'>(</span><span class='symbol'>:program_data</span><span class='rparen'>)</span></code></pre>
326
+
327
+ <h3 id="label-Adding+Data+to+Sections">Adding Data to Sections</h3>
328
+
329
+ <p>There are two ways data can be managed in <code>configuration</code>: via
330
+ its <code>@data</code> property or via some magic methods; your call:</p>
331
+
332
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:user_data</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_merge!'>merge!</span><span class='lparen'>(</span><span class='label'>username:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>bob</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
333
+ <span class='comment'># OR
334
+ </span><span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_user_data'>user_data</span><span class='period'>.</span><span class='id identifier rubyid_merge!'>merge!</span><span class='lparen'>(</span><span class='label'>username:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>bob</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span></code></pre>
335
+
336
+ <h3 id="label-Saving+to+a+File">Saving to a File</h3>
337
+
338
+ <p>When you&#39;re ready to save your configuration data to a YAML file:</p>
339
+
340
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_configuration'>configuration</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span></code></pre>
341
+
342
+ <p>Note that all your keys are converted to strings before saving (and,
343
+ likewise, are converted to symbols, when loading). Assuming we used the
344
+ commands above, we could expect this to be the contents of
345
+ <code>~/.my-app-config</code>:</p>
346
+
347
+ <pre class="code ruby"><code class="ruby">---
348
+ user_data:
349
+ username: bob</code></pre>
350
+
351
+ <h1 id="label-Known+Issues">Known Issues</h1>
352
+ <ul><li>
353
+ <p>LoggerDelegator doesn&#39;t currently know what to do with
354
+ <code>messenger.prompt</code>, so you&#39;ll have to manually log a
355
+ <code>debug</code> message if you want that information logged.</p>
356
+ </li></ul>
357
+
358
+ <h1 id="label-Bugs+and+Feature+Requests">Bugs and Feature Requests</h1>
359
+
360
+ <p>To report bugs with or suggest features/changes for CLIUtils, please use
361
+ the <a href="http://github.com/bachya/cli-utils/issues">Issues Page</a>.</p>
362
+
363
+ <h1 id="label-Contributing">Contributing</h1>
364
+
365
+ <p>Contributions are welcome and encouraged. To contribute:</p>
366
+ <ol><li>
367
+ <p>Fork it ( <a
368
+ href="http://github.com/bachya/cliutils/fork">github.com/bachya/cliutils/fork</a>
369
+ )</p>
370
+ </li><li>
371
+ <p>Create your feature branch (<code>git checkout -b my-new-feature</code>)</p>
372
+ </li><li>
373
+ <p>Commit your changes (<code>git commit -am &#39;Add some
374
+ feature&#39;</code>)</p>
375
+ </li><li>
376
+ <p>Push to the branch (<code>git push origin my-new-feature</code>)</p>
377
+ </li><li>
378
+ <p>Create new Pull Request</p>
379
+ </li></ol>
380
+
381
+ <h1 id="label-License">License</h1>
382
+
383
+ <p>(The MIT License)</p>
384
+
385
+ <p>Copyright © 2014 Aaron Bach <a
386
+ href="mailto:bachya1208@gmail.com">bachya1208@gmail.com</a></p>
387
+
388
+ <p>Permission is hereby granted, free of charge, to any person obtaining a
389
+ copy of this software and associated documentation files (the
390
+ &#39;Software&#39;), to deal in the Software without restriction, including
391
+ without limitation the rights to use, copy, modify, merge, publish,
392
+ distribute, sublicense, and/or sell copies of the Software, and to permit
393
+ persons to whom the Software is furnished to do so, subject to the
394
+ following conditions:</p>
395
+
396
+ <p>The above copyright notice and this permission notice shall be included in
397
+ all copies or substantial portions of the Software.</p>
398
+
399
+ <p>THE SOFTWARE IS PROVIDED &#39;AS IS&#39;, WITHOUT WARRANTY OF ANY KIND,
400
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
401
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
402
+ NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
403
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
404
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
405
+ USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
406
+ </div></div>
407
+
408
+ <div id="footer">
409
+ Generated on Sat Mar 29 17:22:02 2014 by
410
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
411
+ 0.8.7.4 (ruby-2.1.0).
412
+ </div>
413
+
414
+ </body>
415
+ </html>
data/doc/js/app.js ADDED
@@ -0,0 +1,219 @@
1
+ function createSourceLinks() {
2
+ $('.method_details_list .source_code').
3
+ before("<span class='showSource'>[<a href='#' class='toggleSource'>View source</a>]</span>");
4
+ $('.toggleSource').toggle(function() {
5
+ $(this).parent().nextAll('.source_code').slideDown(100);
6
+ $(this).text("Hide source");
7
+ },
8
+ function() {
9
+ $(this).parent().nextAll('.source_code').slideUp(100);
10
+ $(this).text("View source");
11
+ });
12
+ }
13
+
14
+ function createDefineLinks() {
15
+ var tHeight = 0;
16
+ $('.defines').after(" <a href='#' class='toggleDefines'>more...</a>");
17
+ $('.toggleDefines').toggle(function() {
18
+ tHeight = $(this).parent().prev().height();
19
+ $(this).prev().show();
20
+ $(this).parent().prev().height($(this).parent().height());
21
+ $(this).text("(less)");
22
+ },
23
+ function() {
24
+ $(this).prev().hide();
25
+ $(this).parent().prev().height(tHeight);
26
+ $(this).text("more...");
27
+ });
28
+ }
29
+
30
+ function createFullTreeLinks() {
31
+ var tHeight = 0;
32
+ $('.inheritanceTree').toggle(function() {
33
+ tHeight = $(this).parent().prev().height();
34
+ $(this).parent().toggleClass('showAll');
35
+ $(this).text("(hide)");
36
+ $(this).parent().prev().height($(this).parent().height());
37
+ },
38
+ function() {
39
+ $(this).parent().toggleClass('showAll');
40
+ $(this).parent().prev().height(tHeight);
41
+ $(this).text("show all");
42
+ });
43
+ }
44
+
45
+ function fixBoxInfoHeights() {
46
+ $('dl.box dd.r1, dl.box dd.r2').each(function() {
47
+ $(this).prev().height($(this).height());
48
+ });
49
+ }
50
+
51
+ function searchFrameLinks() {
52
+ $('.full_list_link').click(function() {
53
+ toggleSearchFrame(this, $(this).attr('href'));
54
+ return false;
55
+ });
56
+ }
57
+
58
+ function toggleSearchFrame(id, link) {
59
+ var frame = $('#search_frame');
60
+ $('#search a').removeClass('active').addClass('inactive');
61
+ if (frame.attr('src') == link && frame.css('display') != "none") {
62
+ frame.slideUp(100);
63
+ $('#search a').removeClass('active inactive');
64
+ }
65
+ else {
66
+ $(id).addClass('active').removeClass('inactive');
67
+ frame.attr('src', link).slideDown(100);
68
+ }
69
+ }
70
+
71
+ function linkSummaries() {
72
+ $('.summary_signature').click(function() {
73
+ document.location = $(this).find('a').attr('href');
74
+ });
75
+ }
76
+
77
+ function framesInit() {
78
+ if (hasFrames) {
79
+ document.body.className = 'frames';
80
+ $('#menu .noframes a').attr('href', document.location);
81
+ try {
82
+ window.top.document.title = $('html head title').text();
83
+ } catch(error) {
84
+ // some browsers will not allow this when serving from file://
85
+ // but we don't want to stop the world.
86
+ }
87
+ }
88
+ else {
89
+ $('#menu .noframes a').text('frames').attr('href', framesUrl);
90
+ }
91
+ }
92
+
93
+ function keyboardShortcuts() {
94
+ if (window.top.frames.main) return;
95
+ $(document).keypress(function(evt) {
96
+ if (evt.altKey || evt.ctrlKey || evt.metaKey || evt.shiftKey) return;
97
+ if (typeof evt.target !== "undefined" &&
98
+ (evt.target.nodeName == "INPUT" ||
99
+ evt.target.nodeName == "TEXTAREA")) return;
100
+ switch (evt.charCode) {
101
+ case 67: case 99: $('#class_list_link').click(); break; // 'c'
102
+ case 77: case 109: $('#method_list_link').click(); break; // 'm'
103
+ case 70: case 102: $('#file_list_link').click(); break; // 'f'
104
+ default: break;
105
+ }
106
+ });
107
+ }
108
+
109
+ function summaryToggle() {
110
+ $('.summary_toggle').click(function() {
111
+ if (localStorage) {
112
+ localStorage.summaryCollapsed = $(this).text();
113
+ }
114
+ $('.summary_toggle').each(function() {
115
+ $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
116
+ var next = $(this).parent().parent().nextAll('ul.summary').first();
117
+ if (next.hasClass('compact')) {
118
+ next.toggle();
119
+ next.nextAll('ul.summary').first().toggle();
120
+ }
121
+ else if (next.hasClass('summary')) {
122
+ var list = $('<ul class="summary compact" />');
123
+ list.html(next.html());
124
+ list.find('.summary_desc, .note').remove();
125
+ list.find('a').each(function() {
126
+ $(this).html($(this).find('strong').html());
127
+ $(this).parent().html($(this)[0].outerHTML);
128
+ });
129
+ next.before(list);
130
+ next.toggle();
131
+ }
132
+ });
133
+ return false;
134
+ });
135
+ if (localStorage) {
136
+ if (localStorage.summaryCollapsed == "collapse") {
137
+ $('.summary_toggle').first().click();
138
+ }
139
+ else localStorage.summaryCollapsed = "expand";
140
+ }
141
+ }
142
+
143
+ function fixOutsideWorldLinks() {
144
+ $('a').each(function() {
145
+ if (window.location.host != this.host) this.target = '_parent';
146
+ });
147
+ }
148
+
149
+ function generateTOC() {
150
+ if ($('#filecontents').length === 0) return;
151
+ var _toc = $('<ol class="top"></ol>');
152
+ var show = false;
153
+ var toc = _toc;
154
+ var counter = 0;
155
+ var tags = ['h2', 'h3', 'h4', 'h5', 'h6'];
156
+ var i;
157
+ if ($('#filecontents h1').length > 1) tags.unshift('h1');
158
+ for (i = 0; i < tags.length; i++) { tags[i] = '#filecontents ' + tags[i]; }
159
+ var lastTag = parseInt(tags[0][1], 10);
160
+ $(tags.join(', ')).each(function() {
161
+ if ($(this).parents('.method_details .docstring').length != 0) return;
162
+ if (this.id == "filecontents") return;
163
+ show = true;
164
+ var thisTag = parseInt(this.tagName[1], 10);
165
+ if (this.id.length === 0) {
166
+ var proposedId = $(this).attr('toc-id');
167
+ if (typeof(proposedId) != "undefined") this.id = proposedId;
168
+ else {
169
+ var proposedId = $(this).text().replace(/[^a-z0-9-]/ig, '_');
170
+ if ($('#' + proposedId).length > 0) { proposedId += counter; counter++; }
171
+ this.id = proposedId;
172
+ }
173
+ }
174
+ if (thisTag > lastTag) {
175
+ for (i = 0; i < thisTag - lastTag; i++) {
176
+ var tmp = $('<ol/>'); toc.append(tmp); toc = tmp;
177
+ }
178
+ }
179
+ if (thisTag < lastTag) {
180
+ for (i = 0; i < lastTag - thisTag; i++) toc = toc.parent();
181
+ }
182
+ var title = $(this).attr('toc-title');
183
+ if (typeof(title) == "undefined") title = $(this).text();
184
+ toc.append('<li><a href="#' + this.id + '">' + title + '</a></li>');
185
+ lastTag = thisTag;
186
+ });
187
+ if (!show) return;
188
+ html = '<div id="toc"><p class="title"><a class="hide_toc" href="#"><strong>Table of Contents</strong></a> <small>(<a href="#" class="float_toc">left</a>)</small></p></div>';
189
+ $('#content').prepend(html);
190
+ $('#toc').append(_toc);
191
+ $('#toc .hide_toc').toggle(function() {
192
+ $('#toc .top').slideUp('fast');
193
+ $('#toc').toggleClass('hidden');
194
+ $('#toc .title small').toggle();
195
+ }, function() {
196
+ $('#toc .top').slideDown('fast');
197
+ $('#toc').toggleClass('hidden');
198
+ $('#toc .title small').toggle();
199
+ });
200
+ $('#toc .float_toc').toggle(function() {
201
+ $(this).text('float');
202
+ $('#toc').toggleClass('nofloat');
203
+ }, function() {
204
+ $(this).text('left');
205
+ $('#toc').toggleClass('nofloat');
206
+ });
207
+ }
208
+
209
+ $(framesInit);
210
+ $(createSourceLinks);
211
+ $(createDefineLinks);
212
+ $(createFullTreeLinks);
213
+ $(fixBoxInfoHeights);
214
+ $(searchFrameLinks);
215
+ $(linkSummaries);
216
+ $(keyboardShortcuts);
217
+ $(summaryToggle);
218
+ $(fixOutsideWorldLinks);
219
+ $(generateTOC);