mucgly 0.0.2 → 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/CHANGELOG.rdoc +8 -0
- data/LICENSE +1 -1
- data/README.rdoc +160 -130
- data/bin/mucgly +4 -217
- data/doc/Mucgly.html +24 -82
- data/doc/_index.html +5 -153
- data/doc/class_list.html +7 -2
- data/doc/css/style.css +2 -1
- data/doc/file.CHANGELOG.html +16 -8
- data/doc/file.README.html +210 -187
- data/doc/file_list.html +6 -1
- data/doc/frames.html +5 -7
- data/doc/index.html +210 -187
- data/doc/js/app.js +7 -2
- data/doc/js/full_list.js +9 -6
- data/doc/method_list.html +7 -686
- data/doc/top-level-namespace.html +5 -5
- data/ext/mucgly/extconf.rb +11 -0
- data/ext/mucgly/mucgly.c +2095 -0
- data/lib/version.rb +6 -0
- data/test/golden/test_basic.txt +18 -0
- data/test/golden/test_specials_cli.txt +11 -0
- data/test/golden/test_specials_cmd.txt +36 -0
- data/test/result/test_basic.txt +18 -0
- data/test/result/test_specials_cli.txt +11 -0
- data/test/result/test_specials_cmd.txt +36 -0
- data/test/result/test_specials_cmd2.txt +1 -0
- data/test/test_basic.rx.txt +10 -6
- data/test/test_mucgly.rb +4 -6
- data/test/test_specials_cli.rx.txt +4 -4
- data/test/test_specials_cmd.rx.txt +5 -5
- metadata +45 -63
- data/Rakefile +0 -29
- data/doc/EasyFile/InOut.html +0 -2097
- data/doc/EasyFile/Read.html +0 -1334
- data/doc/EasyFile/ReadStack.html +0 -461
- data/doc/EasyFile/Stacked.html +0 -411
- data/doc/EasyFile/String.html +0 -570
- data/doc/EasyFile/Write.html +0 -1084
- data/doc/EasyFile/WriteStack.html +0 -305
- data/doc/EasyFile.html +0 -155
- data/doc/Mucgly/Env.html +0 -1675
- data/doc/Mucgly/MucglyFile/ParseState.html +0 -1662
- data/doc/Mucgly/MucglyFile/Token.html +0 -529
- data/doc/Mucgly/MucglyFile.html +0 -545
- data/doc/Mucgly/Separators.html +0 -521
- data/lib/easyfile.rb +0 -720
- data/lib/mucgly.rb +0 -627
- data/test/test_multi.rx.txt +0 -4
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: d438186a60f6f48bf2b68fd7090f7cc3e375cca3
|
4
|
+
data.tar.gz: 69d49907c80a1faee873a275f228090f48d930e0
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 04b142e789d684fc49819c5289070fcd324cebb199c6a732301279b3b40938356902152d4d2dad2ad171becb8b290305ac0bb70c2fe51ed616141bf125bbcea7
|
7
|
+
data.tar.gz: 96a4e3c1271542ccd0e4174ef450f1e0344ac39121c66ca5784ba65bfbe116e5fa9b73f2037f1874a10ebedb3715b79e95356146f942530671b5a2f4e6a7f204
|
data/CHANGELOG.rdoc
CHANGED
@@ -1,5 +1,13 @@
|
|
1
1
|
= Version history
|
2
2
|
|
3
|
+
[0.1.0] C-based implementation.
|
4
|
+
100 times faster than older versions.
|
5
|
+
Multiple command line interface and internal cmd changes.
|
6
|
+
Not fully backwards compatible with older versions.
|
7
|
+
|
8
|
+
[0.0.3] Usage typo fix (hookend).
|
9
|
+
Added version method.
|
10
|
+
|
3
11
|
[0.0.2] Dependency to Como for Gem.
|
4
12
|
|
5
13
|
[0.0.1] Initial version.
|
data/LICENSE
CHANGED
data/README.rdoc
CHANGED
@@ -2,67 +2,80 @@
|
|
2
2
|
|
3
3
|
== Introduction
|
4
4
|
|
5
|
-
Mucgly is a macro expander for inline macros that exist in the middle
|
6
|
-
body text. The macros are mostly regular Ruby code,
|
7
|
-
commands
|
5
|
+
Mucgly is a macro expander for inline macros that exist in the middle
|
6
|
+
of body text. The macros are expected to be mostly regular Ruby code,
|
7
|
+
but a few special commands are also available.
|
8
8
|
|
9
9
|
A very simple example:
|
10
|
-
Adding 1 + 3 results:
|
10
|
+
Adding 1 + 3 results to: -<.1+3>-
|
11
11
|
|
12
12
|
After macro expansion the results is:
|
13
|
-
Adding 1 + 3 results: 4
|
13
|
+
Adding 1 + 3 results to: 4
|
14
14
|
|
15
15
|
By default macro starts with "-<" and ends with ">-". These limiters
|
16
|
-
are called hooks, hookbeg and hookend respectively. The code between
|
17
|
-
hooks is regular Ruby code. The
|
18
|
-
|
16
|
+
are called hooks, hookbeg and hookend, respectively. The code between
|
17
|
+
hooks is mostly regular Ruby code. The first character is special
|
18
|
+
syntax and the rest is pure Ruby code. The special character (command)
|
19
|
+
"." is used to print the Ruby code evaluation value to current output
|
20
|
+
file (stream).
|
19
21
|
|
20
|
-
|
21
|
-
|
22
|
-
|
22
|
+
Sample session to execute the example above:
|
23
|
+
shell> mucgly
|
24
|
+
Adding 1 + 3 results to: -<.1+3>-
|
25
|
+
Adding 1 + 3 results to: 4
|
26
|
+
<Ctrl-D>
|
27
|
+
shell>
|
28
|
+
|
29
|
+
|
30
|
+
Ruby code is always executed in the Ruby interpreters "<main>" scope.
|
23
31
|
|
24
32
|
Previous example with multiple macros:
|
25
33
|
-<@a = 1>--<@b = 3>-\
|
26
|
-
Adding 1 + 3 results: -<write
|
34
|
+
Adding 1 + 3 results to: -<Mucgly.write(@a+@b)>-
|
27
35
|
|
28
|
-
Result is exactly the same as in the previous execution
|
29
|
-
|
30
|
-
|
36
|
+
Result is exactly the same as in the previous execution, but the Ruby
|
37
|
+
code is distributed into multiple segments. The first macro "-<@a =
|
38
|
+
1>-" produces no output, it just sets the variable "@a" to "1". Second
|
39
|
+
macro is similar. The default "escape" character (hookesc) is
|
31
40
|
"\\". When placed before newline character, it "eats" the newline and
|
32
41
|
nothing is output. Thus the first line outputs nothing.
|
33
42
|
|
34
|
-
The second line refers to settings from previous
|
35
|
-
variables has to be used to
|
36
|
-
to
|
43
|
+
The macro on the second line refers to settings from previous
|
44
|
+
macros. Instance variables has to be used to share data between macro
|
45
|
+
calls (due to "<main>" evaluation). Local variables are not persistent
|
46
|
+
enough. Mucgly module method, "Mucgly.write", is used to write out the
|
47
|
+
calculation result. Mucgly module is defined within Mucgly utility.
|
37
48
|
|
38
49
|
|
39
50
|
== Features
|
40
51
|
|
41
52
|
* User settable hooks to define macro boundaries. Can be set from
|
42
|
-
command line, configuration files, or from macro file.
|
53
|
+
command line, configuration files, or from macro input file.
|
43
54
|
|
44
55
|
* Multiple sources for configuration: default config, environment
|
45
56
|
variable, command line.
|
46
57
|
|
47
|
-
*
|
48
|
-
|
49
|
-
* Convention based output file naming.
|
58
|
+
* Multipass support.
|
50
59
|
|
51
60
|
* Multiple convenience functions for macros to use.
|
52
61
|
|
53
|
-
* Macro file introspection: line number, file name
|
62
|
+
* Macro file introspection: line number, file name.
|
54
63
|
|
55
|
-
* Output stream de-muxing.
|
64
|
+
* Output stream redirection (de-muxing).
|
56
65
|
|
57
66
|
* Many special commands: include, source, etc...
|
58
67
|
|
68
|
+
* Fast C-language based macro file processing.
|
69
|
+
|
59
70
|
|
60
71
|
|
61
72
|
== Applications
|
62
73
|
|
63
74
|
* Replacement for M4 macro processor.
|
64
75
|
|
65
|
-
*
|
76
|
+
* Ruby pre-processor.
|
77
|
+
|
78
|
+
* General purpose code generation.
|
66
79
|
|
67
80
|
* Document formatting.
|
68
81
|
|
@@ -75,169 +88,178 @@ to instance evaluation).
|
|
75
88
|
=== Hooks
|
76
89
|
|
77
90
|
Hooks start and end the macro definition. By default hookbeg is "-<"
|
78
|
-
and hookend is ">-". These values are not easily conflicting with
|
79
|
-
macro file body text.
|
91
|
+
and hookend is ">-". These values are not easily conflicting with
|
92
|
+
typical macro file body text.
|
80
93
|
|
81
|
-
If literal hook string is required
|
82
|
-
place before the hook. For example "
|
83
|
-
the output.
|
94
|
+
If literal hook string is required in the output, the hookesc sequence
|
95
|
+
should be place before the hook. For example "\\-<" will produce
|
96
|
+
literal "-<" to the output. "\\" is the default hookesc value.
|
84
97
|
|
85
98
|
User can set the hooks to whatever string value desired. The hooks can
|
86
99
|
also have the same value. However nested macros are not possible
|
87
|
-
then. Hooks can also be the same as the escape
|
100
|
+
then. Hooks can also be the same as the escape sequence, but this
|
88
101
|
makes usage somewhat complicated.
|
89
102
|
|
90
103
|
=== Escape
|
91
104
|
|
92
|
-
Default escape
|
93
|
-
cancel space (" ") output, and cancel newline ("\\n") output.
|
105
|
+
Default hookesc (escape sequence) is "\\". It can be used to escape
|
106
|
+
hooks, cancel space (" ") output, and cancel newline ("\\n") output.
|
94
107
|
|
95
|
-
User can set the escape
|
96
|
-
character value is accepted.
|
108
|
+
User can set the escape sequence to any character(s).
|
97
109
|
|
98
|
-
===
|
110
|
+
=== Single char hooks and escape
|
99
111
|
|
100
|
-
If
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
character is used to save a macro to the later pass.
|
112
|
+
If all hooks are single character (including hookesc) and have the
|
113
|
+
same value, there are some additional rules that are used to identify
|
114
|
+
macro boundaries and escapes. Let's assume that the selected hook char
|
115
|
+
is "|" (vertical bar).
|
105
116
|
|
106
|
-
|
107
|
-
|
108
|
-
|
117
|
+
Escape is detected if "| ", "|\\n", or "||" is seen in the input, when
|
118
|
+
outside macro. Escape is detected within macro if "||" is seen in input.
|
119
|
+
|
120
|
+
Hookbeg is detected at "|" if outside macro. Hookend is detected at
|
121
|
+
"|" if inside macro. Thus if literal "|" is needed inside macro, then
|
122
|
+
"||" must be used. Also expressing multilevel macros (macro in macro)
|
123
|
+
is not possible, since hookbeg is never detected within macro. The
|
124
|
+
default hook values can be used for nested macros (if desired).
|
109
125
|
|
110
|
-
Example, with functions (insert_toc, header...) defined elsewhere:
|
111
|
-
-<#insert_toc>-
|
112
|
-
-<header(1, "My header 1")>-
|
113
|
-
Paragraph1
|
114
|
-
-<header(2, "My header 1.1")>-
|
115
|
-
Paragraph2
|
116
|
-
-<header(1, "My header 2")>-
|
117
|
-
Paragraph3
|
118
126
|
|
119
127
|
|
120
128
|
== Special commands
|
121
129
|
|
122
130
|
In addition to regular Ruby code the macros are allowed to include so
|
123
131
|
called Special Commands. These commands start with the ":" characters
|
124
|
-
|
132
|
+
or with ".".
|
125
133
|
|
126
|
-
|
127
|
-
|
128
|
-
|
134
|
+
|
135
|
+
=== Named commands
|
136
|
+
|
137
|
+
Example for named command:
|
129
138
|
...
|
139
|
+
-<:hook [ ]>-\
|
140
|
+
...
|
141
|
+
|
142
|
+
Would change the hookbeg and hookend to "[" and "]" respectively. Note
|
143
|
+
that hooks are changed only for the current input file. If for example
|
144
|
+
an included input file changes hooks, the includer file still uses the
|
145
|
+
original hooks.
|
130
146
|
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
macro. Note that a command without an argument has to end with space
|
136
|
-
as well.
|
147
|
+
One special command is allowed per macro and it can't be mixed normal
|
148
|
+
Ruby code. Command name is separated by ":" in the beginning and by
|
149
|
+
space (" ") in the end. The rest of the macro is taken as argument to
|
150
|
+
the command.
|
137
151
|
|
138
152
|
List of ":" style special commands:
|
139
153
|
|
140
154
|
[include] Include reverts the input stream to the file given in the
|
141
|
-
argument. Command can be used to multiplex
|
142
|
-
into one
|
143
|
-
|
144
|
-
[output] Select a new output file. Use with "close" command, when the
|
145
|
-
new output file is ready.
|
155
|
+
argument. Command can be used for example to multiplex
|
156
|
+
multiple files into one (example: "-<:include input.txt>-"
|
157
|
+
).
|
146
158
|
|
147
159
|
[comment] Comment is used to add comments into the macro file. No
|
148
160
|
output is produced from comment macros.
|
149
161
|
|
150
162
|
[source] Source reads a plain Ruby file into the Execution Environment.
|
151
163
|
|
152
|
-
[hook] Sets both hookbeg and hookend to values separated by
|
153
|
-
|
154
|
-
macro.
|
164
|
+
[hook] Sets both hookbeg and hookend to values separated by
|
165
|
+
space. Without space hookbeg and hookend are set to same value.
|
155
166
|
|
156
167
|
[hookbeg] Sets hookbeg.
|
157
168
|
|
158
169
|
[hookend] Sets hookend.
|
159
170
|
|
160
|
-
[
|
171
|
+
[hookesc] Sets escape sequence.
|
172
|
+
|
173
|
+
[hookall] Sets hookbeg, hookend, and hookesc to same value.
|
161
174
|
|
162
|
-
[exit] Aborts the macro file.
|
175
|
+
[exit] Aborts the macro processing (file).
|
163
176
|
|
164
|
-
|
165
|
-
|
177
|
+
|
178
|
+
=== Quick commands
|
179
|
+
|
180
|
+
Special write command starts with "." and is followed by the Ruby
|
181
|
+
value.
|
166
182
|
|
167
183
|
For example:
|
168
|
-
...
|
184
|
+
... -<.@my_name>- ...
|
169
185
|
|
170
186
|
Would write out the value of the "@my_name" variable, thus it is equal
|
171
187
|
to writing:
|
172
|
-
... -<write @my_name>- ...
|
188
|
+
... -<Mucgly.write @my_name>- ...
|
173
189
|
|
190
|
+
The special character "/" can also be used for comment macro, i.e. "/"
|
191
|
+
is same as ":comment ".
|
174
192
|
|
175
193
|
|
176
|
-
|
194
|
+
=== Multipass
|
177
195
|
|
178
|
-
|
179
|
-
|
180
|
-
|
196
|
+
If the macro starts with "#" character, the macro is not excuted. The
|
197
|
+
macro content is output with "#" removed from the output, including
|
198
|
+
the current macro hooks. If 3 passes are needed, then "##" can be
|
199
|
+
placed to the initial macro file. Multipass macro files are processes
|
200
|
+
by (shell) piping the output of Mucgly to another Mucgly process.
|
181
201
|
|
182
|
-
|
202
|
+
Multipass can be used for example to create a Table Of Contents. First
|
203
|
+
pass collects information about document content and second pass will
|
204
|
+
insert the Table Of Contents for a document.
|
183
205
|
|
184
|
-
|
206
|
+
Example, with functions (insert_toc, header...) defined elsewhere:
|
207
|
+
-<#insert_toc>-
|
208
|
+
-<header(1, "My header 1")>-
|
209
|
+
Paragraph1
|
210
|
+
-<header(2, "My header 1.1")>-
|
211
|
+
Paragraph2
|
212
|
+
-<header(1, "My header 2")>-
|
213
|
+
Paragraph3
|
214
|
+
|
215
|
+
|
216
|
+
== Mucgly module methods
|
185
217
|
|
186
|
-
|
187
|
-
|
188
|
-
[source] Sources a plain Ruby file.
|
218
|
+
Ruby Mucgly module includes methods that are used to interact with
|
219
|
+
Mucgly program internals.
|
189
220
|
|
221
|
+
Methods "write", "puts" produce output to current output file
|
222
|
+
stream. Hook-commands change the current hook values.
|
190
223
|
|
191
|
-
=== Hidden methods
|
192
224
|
|
193
|
-
|
194
|
-
prevent poluting the Execution Environment's namespace.
|
225
|
+
Complete list of Mucgly module methods:
|
195
226
|
|
196
|
-
[
|
197
|
-
and second is output file. File pair argument is an
|
198
|
-
Array of two ([<fileI>, <fileO>]).
|
227
|
+
[write] Write string to current output file without newline.
|
199
228
|
|
200
|
-
[
|
229
|
+
[puts] Write string to current output file with newline.
|
201
230
|
|
202
|
-
[
|
203
|
-
closed, the input stream is reverted to the original
|
204
|
-
file.
|
231
|
+
[hookbeg] Get hookbeg value.
|
205
232
|
|
206
|
-
[
|
207
|
-
closed, the input stream is reverted to the original
|
208
|
-
file.
|
233
|
+
[hookend] Get hookend value.
|
209
234
|
|
210
|
-
[
|
235
|
+
[hookesc] Get hookesc value.
|
211
236
|
|
212
|
-
[
|
213
|
-
closed, the input stream is reverted to the original
|
214
|
-
file.
|
237
|
+
[sethookbeg] Set hookbeg value.
|
215
238
|
|
216
|
-
[
|
217
|
-
is closed, the output stream is reverted to the original
|
218
|
-
file.
|
239
|
+
[sethookend] Set hookend value.
|
219
240
|
|
220
|
-
[
|
241
|
+
[sethookesc] Set hookesc value.
|
221
242
|
|
222
|
-
[
|
243
|
+
[ifilename] Input file name as String.
|
223
244
|
|
224
|
-
[
|
245
|
+
[ilinenumber] Input file line number.
|
225
246
|
|
226
|
-
[
|
247
|
+
[ofilename] Output file name as String.
|
227
248
|
|
228
|
-
[
|
249
|
+
[olinenumber] Output file line number.
|
229
250
|
|
230
|
-
[
|
251
|
+
[pushinput] Makes given file as current input stream. When this stream
|
252
|
+
is runs out (EOF) or is closed (with closeinput), the
|
253
|
+
input stream is reverted to previous input file.
|
231
254
|
|
232
|
-
[
|
255
|
+
[closeinput] Close output stream (before EOF is encountered).
|
233
256
|
|
234
|
-
[
|
257
|
+
[pushoutput] Makes given file as top output stream. When this stream
|
258
|
+
is closed (with closeoutput), the output stream is
|
259
|
+
reverted to previous output file.
|
235
260
|
|
236
|
-
[
|
261
|
+
[closeoutput] Close output stream.
|
237
262
|
|
238
|
-
[_separators] Handle to Separators object. Separotors object includes
|
239
|
-
the "escapeChar", "hookBegChars", and "hookEndChars"
|
240
|
-
setter and getter methods.
|
241
263
|
|
242
264
|
|
243
265
|
== Command line interface
|
@@ -250,24 +272,20 @@ for an overview of the command line options.
|
|
250
272
|
|
251
273
|
=== Input and Output files
|
252
274
|
|
253
|
-
Input files can be listed to "-
|
275
|
+
Input files can be listed to "-f" option. The default input stream for
|
254
276
|
Mucgly is STDIN.
|
255
277
|
|
256
|
-
Output
|
278
|
+
Output file can be defined with "-o" option. The default output stream
|
257
279
|
for Mucgly is STDOUT.
|
258
280
|
|
259
|
-
If "-
|
260
|
-
includes ".rx" in each name, the output file list is created by
|
261
|
-
extracting ".rx" from each input file name.
|
281
|
+
If "-g" option is given, the output file list is created by extracting "-g" option argument value from each input file name.
|
262
282
|
|
263
283
|
For example with:
|
264
|
-
mucgly -
|
284
|
+
mucgly -f foo.rx.txt -f bar.rx.txt -g .rx
|
265
285
|
|
266
286
|
Two files, foo.txt and bar.txt, would be created. This holds true
|
267
287
|
unless the output streams are manipulated with macro commands.
|
268
288
|
|
269
|
-
If the number of input and output files match, then they are used in pairs.
|
270
|
-
|
271
289
|
|
272
290
|
== Configuration
|
273
291
|
|
@@ -275,10 +293,6 @@ Mucgly checks for the existance of the "MUCGLY" environment
|
|
275
293
|
variable. If the variable exists, the file in variable value is read
|
276
294
|
in as plain Ruby.
|
277
295
|
|
278
|
-
User configuration is searched from the users home directory:
|
279
|
-
$HOME/.mucgly
|
280
|
-
It is read as plain Ruby file if it exists.
|
281
|
-
|
282
296
|
Configuration files can also be given on command line using the "-c"
|
283
297
|
option. These settings can be used to override the settings above.
|
284
298
|
|
@@ -289,4 +303,20 @@ with "-l" option.
|
|
289
303
|
== More information
|
290
304
|
|
291
305
|
Check out the "test" directory within installation for detailed
|
292
|
-
examples about usage.
|
306
|
+
examples about macro usage.
|
307
|
+
|
308
|
+
|
309
|
+
== Non-GEM installation
|
310
|
+
|
311
|
+
By default Mucgly is distributed as GEM. However Mucgly is by nature a
|
312
|
+
C-program. It can be compliled as "normal" C-program that just uses
|
313
|
+
Ruby Interpreter for evaluating Ruby macro content.
|
314
|
+
|
315
|
+
If Mucgly is used in C-main mode, it runs slightly faster, and with
|
316
|
+
smaller memory footprint.
|
317
|
+
|
318
|
+
Example compilation command (use in Mucgly GEM directory root):
|
319
|
+
gcc `pkg-config --cflags --libs glib-2.0` `pkg-config --cflags --libs ruby-2.1` -O2 -std=c11 -o mucgly ext/mucgly/mucgly.c
|
320
|
+
|
321
|
+
Executable file "mucgly" is created, which can be used the same way as
|
322
|
+
the GEM executable (i.e. same command line options).
|