gen-text 0.0.6 → 0.0.7

data/README.md

@@ -9,6 +9,23 @@ Install
 - Install [Ruby](http://ruby-lang.org) 1.9.3 or higher.
 - `gem install gen-text`
 
+Example
+-------
+
+Simple grammar:
+
+    expr =
+      expr ('+'|'-') expr |
+      expr ('*'|'/') expr |
+      '(' expr ')' |
+      0...1000 ;
+
+Sample output:
+
+    (914-548*155+131*799)*827
+
+See more examples in "sample" directory.
+
 Usage
 -----
 
@@ -69,8 +86,9 @@ You may use the following expressions in the rules' right part:
         <tt>'str'</tt>
       </td>
       <td>
-        <p>Generate a string.</p>
-        <p>Following escape sequences are allowed: "\n", "\t", "\e" and "\." where "." is an arbitrary character.</p>
+        Generate a string.
+        <p></p>
+        Following escape sequences are allowed: "\n", "\t", "\e" and "\." where "." is an arbitrary character.
       </td>
     </tr>
     <tr>
@@ -78,7 +96,7 @@ You may use the following expressions in the rules' right part:
       <td>Generate an UTF-8 character sequence corresponding to the Unicode code. E. g.: <tt>U+000A</tt> is equivalent to <tt>"\n"</tt>.</td>
     </tr>
     <tr>
-      <td><tt>n</tt> (a number)</td>
+      <td><tt>n</tt> (a number)</td>
       <td>Generate a number</td>
     </tr>
     <tr>
@@ -87,7 +105,7 @@ You may use the following expressions in the rules' right part:
     </tr>
     <tr>
       <td><tt>nonterm</tt></td>
-      <td>–</td>
+      <td>—</td>
     </tr>
     <tr>
       <td colspan="2"><center><strong>Combinators</strong></center></td>
@@ -104,33 +122,28 @@ You may use the following expressions in the rules' right part:
     </tr>
     <tr>
       <td>
-        <tt>
-          | expr <br/>
-          | expr
-        </tt>
+<tt><pre>| expr
+| expr</pre></tt>
       </td>
       <td>Random choice (another form).</td>
     </tr>
     <tr>
       <td>
-        <tt>
-          | [m%] expr <br/>
-          | [n%] expr <br/>
-          | expr
-        </tt>
+<tt><pre>| [m%] expr
+| [n%] expr
+| expr</pre></tt>
       </td>
       <td>
-        <p>Random choice with specific probabilities.</p>
-        <p>If probability is unspecified then it is calculated automatically.</p>
+        Random choice with specific probabilities.
+        <p></p>
+        If probability is unspecified then it is calculated automatically.
       </td>
     </tr>
     <tr>
       <td>
-        <tt>
-          | [0.1] expr <br/>
-          | [0.3] expr <br/>
-          | expr
-        </tt>
+<tt><pre>| [0.1] expr
+| [0.3] expr
+| expr</pre></tt>
       </td>
       <td>
         The same as above. Probabilities may be specified as floating point numbers between 0.0 and 1.0.
@@ -145,7 +158,7 @@ You may use the following expressions in the rules' right part:
         <tt>expr*[m...n]</tt> <br/>
       </td>
       <td>
-        <p>Repeat <tt>expr</tt> many times:</p>
+        Repeat <tt>expr</tt> many times:
         <ul>
           <li>0 or more times</li>
           <li>1 or more times</li>
@@ -153,17 +166,39 @@ You may use the following expressions in the rules' right part:
           <li>exactly <tt>n</tt> times</li>
           <li>between <tt>m</tt> and <tt>n</tt> times</li>
         </ul>
-        <p><strong>Note:</strong> you may use <tt>inf</tt> ("infinity") instead of <tt>m</tt> or <tt>n</tt>.</p>
+        <p></p>
+        <strong>Note:</strong> you may use <tt>inf</tt> ("infinity") instead of <tt>m</tt> or <tt>n</tt>.
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <tt>n:expr</tt>
+      </td>
+      <td>
+        Capture a string generated by <tt>expr</tt> into variable <tt>n</tt>. The variable may then be used in <a href="#Code_insertions">Ruby code insertions</a>.
+        <p></p>
+        You may also use names like <tt>$n</tt> and <tt>@n</tt>.
+        <p></p>
+        <strong>Note</strong>: presence of this expression turns on backtracking and output buffering and may result in enormous memory usage.
       </td>
     </tr>
     <tr>
-      <td colspan="2"><center><strong>Ruby code insertions</strong></center></td>
+      <td>
+        <tt>n := expr</tt>
+      </td>
+      <td>
+        The same as above but the output generated by <tt>expr</tt> is discarded.
+      </td>
+    </tr>
+    <tr>
+      <td colspan="2"><center><strong><a id="Code_insertions"></a>Ruby code insertions</strong></center></td>
     </tr>
     <tr>
       <td><tt>{ code }</tt></td>
       <td>
-        <p>Execute the code. Generate nothing.</p>
-        <p><strong>Note</strong>: all code insertions inside a rule share the same scope.</p>
+        Execute the code. Generate nothing.
+        <p></p>
+        <strong>Note</strong>: all code insertions inside a rule share the same scope.
       </td>
     </tr>
     <tr>
@@ -173,15 +208,14 @@ You may use the following expressions in the rules' right part:
     <tr>
       <td><tt>{? code }</tt></td>
       <td>
-        <p>Condition. A code which must evaluate to true.</p>
-        <p><strong>Note</strong>: presence of this expression turns on backtracking and output buffering and may result in enormous memory usage.</p>
+        Condition. A code which must evaluate to true.
+        <p></p>
+        <strong>Note</strong>: presence of this expression turns on backtracking and output buffering and may result in enormous memory usage.
       </td>
     </tr>
   </tbody>
 </table>
 
-TODO: Capture the generated output.
-
 ### Alternate syntax ###
 
 You may use "<-" instead of "=":
@@ -194,13 +228,8 @@ and "/" instead of "|":
 
     `simple choice` <- "a" / "b" ;
 
-Examples
---------
-
-See them in "sample" directory.
-
 Links
 -----
 
-- [Documentation](http://www.rubydoc.info/gems/gen-text/0.0.5)
+- [Documentation](http://www.rubydoc.info/gems/gen-text/0.0.7)
 - [Source code](https://github.com/LavirtheWhiolet/gen-text)

data/lib/gen_text/compile.rb

@@ -256,6 +256,19 @@ module GenText
       
     end
     
+    Capture = ASTNode.new :var_name, :expr, :discard_output do
+      
+      def to_vm_code(context)
+        [
+          *generated_from(pos),
+          [:push_pos],
+          *expr.to_vm_code(context),
+          [:capture, context.rule_scope, var_name, discard_output]
+        ]
+      end
+      
+    end
+    
     Choice = ASTNode.new :alternatives do
       
       def to_vm_code(context)
@@ -372,8 +385,8 @@ module GenText
     end
     
     rule :seq do
-      e = repeat and many {
-        e2 = repeat and e = _(Seq[to_seq_subexprs(e) + to_seq_subexprs(e2)])
+      e = capture and many {
+        e2 = capture and e = _(Seq[to_seq_subexprs(e) + to_seq_subexprs(e2)])
       } and
       e
     end
@@ -385,6 +398,18 @@ module GenText
       end
     end
     
+    rule :capture do
+      _{
+        n = ruby_var_name and
+        d = (
+          _{ colon_eq and :discard_output } or
+          _{ colon and :do_not_discard_output }
+        ) and
+        e = repeat and _(Capture[n, e, (d == :discard_output)])
+      } or
+      _{ repeat }
+    end
+    
     rule :repeat do
       e = primary and many {
         _{
@@ -456,6 +481,8 @@ module GenText
     token :rbracket, "]"
     token :dot, "."
     token :larrow, "<-"
+    token :colon, ":"
+    token :colon_eq, ":="
     
     # Parses "#{start} #{code_part} } #{whitespace_and_comments}".
     # Returns the code_part.
@@ -479,6 +506,10 @@ module GenText
       }.join
     end
     
+    token :ruby_var_name, "variable name" do
+      scan(/[\@\$]?[a-z_][a-z_0-9]*/)
+    end
+    
     token :string do
       _{ string0('"') } or
       _{ string0("'") } or

data/lib/gen_text/vm.rb

@@ -7,12 +7,15 @@ module GenText
     # @return [Boolean] true if +program+ may result in calling
     #   {IO#pos=} and false otherwise.
     def self.may_set_out_pos?(program)
-      program.any? { |instruction| instruction.first == :rescue_ }
+      program.any? do |instruction|
+        [:rescue_, :capture].include? instruction.first
+      end
     end
     
     # Executes +program+.
     # 
-    # After the execution the +out+ may contain garbage after its {IO#pos}.
+    # If +program+ may result in calling {IO#pos=} (see {VM::may_set_out_pos?}
+    # then after the execution the +out+ may contain garbage after its {IO#pos}.
     # It is up to the caller to truncate the garbage or to copy the useful data.
     # 
     # @param program Array of <code>[:method_id, *args]</code>.
@@ -165,6 +168,32 @@ module GenText
       @pc += 1
     end
     
+    # - p := {#pop};
+    # - +binding_+.eval(set variable named +name+ to a substring of {#out} from
+    #   p to current position);
+    # - if +discard_output+ is true then set {IO#pos} of {#out} to p.
+    # 
+    # @param [Binding] binding_
+    # @param [String] name
+    # @param [Boolean] discard_output
+    # @return [void]
+    def capture(binding_, name, discard_output)
+      capture_start_pos = @stack.pop
+      capture_end_pos = @out.pos
+      captured_string = begin
+        @out.pos = capture_start_pos
+        @out.read(capture_end_pos - capture_start_pos)
+      end
+      @out.pos =
+        if discard_output then
+          capture_start_pos
+        else
+          capture_end_pos
+        end
+      binding_.eval("#{name} = #{captured_string.inspect}")
+      @pc += 1
+    end
+    
     # {#push}(eval(+ruby_code+, +file+, +line+))
     # 
     # @param [Binding] binding_
@@ -177,7 +206,15 @@ module GenText
       @pc += 1
     end
     
-    # {#push}({#out}'s {IO#pos} and {#pc} as {RescuePoint})
+    # {#push}({#out}'s {IO#pos})
+    # 
+    # @return [void]
+    def push_pos
+      @stack.push(@out.pos)
+      @pc += 1
+    end
+    
+    # {#push}({#out}'s {IO#pos}, {#pc} as {RescuePoint})
     # 
     # @param [Integer, nil] pc if specified then it is pushed instead of {#pc}.
     # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gen-text
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-26 00:00:00.000000000 Z
+date: 2016-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parse-framework