mucgly 0.0.2 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d438186a60f6f48bf2b68fd7090f7cc3e375cca3
+  data.tar.gz: 69d49907c80a1faee873a275f228090f48d930e0
+SHA512:
+  metadata.gz: 04b142e789d684fc49819c5289070fcd324cebb199c6a732301279b3b40938356902152d4d2dad2ad171becb8b290305ac0bb70c2fe51ed616141bf125bbcea7
+  data.tar.gz: 96a4e3c1271542ccd0e4174ef450f1e0344ac39121c66ca5784ba65bfbe116e5fa9b73f2037f1874a10ebedb3715b79e95356146f942530671b5a2f4e6a7f204

data/CHANGELOG.rdoc

@@ -1,5 +1,13 @@
 = Version history
 
+[0.1.0] C-based implementation.
+        100 times faster than older versions.
+        Multiple command line interface and internal cmd changes.
+        Not fully backwards compatible with older versions.
+
+[0.0.3] Usage typo fix (hookend).
+        Added version method.
+
 [0.0.2] Dependency to Como for Gem.
 
 [0.0.1] Initial version.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014 tero.isannainen@gmail.com
+Copyright (c) 2014, 2015 tero.isannainen@gmail.com
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -2,67 +2,80 @@
 
 == Introduction
 
-Mucgly is a macro expander for inline macros that exist in the middle of
-body text. The macros are mostly regular Ruby code, but a few special
-commands is also provided.
+Mucgly is a macro expander for inline macros that exist in the middle
+of body text. The macros are expected to be mostly regular Ruby code,
+but a few special commands are also available.
 
 A very simple example:
-  Adding 1 + 3 results: -<write (1+3).to_s>-
+  Adding 1 + 3 results to: -<.1+3>-
 
 After macro expansion the results is:
-  Adding 1 + 3 results: 4
+  Adding 1 + 3 results to: 4
 
 By default macro starts with "-<" and ends with ">-". These limiters
-are called hooks, hookbeg and hookend respectively. The code between
-hooks is regular Ruby code. The "write" call writes to selected IO
-stream.
+are called hooks, hookbeg and hookend, respectively. The code between
+hooks is mostly regular Ruby code. The first character is special
+syntax and the rest is pure Ruby code. The special character (command)
+"." is used to print the Ruby code evaluation value to current output
+file (stream).
 
-Ruby code is executed within a class instance reserved for this
-purpose. The instance is called the Execution Environment. It enables
-values from one macro to be visible in others.
+Sample session to execute the example above:
+  shell> mucgly
+  Adding 1 + 3 results to: -<.1+3>-
+  Adding 1 + 3 results to: 4
+  <Ctrl-D>
+  shell>
+
+
+Ruby code is always executed in the Ruby interpreters "<main>" scope.
 
 Previous example with multiple macros:
   -<@a = 1>--<@b = 3>-\
-  Adding 1 + 3 results: -<write (@a+@b).to_s>-
+  Adding 1 + 3 results to: -<Mucgly.write(@a+@b)>-
 
-Result is exactly the same as in the previous execution. The first
-macro "-<@a = 1>-" produces no output, it just sets the variable "@a"
-to "1". Second macro is similar. The default "escape" character is
+Result is exactly the same as in the previous execution, but the Ruby
+code is distributed into multiple segments. The first macro "-<@a =
+1>-" produces no output, it just sets the variable "@a" to "1". Second
+macro is similar. The default "escape" character (hookesc) is
 "\\". When placed before newline character, it "eats" the newline and
 nothing is output. Thus the first line outputs nothing.
 
-The second line refers to settings from previous macros. Instance
-variables has to be used to maintain the data between macro calls (due
-to instance evaluation).
+The macro on the second line refers to settings from previous
+macros. Instance variables has to be used to share data between macro
+calls (due to "<main>" evaluation). Local variables are not persistent
+enough. Mucgly module method, "Mucgly.write", is used to write out the
+calculation result. Mucgly module is defined within Mucgly utility.
 
 
 == Features
 
 * User settable hooks to define macro boundaries. Can be set from
-  command line, configuration files, or from macro file.
+  command line, configuration files, or from macro input file.
 
 * Multiple sources for configuration: default config, environment
   variable, command line.
 
-* Multiple passes for macro file.
-
-* Convention based output file naming.
+* Multipass support.
 
 * Multiple convenience functions for macros to use.
 
-* Macro file introspection: line number, file name
+* Macro file introspection: line number, file name.
 
-* Output stream de-muxing.
+* Output stream redirection (de-muxing).
 
 * Many special commands: include, source, etc...
 
+* Fast C-language based macro file processing.
+
 
 
 == Applications
 
 * Replacement for M4 macro processor.
 
-* Code generation.
+* Ruby pre-processor.
+
+* General purpose code generation.
 
 * Document formatting.
 
@@ -75,169 +88,178 @@ to instance evaluation).
 === Hooks
 
 Hooks start and end the macro definition. By default hookbeg is "-<"
-and hookend is ">-". These values are not easily conflicting with the
-macro file body text.
+and hookend is ">-". These values are not easily conflicting with
+typical macro file body text.
 
-If literal hook string is required, the escape character should be
-place before the hook. For example "\-<" will produce literal "-<" to
-the output.
+If literal hook string is required in the output, the hookesc sequence
+should be place before the hook. For example "\\-<" will produce
+literal "-<" to the output. "\\" is the default hookesc value.
 
 User can set the hooks to whatever string value desired. The hooks can
 also have the same value. However nested macros are not possible
-then. Hooks can also be the same as the escape character, but this
+then. Hooks can also be the same as the escape sequence, but this
 makes usage somewhat complicated.
 
 === Escape
 
-Default escape character is "\\". It can be used to escape hooks,
-cancel space (" ") output, and cancel newline ("\\n") output.
+Default hookesc (escape sequence) is "\\". It can be used to escape
+hooks, cancel space (" ") output, and cancel newline ("\\n") output.
 
-User can set the escape character to any character. Only single
-character value is accepted.
+User can set the escape sequence to any character(s).
 
-=== Multipass
+=== Single char hooks and escape
 
-If the macro starts with "#" character, the macro is not expanded. One
-"#" character is removed and the rest of the macro is output as it
-is. Each pass will remove one "#" character and when all are removed,
-the macro is evaluated. Usually two passes are enough and one "#"
-character is used to save a macro to the later pass.
+If all hooks are single character (including hookesc) and have the
+same value, there are some additional rules that are used to identify
+macro boundaries and escapes. Let's assume that the selected hook char
+is "|" (vertical bar).
 
-Multipass can be used for example to create a Table Of Contents. First
-pass collects information about document content and second pass will
-insert the Table Of Contents.
+Escape is detected if "| ", "|\\n", or "||" is seen in the input, when
+outside macro. Escape is detected within macro if "||" is seen in input.
+
+Hookbeg is detected at "|" if outside macro. Hookend is detected at
+"|" if inside macro. Thus if literal "|" is needed inside macro, then
+"||" must be used. Also expressing multilevel macros (macro in macro)
+is not possible, since hookbeg is never detected within macro. The
+default hook values can be used for nested macros (if desired).
 
-Example, with functions (insert_toc, header...) defined elsewhere:
-  -<#insert_toc>-
-  -<header(1, "My header 1")>-
-  Paragraph1
-  -<header(2, "My header 1.1")>-
-  Paragraph2
-  -<header(1, "My header 2")>-
-  Paragraph3
 
 
 == Special commands
 
 In addition to regular Ruby code the macros are allowed to include so
 called Special Commands. These commands start with the ":" characters
-and with ".".
+or with ".".
 
-Example:
-  ...
-  -<:hook [ ]->\
+
+=== Named commands
+
+Example for named command:
   ...
+  -<:hook [ ]>-\
+ ...
+
+Would change the hookbeg and hookend to "[" and "]" respectively. Note
+that hooks are changed only for the current input file. If for example
+an included input file changes hooks, the includer file still uses the
+original hooks.
 
-Would change the hookbeg and hookend to "[" and "]" respectively. One
-special command is allowed per macro and it can't be mixed normal Ruby
-code. Command name is separated by ":" in the beginning and by space
-(" ") in the end. The rest of the macro is taken as argument to the
-macro. Note that a command without an argument has to end with space
-as well.
+One special command is allowed per macro and it can't be mixed normal
+Ruby code. Command name is separated by ":" in the beginning and by
+space (" ") in the end. The rest of the macro is taken as argument to
+the command.
 
 List of ":" style special commands:
 
 [include] Include reverts the input stream to the file given in the
-          argument. Command can be used to multiplex multiple files
-          into one, for example.
-
-[output] Select a new output file. Use with "close" command, when the
-         new output file is ready.
+          argument. Command can be used for example to multiplex
+          multiple files into one (example: "-<:include input.txt>-"
+          ).
 
 [comment] Comment is used to add comments into the macro file. No
           output is produced from comment macros.
 
 [source] Source reads a plain Ruby file into the Execution Environment.
 
-[hook] Sets both hookbeg and hookend to values separated by space. The
-       new hook values are valid immediately after the enclosing
-       macro.
+[hook] Sets both hookbeg and hookend to values separated by
+       space. Without space hookbeg and hookend are set to same value.
 
 [hookbeg] Sets hookbeg.
 
 [hookend] Sets hookend.
 
-[escape] Sets escape character.
+[hookesc] Sets escape sequence.
+
+[hookall] Sets hookbeg, hookend, and hookesc to same value.
 
-[exit] Aborts the macro file.
+[exit] Aborts the macro processing (file).
 
-Variable value reference command starts with "." and is followed by
-the (instance) variable name.
+
+=== Quick commands
+
+Special write command starts with "." and is followed by the Ruby
+value.
 
 For example:
-  ... -<.my_name>- ...
+  ... -<.@my_name>- ...
 
 Would write out the value of the "@my_name" variable, thus it is equal
 to writing:
-  ... -<write @my_name>- ...
+  ... -<Mucgly.write @my_name>- ...
 
+The special character "/" can also be used for comment macro, i.e. "/"
+is same as ":comment ".
 
 
-== API methods
+=== Multipass
 
-API methods are instance methods of the Execution Environment,
-i.e. they are predefined and visible for the macro code. These methods
-are organized into two categories: Published and Hidden.
+If the macro starts with "#" character, the macro is not excuted. The
+macro content is output with "#" removed from the output, including
+the current macro hooks. If 3 passes are needed, then "##" can be
+placed to the initial macro file. Multipass macro files are processes
+by (shell) piping the output of Mucgly to another Mucgly process.
 
-=== Published methods
+Multipass can be used for example to create a Table Of Contents. First
+pass collects information about document content and second pass will
+insert the Table Of Contents for a document.
 
-Published methods are the most commonly used methods in macros. These are:
+Example, with functions (insert_toc, header...) defined elsewhere:
+  -<#insert_toc>-
+  -<header(1, "My header 1")>-
+  Paragraph1
+  -<header(2, "My header 1.1")>-
+  Paragraph2
+  -<header(1, "My header 2")>-
+  Paragraph3
+
+
+== Mucgly module methods
 
-[write] Writes string into selected output IO.
-[puts] Writes string (+newline) into selected output IO.
-[source] Sources a plain Ruby file.
+Ruby Mucgly module includes methods that are used to interact with
+Mucgly program internals.
 
+Methods "write", "puts" produce output to current output file
+stream. Hook-commands change the current hook values.
 
-=== Hidden methods
 
-Hidded methods start with underscore ("_"). The naming is used to
-prevent poluting the Execution Environment's namespace.
+Complete list of Mucgly module methods:
 
-[_processFilePair] Process a pair of files. First half is input file
-                   and second is output file. File pair argument is an
-                   Array of two ([<fileI>, <fileO>]).
+[write] Write string to current output file without newline.
 
-[_processFilePairs] Uses "_processFilePair" to process a list of file pairs.
+[puts] Write string to current output file with newline.
 
-[_openInput] Sets input stream to given file. When this file is
-             closed, the input stream is reverted to the original
-             file.
+[hookbeg] Get hookbeg value.
 
-[_openOutput] Sets output stream to given file. When this file is
-              closed, the input stream is reverted to the original
-              file.
+[hookend] Get hookend value.
 
-[_openString] Open a StringIO file for output.
+[hookesc] Get hookesc value.
 
-[_pushInput] Makes given file as top input stream. When this stream is
-             closed, the input stream is reverted to the original
-             file.
+[sethookbeg] Set hookbeg value.
 
-[_pushOutput] Makes given file as top output stream. When this stream
-              is closed, the output stream is reverted to the original
-              file.
+[sethookend] Set hookend value.
 
-[_closeInput] Close input stream.
+[sethookesc] Set hookesc value.
 
-[_closeOutput] Close output stream.
+[ifilename] Input file name as String.
 
-[_ofilename] Output file name as String.
+[ilinenumber] Input file line number.
 
-[_olinenumber] Output file line number.
+[ofilename] Output file name as String.
 
-[_ifilename] Input file name as String.
+[olinenumber] Output file line number.
 
-[_ilinenumber] Input file line number.
+[pushinput] Makes given file as current input stream. When this stream
+            is runs out (EOF) or is closed (with closeinput), the
+            input stream is reverted to previous input file.
 
-[_eval] Perform instance_eval on the given argument.
+[closeinput] Close output stream (before EOF is encountered).
 
-[_inIO] Handle to input stream (get/set).
+[pushoutput] Makes given file as top output stream. When this stream
+             is closed (with closeoutput), the output stream is
+             reverted to previous output file.
 
-[_outIO] Handle to output stream (get/set).
+[closeoutput] Close output stream.
 
-[_separators] Handle to Separators object. Separotors object includes
-              the "escapeChar", "hookBegChars", and "hookEndChars"
-              setter and getter methods.
 
 
 == Command line interface
@@ -250,24 +272,20 @@ for an overview of the command line options.
 
 === Input and Output files
 
-Input files can be listed to "-i" option. The default input stream for
+Input files can be listed to "-f" option. The default input stream for
 Mucgly is STDIN.
 
-Output files can be listed to "-o" option. The default output stream
+Output file can be defined with "-o" option. The default output stream
 for Mucgly is STDOUT.
 
-If "-o" option is given without arguments and the input file list
-includes ".rx" in each name, the output file list is created by
-extracting ".rx" from each input file name.
+If "-g" option is given, the output file list is created by extracting "-g" option argument value from each input file name.
 
 For example with:
-   mucgly -i foo.rx.txt bar.rx.txt -o
+   mucgly -f foo.rx.txt -f bar.rx.txt -g .rx
 
 Two files, foo.txt and bar.txt, would be created. This holds true
 unless the output streams are manipulated with macro commands.
 
-If the number of input and output files match, then they are used in pairs.
-
 
 == Configuration
 
@@ -275,10 +293,6 @@ Mucgly checks for the existance of the "MUCGLY" environment
 variable. If the variable exists, the file in variable value is read
 in as plain Ruby.
 
-User configuration is searched from the users home directory:
-  $HOME/.mucgly
-It is read as plain Ruby file if it exists.
-
 Configuration files can also be given on command line using the "-c"
 option. These settings can be used to override the settings above.
 
@@ -289,4 +303,20 @@ with "-l" option.
 == More information
 
 Check out the "test" directory within installation for detailed
-examples about usage.
+examples about macro usage.
+
+
+== Non-GEM installation
+
+By default Mucgly is distributed as GEM. However Mucgly is by nature a
+C-program. It can be compliled as "normal" C-program that just uses
+Ruby Interpreter for evaluating Ruby macro content.
+
+If Mucgly is used in C-main mode, it runs slightly faster, and with
+smaller memory footprint.
+
+Example compilation command (use in Mucgly GEM directory root):
+  gcc `pkg-config --cflags --libs glib-2.0` `pkg-config --cflags --libs ruby-2.1` -O2 -std=c11 -o mucgly ext/mucgly/mucgly.c
+
+Executable file "mucgly" is created, which can be used the same way as
+the GEM executable (i.e. same command line options).