mucgly 0.0.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -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>