mucgly 0.0.1

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.
@@ -0,0 +1,390 @@
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=US-ASCII" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.6.1
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#!" + escape(window.location.href);
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>Mucgly</h1>
66
+
67
+ <h2>Introduction</h2>
68
+
69
+ <p>Mucgly is a macro expander for inline macros that exist in the middle of
70
+ body text. The macros are mostly regular Ruby code, but a few special
71
+ commands is also provided.</p>
72
+
73
+ <p>A very simple example:</p>
74
+
75
+ <pre class="code ruby"><code class="ruby">Adding 1 + 3 results: -&lt;write (1+3).to_s&gt;-</code></pre>
76
+
77
+ <p>After macro expansion the results is:</p>
78
+
79
+ <pre class="code ruby"><code class="ruby">Adding 1 + 3 results: 4</code></pre>
80
+
81
+ <p>By default macro starts with "-&lt;" and ends with "&gt;-". These limiters
82
+ are called hooks, hookbeg and hookend respectively. The code between hooks
83
+ is regular Ruby code. The "write" call writes to selected IO stream.</p>
84
+
85
+ <p>Ruby code is executed within a class instance reserved for this purpose.
86
+ The instance is called the Execution Environment. It enables values from
87
+ one macro to be visible in others.</p>
88
+
89
+ <p>Previous example with multiple macros:</p>
90
+
91
+ <pre class="code ruby"><code class="ruby">-&lt;@a = 1&gt;--&lt;@b = 3&gt;-\
92
+ Adding 1 + 3 results: -&lt;write (@a+@b).to_s&gt;-</code></pre>
93
+
94
+ <p>Result is exactly the same as in the previous execution. The first macro
95
+ "-&lt;@a = 1&gt;-" produces no output, it just sets the variable "@a" to
96
+ "1". Second macro is similar. The default "escape" character is "\". When
97
+ placed before newline character, it "eats" the newline and nothing is
98
+ output. Thus the first line outputs nothing.</p>
99
+
100
+ <p>The second line refers to settings from previous macros. Instance variables
101
+ has to be used to maintain the data between macro calls (due to instance
102
+ evaluation).</p>
103
+
104
+ <h2>Features</h2>
105
+ <ul><li>
106
+ <p>User settable hooks to define macro boundaries. Can be set from command
107
+ line, configuration files, or from macro file.</p>
108
+ </li><li>
109
+ <p>Multiple sources for configuration: default config, environment variable,
110
+ command line.</p>
111
+ </li><li>
112
+ <p>Multiple passes for macro file.</p>
113
+ </li><li>
114
+ <p>Convention based output file naming.</p>
115
+ </li><li>
116
+ <p>Multiple convenience functions for macros to use.</p>
117
+ </li><li>
118
+ <p>Macro file introspection: line number, file name</p>
119
+ </li><li>
120
+ <p>Output stream de-muxing.</p>
121
+ </li><li>
122
+ <p>Many special commands: include, source, etc...</p>
123
+ </li></ul>
124
+
125
+ <h2>Applications</h2>
126
+ <ul><li>
127
+ <p>Replacement for M4 macro processor.</p>
128
+ </li><li>
129
+ <p>Code generation.</p>
130
+ </li><li>
131
+ <p>Document formatting.</p>
132
+ </li><li>
133
+ <p>Etc.</p>
134
+ </li></ul>
135
+
136
+ <h2>Special characters</h2>
137
+
138
+ <h3>Hooks</h3>
139
+
140
+ <p>Hooks start and end the macro definition. By default hookbeg is "-&lt;" and
141
+ hookend is "&gt;-". These values are not easily conflicting with the macro
142
+ file body text.</p>
143
+
144
+ <p>If literal hook string is required, the escape character should be place
145
+ before the hook. For example "-&lt;" will produce literal "-&lt;" to the
146
+ output.</p>
147
+
148
+ <p>User can set the hooks to whatever string value desired. The hooks can also
149
+ have the same value. However nested macros are not possible then. Hooks can
150
+ also be the same as the escape character, but this makes usage somewhat
151
+ complicated.</p>
152
+
153
+ <h3>Escape</h3>
154
+
155
+ <p>Default escape character is "\". It can be used to escape hooks, cancel
156
+ space (" ") output, and cancel newline ("\n") output.</p>
157
+
158
+ <p>User can set the escape character to any character. Only single character
159
+ value is accepted.</p>
160
+
161
+ <h3>Multipass</h3>
162
+
163
+ <p>If the macro starts with "#" character, the macro is not expanded. One "#"
164
+ character is removed and the rest of the macro is output as it is. Each
165
+ pass will remove one "#" character and when all are removed, the macro is
166
+ evaluated. Usually two passes are enough and one "#" character is used to
167
+ save a macro to the later pass.</p>
168
+
169
+ <p>Multipass can be used for example to create a Table Of Contents. First pass
170
+ collects information about document content and second pass will insert the
171
+ Table Of Contents.</p>
172
+
173
+ <p>Example, with functions (insert_toc, header...) defined elsewhere:</p>
174
+
175
+ <pre class="code ruby"><code class="ruby">-&lt;#insert_toc&gt;-
176
+ -&lt;header(1, &quot;My header 1&quot;)&gt;-
177
+ Paragraph1
178
+ -&lt;header(2, &quot;My header 1.1&quot;)&gt;-
179
+ Paragraph2
180
+ -&lt;header(1, &quot;My header 2&quot;)&gt;-
181
+ Paragraph3</code></pre>
182
+
183
+ <h2>Special commands</h2>
184
+
185
+ <p>In addition to regular Ruby code the macros are allowed to include so
186
+ called Special Commands. These commands start with the ":" characters and
187
+ with ".".</p>
188
+
189
+ <p>Example:</p>
190
+
191
+ <pre class="code ruby"><code class="ruby">...
192
+ -&lt;:hook [ ]-&gt;\
193
+ ...</code></pre>
194
+
195
+ <p>Would change the hookbeg and hookend to "[" and "]" respectively. One
196
+ special command is allowed per macro and it can't be mixed normal Ruby
197
+ code. Command name is separated by ":" in the beginning and by space (" ")
198
+ in the end. The rest of the macro is taken as argument to the macro. Note
199
+ that a command without an argument has to end with space as well.</p>
200
+
201
+ <p>List of ":" style special commands:</p>
202
+ <dl class="rdoc-list"><dt>include</dt>
203
+ <dd>
204
+ <p>Include reverts the input stream to the file given in the argument. Command
205
+ can be used to multiplex multiple files into one, for example.</p>
206
+ </dd><dt>output</dt>
207
+ <dd>
208
+ <p>Select a new output file. Use with "close" command, when the new output
209
+ file is ready.</p>
210
+ </dd><dt>comment</dt>
211
+ <dd>
212
+ <p>Comment is used to add comments into the macro file. No output is produced
213
+ from comment macros.</p>
214
+ </dd><dt>source</dt>
215
+ <dd>
216
+ <p>Source reads a plain Ruby file into the Execution Environment.</p>
217
+ </dd><dt>hook</dt>
218
+ <dd>
219
+ <p>Sets both hookbeg and hookend to values separated by space. The new hook
220
+ values are valid immediately after the enclosing macro.</p>
221
+ </dd><dt>hookbeg</dt>
222
+ <dd>
223
+ <p>Sets hookbeg.</p>
224
+ </dd><dt>hookend</dt>
225
+ <dd>
226
+ <p>Sets hookend.</p>
227
+ </dd><dt>escape</dt>
228
+ <dd>
229
+ <p>Sets escape character.</p>
230
+ </dd><dt>exit</dt>
231
+ <dd>
232
+ <p>Aborts the macro file.</p>
233
+ </dd></dl>
234
+
235
+ <p>Variable value reference command starts with "." and is followed by the
236
+ (instance) variable name.</p>
237
+
238
+ <p>For example:</p>
239
+
240
+ <pre class="code ruby"><code class="ruby">... -&lt;.my_name&gt;- ...</code></pre>
241
+
242
+ <p>Would write out the value of the "@my_name" variable, thus it is equal to
243
+ writing:</p>
244
+
245
+ <pre class="code ruby"><code class="ruby">... -&lt;write @my_name&gt;- ...</code></pre>
246
+
247
+ <h2>API methods</h2>
248
+
249
+ <p>API methods are instance methods of the Execution Environment, i.e. they
250
+ are predefined and visible for the macro code. These methods are organized
251
+ into two categories: Published and Hidden.</p>
252
+
253
+ <h3>Published methods</h3>
254
+
255
+ <p>Published methods are the most commonly used methods in macros. These are:</p>
256
+ <dl class="rdoc-list"><dt>write</dt>
257
+ <dd>
258
+ <p>Writes string into selected output IO.</p>
259
+ </dd><dt>puts</dt>
260
+ <dd>
261
+ <p>Writes string (+newline) into selected output IO.</p>
262
+ </dd><dt>source</dt>
263
+ <dd>
264
+ <p>Sources a plain Ruby file.</p>
265
+ </dd></dl>
266
+
267
+ <h3>Hidden methods</h3>
268
+
269
+ <p>Hidded methods start with underscore ("_"). The naming is used to prevent
270
+ poluting the Execution Environment's namespace.</p>
271
+ <dl class="rdoc-list"><dt>_processFilePair</dt>
272
+ <dd>
273
+ <p>Process a pair of files. First half is input file and second is output
274
+ file. File pair argument is an Array of two ([&lt;fileI&gt;,
275
+ &lt;fileO&gt;]).</p>
276
+ </dd><dt>_processFilePairs</dt>
277
+ <dd>
278
+ <p>Uses "_processFilePair" to process a list of file pairs.</p>
279
+ </dd><dt>_openInput</dt>
280
+ <dd>
281
+ <p>Sets input stream to given file. When this file is closed, the input stream
282
+ is reverted to the original file.</p>
283
+ </dd><dt>_openOutput</dt>
284
+ <dd>
285
+ <p>Sets output stream to given file. When this file is closed, the input
286
+ stream is reverted to the original file.</p>
287
+ </dd><dt>_openString</dt>
288
+ <dd>
289
+ <p>Open a StringIO file for output.</p>
290
+ </dd><dt>_pushInput</dt>
291
+ <dd>
292
+ <p>Makes given file as top input stream. When this stream is closed, the input
293
+ stream is reverted to the original file.</p>
294
+ </dd><dt>_pushOutput</dt>
295
+ <dd>
296
+ <p>Makes given file as top output stream. When this stream is closed, the
297
+ output stream is reverted to the original file.</p>
298
+ </dd><dt>_closeInput</dt>
299
+ <dd>
300
+ <p>Close input stream.</p>
301
+ </dd><dt>_closeOutput</dt>
302
+ <dd>
303
+ <p>Close output stream.</p>
304
+ </dd><dt>_ofilename</dt>
305
+ <dd>
306
+ <p>Output file name as String.</p>
307
+ </dd><dt>_olinenumber</dt>
308
+ <dd>
309
+ <p>Output file line number.</p>
310
+ </dd><dt>_ifilename</dt>
311
+ <dd>
312
+ <p>Input file name as String.</p>
313
+ </dd><dt>_ilinenumber</dt>
314
+ <dd>
315
+ <p>Input file line number.</p>
316
+ </dd><dt>_eval</dt>
317
+ <dd>
318
+ <p>Perform instance_eval on the given argument.</p>
319
+ </dd><dt>_inIO</dt>
320
+ <dd>
321
+ <p>Handle to input stream (get/set).</p>
322
+ </dd><dt>_outIO</dt>
323
+ <dd>
324
+ <p>Handle to output stream (get/set).</p>
325
+ </dd><dt>_separators</dt>
326
+ <dd>
327
+ <p>Handle to Separators object. Separotors object includes the "escapeChar",
328
+ "hookBegChars", and "hookEndChars" setter and getter methods.</p>
329
+ </dd></dl>
330
+
331
+ <h2>Command line interface</h2>
332
+
333
+ <p>Please execute:</p>
334
+
335
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_mucgly'>mucgly</span> <span class='op'>-</span><span class='id identifier rubyid_h'>h</span></code></pre>
336
+
337
+ <p>for an overview of the command line options.</p>
338
+
339
+ <h3>Input and Output files</h3>
340
+
341
+ <p>Input files can be listed to "-i" option. The default input stream for
342
+ Mucgly is STDIN.</p>
343
+
344
+ <p>Output files can be listed to "-o" option. The default output stream for
345
+ Mucgly is STDOUT.</p>
346
+
347
+ <p>If "-o" option is given without arguments and the input file list includes
348
+ ".rx" in each name, the output file list is created by extracting ".rx"
349
+ from each input file name.</p>
350
+
351
+ <p>For example with:</p>
352
+
353
+ <pre class="code ruby"><code class="ruby">mucgly -i foo.rx.txt bar.rx.txt -o</code></pre>
354
+
355
+ <p>Two files, foo.txt and bar.txt, would be created. This holds true unless
356
+ the output streams are manipulated with macro commands.</p>
357
+
358
+ <p>If the number of input and output files match, then they are used in pairs.</p>
359
+
360
+ <h2>Configuration</h2>
361
+
362
+ <p>Mucgly checks for the existance of the "MUCGLY" environment variable. If
363
+ the variable exists, the file in variable value is read in as plain Ruby.</p>
364
+
365
+ <p>User configuration is searched from the users home directory:</p>
366
+
367
+ <pre class="code ruby"><code class="ruby">$HOME/.mucgly</code></pre>
368
+
369
+ <p>It is read as plain Ruby file if it exists.</p>
370
+
371
+ <p>Configuration files can also be given on command line using the "-c"
372
+ option. These settings can be used to override the settings above.</p>
373
+
374
+ <p>Additionally plain Ruby code can be given straight on the command line with
375
+ "-l" option.</p>
376
+
377
+ <h2>More information</h2>
378
+
379
+ <p>Check out the "test" directory within installation for detailed examples
380
+ about usage.</p>
381
+ </div></div>
382
+
383
+ <div id="footer">
384
+ Generated on Wed Jan 15 19:29:44 2014 by
385
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
386
+ 0.8.6.1 (ruby-1.9.3).
387
+ </div>
388
+
389
+ </body>
390
+ </html>
@@ -0,0 +1,58 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html>
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <base id="base_target" target="_parent" />
19
+ </head>
20
+ <body>
21
+ <script type="text/javascript" charset="utf-8">
22
+ if (window.top.frames.main) {
23
+ document.getElementById('base_target').target = 'main';
24
+ document.body.className = 'frames';
25
+ }
26
+ </script>
27
+ <div id="content">
28
+ <h1 id="full_list_header">File List</h1>
29
+ <div id="nav">
30
+
31
+ <span><a target="_self" href="class_list.html">
32
+ Classes
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="method_list.html">
36
+ Methods
37
+ </a></span>
38
+
39
+ <span><a target="_self" href="file_list.html">
40
+ Files
41
+ </a></span>
42
+
43
+ </div>
44
+ <div id="search">Search: <input type="text" /></div>
45
+
46
+ <ul id="full_list" class="file">
47
+
48
+
49
+ <li class="r1"><span class="object_link"><a href="index.html" title="README">README</a></a></li>
50
+
51
+
52
+ <li class="r2"><span class="object_link"><a href="file.CHANGELOG.html" title="CHANGELOG">CHANGELOG</a></a></li>
53
+
54
+
55
+ </ul>
56
+ </div>
57
+ </body>
58
+ </html>
data/doc/frames.html ADDED
@@ -0,0 +1,28 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
3
+
4
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
+ <head>
6
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
7
+ <title>Documentation by YARD 0.8.6.1</title>
8
+ </head>
9
+ <script type="text/javascript" charset="utf-8">
10
+ window.onload = function() {
11
+ var match = window.location.hash.match(/^#!(.+)/);
12
+ var name = 'index.html';
13
+ if (match) {
14
+ name = unescape(match[1]);
15
+ }
16
+ document.writeln('<frameset cols="20%,*">' +
17
+ '<frame name="list" src="class_list.html" />' +
18
+ '<frame name="main" src="' + name + '" />' +
19
+ '</frameset>');
20
+ }
21
+ </script>
22
+ <noscript>
23
+ <frameset cols="20%,*">
24
+ <frame name="list" src="class_list.html" />
25
+ <frame name="main" src="index.html" />
26
+ </frameset>
27
+ </noscript>
28
+ </html>