antelope 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a92fce8aab3e6c5107252ea4a33c51f7da399473
-  data.tar.gz: 6833313957e6ae84009644b24ce78093bf049285
+  metadata.gz: 16bfd59509232d2d3ac2ae7a2fd3be25254836da
+  data.tar.gz: 28f7a1a19695c03a3f22e0d4b4bcf3ddea518fd4
 SHA512:
-  metadata.gz: 0904f4b66bbb6468462420b81bdcd3d711291137f9ca54232bf3856dc8f1fafe6d208186c4db6d2aeb74af7b83e3fd74b2877a159c80767eac55325fdee5333b
-  data.tar.gz: c75fa1bc293beb80a2e45fe971c2db0330064919954393121a72fae89872c5a8e1d93f99eebfc247e7f879b25c2dcf86d3ad01d4ba92982f9eed9ffdfbb5a411
+  metadata.gz: c89393e3efb8f38b932aefd49a5b7800879ca7d9a4bcbdc4a23f075f6bae1f5eb758904b6c602856834bb281ebf910ad0ffeb4af4fc2f6212c9813af121253e0
+  data.tar.gz: 62bebf9be801f6408ed4603e401aab55d7e38224dd428073874255ba20e3b1892b9f79e5abb56a4a5bd9de8bbb55501f0c6854a2261ea99526e6b79f420eac67

data/.yardopts

@@ -3,3 +3,5 @@
 -m markdown
 -
 LICENSE.txt
+CONTRIBUTING.md
+GENERATORS.md

data/CONTRIBUTING.md

@@ -6,11 +6,11 @@ First and foremost, **thank you**! Contributing to _Antelope_ is great!  There a
 
 1. Fork the repository ([medcat/antelope])
 2. Create a new branch for your feature (something like `my-feature`)
-3. Make yo' changes
-4. Commit yo' changes
+3. Make your changes
+4. Commit your changes
 5. if(notDone) goto 3;
-6. Push yo' changes
-7. Make yo' pull request
+6. Push your changes
+7. Make a pull request
 
 Creating a new branch is a _really, really_ good idea; it keeps things neat in the world of git.  When you make the pull request, any commits you make to the merging branch are added to the pull request.  Also, _please_ make sure you describe the pull request, and what it does, and why it's needed.
 

data/GENERATORS.md

@@ -10,11 +10,11 @@ class MyGenerator < Antelope::Generator::Base
 end
 ```
 
-Next, you'll want to define a `generate` method on your generator that takes no arguments.  This is used internally by _Antelope_ to actually have your generator perform its generation.  In the case of this generator, we'll have it copy over a template (after running ERb over it).
+Next, you'll want to define a `generate` method on your generator that takes no arguments.  This is used internally by _Antelope_ to actually have your generator perform its generation.  In the case of this generator, we'll have it copy over a template (after running the templating generator over it over it).
 
 ```Ruby
 class MyGenerator < Antelope::Generator::Base
-    
+
   def generate
     template "my_template", "#{file}.my_file"
   end
@@ -25,7 +25,7 @@ end
 
 ```Ruby
 class MyGenerator < Antelope::Generator::Base
-  
+
   def self.source_root
     Pathname.new("/path/to/source")
   end
@@ -39,15 +39,15 @@ end
 In the template, the code is run in the context of the instance of the class, so you have access to instance variables and methods as if you were defining a method on the class:
 
 ```
-% table.each_with_index do |hash, i|
-  state <%= i %>:
-%   hash.each do |token, action|
-    for <%= token %>, I'll <%= action[0] %> <%= action[1] %>
-%   end
-% end
+{{ table.each_with_index do |hash, i| }}
+  state {{= i }}:
+{{   hash.each do |token, action| }}
+    for {{= token }}, I'll {{= action[0] }} {{= action[1] }}
+{{   end }}
+{{ end }}
 ```
 
-_Note: in templates, the ERb syntax allows lines starting with `%` to be interpreted as ruby; this helps remove unwanted line space._
+_Note: in templates, blocks that start at the beginning of a line and end at the end of a line do not produce any whitespace._
 
 `table` here is defined on the base class, and we're iterating over all of the values of it.
 
@@ -60,23 +60,65 @@ The finialized product:
 class MyGenerator < Antelope::Generator::Base
 
   register_as "my_generator"
-  
+
   def self.source_root
     Pathname.new("/path/to/source")
   end
 
   def generate
-    template "my_template", "#{file}.my_file"
+    template "my_template.erb", "#{file}.my_file"
   end
 end
 ```
 
 ```
-# my_template.erb
-% table.each_with_index do |hash, i|
-  state <%= i %>:
-%   hash.each do |token, action|
-    for <%= token %>, I'll <%= action[0] %> <%= action[1] %>
-%   end
-% end
+# my_template.ant
+{{ table.each_with_index do |hash, i| }}
+  state {{= i }}:
+{{   hash.each do |token, action| }}
+    for {{= token }}, I'll {{= action[0] }} {{= action[1] }}
+{{   end }}
+{{ end }}
+```
+
+## Bundling
+
+If you want to bundle a few generators together such that the bundle is generated together, you can use an `Antelope::Generator::Group`.  This would be useful for something like a C language generator, which may need to generate both a header and a source file:
+
+```Ruby
+class CHeader < Antelope::Generator::Base
+  # ...
+end
+
+class CSource < Antelope::Generator::Base
+  # ...
+end
+
+
+class C < Antelope::Generator::Group
+  register_generator CHeader, "c-header"
+  register_generator CSource, "c-source"
+end
 ```
+
+The `register_generator` takes a generator class and a name for the generator, and adds the generator to the list of generators on the receiver (in this case, the `C` class).  Now, when `C#generate` is run, it will run both `CHeader#generate` and `CSource#generate`.
+
+## Using Compiler Directives
+
+Directives are statements that are used in Ace files in order to pass information to _Antelope_.  They normally follow the syntax `%<directive name> [directive arguments]*`.  See [the Ace file format](http://rubydoc.info/github/medcat/antelope/Antelope/Ace) for more information about directives.
+
+In some cases, like in the [Ruby generator][Ruby], options from the Ace file are needed for generation.  In the case of the Ruby generator, we need the error class that the developer wants the generator to use; and we reference it through the `ruby.error-class` directive.  In order to define directives that can be used in custom generators, you just need to add a few lines:
+
+```Ruby
+class MyGenerator < Antelope::Generator::Base
+
+  has_directive "my-generator.some-value", Boolean
+
+end
+```
+
+In this example, we define a directive named `my-generator.some-value`; this directive is eventually coerced into a `true`/`false` value.  In order to actually use the value of the directive, in either the template or a method on the generator, you can reference `directives["my-generator.some-value"]`, which will be `nil` (it wasn't defined), `true` (it was defined, with any arguments), or `false` (it was explicitly defined with one argument, `"false"`).  Some other values you can pass in place of `Boolean` would be `:single` (or `:one`), which only gives the first argument passed to the directive; an `Array` of types, which would coerce each argument into its corresponding element of the array; `Array`, which will give an array of the given arguments; `String`, which gives a string representation of the first argument; any `Numeric` subclass, which would coerce the first argument into an integer; `Float`, which would coerce the first argument into a float; any class, which would be instantized with the arguments to the directive.  Any other values would yield an error.
+
+It is recommended that you namespace directives that only your generator would use, using dashed syntax, like in our example above.  However, some directives are not namespaced, or are not namespaced under a generator; these may be used by any generator.  It is also recommended that you declare every directive that you use.
+
+[Ruby]: http://rubydoc.info/github/medcat/antelope/Antelope/Generator/Ruby

data/README.md

@@ -1,24 +1,94 @@
 # Antelope
 
-TODO: Write a gem description
+_Antelope_ is a parser generator that can generate parsers for any language*.  In the sense of actually creating a parser, it works kind of like [_Bison_][bison] - you give it an input file, say, `language.ace`, and it generates a parser for it, in, say, `language.rb`.  Only, instead of _Bison_'s support only for C, C++, and Java, _Antelope_ is meant to generate parsers for multiple languages.  _Antelope_ is also written in Ruby for understandability.
+
+Enough about that, though, let's get into _Antelope_.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Since you'll only typically use _Antelope_ from the command line, I suggest you install it like so:
+
+    $ gem install antelope
 
-    gem 'antelope'
+If, however, you plan on using it in an application, or need it as a part of a library, you can add `gem "antelope"` to your Gemfile.
 
-And then execute:
+## Usage
 
-    $ bundle
+_Antelope_ is fairly simple to use; you define an `.ace` file, compile it, and use the proper API for the generated language.
 
-Or install it yourself as:
+### How Antelope Works
 
-    $ gem install antelope
+Before getting into Ace files, however, you have to understand how _Antelope_ works.  _Antelope_ generates a LALR(1) parser, like _Bison_; for your benefit, however, there are some terms here to understand:
 
-## Usage
+- LL: A type of parser.  If followed by parenthesis, the number (or letter) in the parenthesis denotes the number of tokens of lookahead; i.e., LL(0) has 0 tokens of lookahead.  Standing for **L** eft to Right, **L** eftmost Derivation, these tend to be handwritten as Recursive Decent parsers.  LL parsers can be represented normally by a set of _productions_.  LL parsers are _Top-Down parsers_, meaning they start with only the _Starting symbol_ and try to match the input.  A look at an LL parser is given [here][ll-parser]; check out [this post][tumblr-ll-parser] for more information about LL parsers.  _Antelope_ does not generate LL parsers.
+- Production: In parsing, a production associates a _nonterminal_ with a _string_ of _nonterminals_ and _terminals_.  It is said that the string of nonterminals and terminals _reduces to_ the nonterminal.  Productions take the form of `A -> y`, with _A_ being the left hand side (and the _nonterminal_), and _y_ being the string.
+- Starting symbol: In parsing, it is the _nonterminal_ that is used to represent any kind of valid input.
+- Symbol: A _nonterminal_ or a _terminal_.
+- Nonterminal: In parsing, a nonterminal is an abstraction used to represent any number of _strings_ of _nonterminals_ and _terminals_.
+- String: In parsing, an ordered set of _symbols_.
+- Terminal: In parsing, it is a concrete value given by the lexer.
+- LR: A family of types of parsers.  If followed by parenthesis, the number (or letter) in the parenthesis denotes the number of tokens of lookahead; i.e., LR(0) has 0 tokens of lookahead.  Standing for **L** eft to Right, **R** ightmost Derivation, they tend to be more complicated than their LL brethren.  LR parsers work by starting with the entire input and finding _Handles_ from that input, eventually ending up at the _Starting symbol_.  LR parsers typically do this by splitting the input into two parts: the _stack_, and the _input_.  LR(0), LR(1), SLR(1), and LALR(1) are all examples of LR parsers.
+- Handle: In a LR parser, it is the _Leftmost complete cluster of leaf nodes_ (in a representative AST).  When a handle is found, a _reduction_ is performed.
+- Stack: Initially empty, it can contain any _symbol_, and is primarily used to represent what the parser has seen.  Finding handles will purely occur at the top of the stack.
+- Reduction/Reduce: In a LR parser, this is an action corresponding to replacing the right side of a _production_ with its left side.  This purely occurs at the top of the _stack_, and correlates to finding a _Handle_.
+- Input: Initially containing the full input, it can contain only _terminals_; it primarily contains what the parser has yet to see.
+- LR(0): In parsing, it is a type of LR parser that uses no lookahead.  It essentially uses a deterministic finite automaton to find _possible_ handles.  It does no checking to make sure that the _possible_ handles are legitimate.
+- SLR(1): A part of the LR family of parsers, it upgrades LR(0) by checking to make sure that the reduction that it will make (as a part of finding a handle) is valid in the context; basically, for every reduction that it can make, it defines a set of terminals that can _FOLLOW_ the corresponding nonterminal.
+- FOLLOW(A) set: In parsing, it defines a set of terminals that can _follow_ the nonterminal _A_ anywhere in the grammar.
+- LALR(1): A part of the LR family of parsers, it upgrades SLR by using a more precise _FOLLOW_ set, called _LA_.
+- LA set: LA(q, A -> y) = { t | S =>* _aAtw_ and _ay_ reaches _q_ }
+- Panic mode: In parsing, this is the mode that a parser can go in for recovery, if it encounters a terminal that it was not expecting.  In panic mode, the parser pops terminals off of the input until it reaches a valid _synchronization token_.  In order to utilize panic mode, at least one production must have the special _error_ terminal in it.  If the parser encounters an error, it will attempt to find a production it can use to resynchronize; if it cannot resynchronize, it will error.  It then attempts to resynchronize by continuously pop terminals off of the input and discarding them, attempting to find a synchronization token.  A synchronization token is a token that follows an _error_ terminal.
+- Shift/reduce conflict: This occurs when the parser is unable to decide if it should shift the next token over from the input to the stack, or to reduce the top token on the stack.  If a shift/reduce conflict cannot be solved by changing the grammar, then precedence rules may be used (see `examples/example.ace`).
+- Reduce/reduce conflict: This occurs when the parser is unable to decide which production to reduce.  This cannot be solved by precedence.
+- Precedence: In some grammars, the _Antelope_ runs into _Shift/reduce conflicts_ when attempting to construct a parser.  To resolve these conflicts, _Antelope_ provides precedence declarations.  Precedence is separated into levels, which each have a type; levels can be _left-associative_, _right-associative_, or _non-associative_.  The higher the level, the higher the precedence.  Think of the Order of Operations here; the operations multiply and divide are left associative, and on a higher level than add and subtract, which are still left-associative:
+
+        MULTIPLY, DIVIDE (left-associative)
+        ADD, SUBTRACT (left-associative)
+
+  Exponentiation, however, is right-associative, and is higher than MULTIPLY or DIVIDE; basically, `2**2**2` would be parsed as `2**(2**2)`, instead of the left-associative `(2**2)**2`.  For an example of a grammar that uses precedence, see `examples/example.ace`.
+
+### Defining the Ace file
+
+The Ace file format is very similar to _Bison_'s _y_ files; this was intentional, to make transitions between the two easy.  The Ace file should be formatted like so:
+
+```
+<directives>
+%%
+<rules>
+%%
+<code>
+```
+
+Both `%%` (internally called _content boundaries_) are required; the minimum file that is _technically_ accepted by _Antelope_ is therefore two content boundaries separated by a newline.
 
-TODO: Write usage instructions here
+In the `<directives>` section, there can be any number and combinations of _code blocks_ and _directives_.  _Code blocks_ are blocks of code delimited by `%{` and `%}`, with the ending delimiter on its own line.  These are copied into the output of the file directly.  _Directives_ tell _Antelope_ information about the grammar.  An example directive would be the `token` or `terminal` directive; this lets _Antelope_ know that a terminal by the given name exists.  Directives take the form `%<name> [<value>]*`, with `<name>` being the directive name, and `<value>` being a string delimited by braces, angle brackets, quotes, or nothing at all.  An example of a directive would be `%token ADD "+"`.  The available directives are determined by the code generators available to _Antelope_ at the time that the Ace file is being compiled.  Some directives, however, are always available:
+
+- `require` (1 argument): This makes _Antelope_ check its version against the first argument to this.  If the versions do _not_ match, _Antelope_ will raise an error and fail to parse the file.  It is recommended to at least require the minor version of _Antelope_ (i.e. `%require "~> 0.1").
+- `token`, `terminal` (1-2 arguments): Defines a terminal.  The first argument defines its name; the second argument defines its value.  Its value isn't used anywhere but the `.output` file, to make it easier to read.
+- `left`, `right`, `nonassoc` (1+ arguments): Defines a precedence level, and sets the type of the level based on the directive name used.
+- `type`: The code generator to use.  Currently, the possible values for this can be `null`, `ruby`, and `output`.
+- `define` (1+ arguments): Sets a key to a value.  This would do the exact same thing that using the key as a directive would do, i.e. `%define something "value"` does the same thing as `%something "value"`. _(note: This is not entirely true.  If the key were one of the above, it would most likely raise an error, complaining that there is no directive named that.)_
+- `panic-mode` (0-1 arguments): Enables/disables panic mode being put in the output code.  Not included by default, but should be.
+
+In the `<rules>` section, there can be any number of rules (which are definitions for productions).  Rules have this syntax:
+
+```
+<head>: <body> ["|" <body>]* [";"]
+```
+
+With `<head>` being the nonterminal that the production(s) reduce to, and `<body>` being one or more symbols followed by an optional block that is executed when is a reduction is made using that production.  A semicolon terminating the rule is optional.  Rules are what make up the grammar. `error`, `nothing`, and `ε` are all special symbols; the first one defines the special `error` terminal (used for panic mode, ignored otherwise), whereas the second two are used to literally mean nothing (i.e., the rule reduces to nothing).  It is not always a good idea to use the `nothing` symbol, since most rules can be written without it.
+
+In the `<code>` section, custom code used to wrap the generated parser can be placed.  In order to embed the generated parser, you must place `%{write}` where you want the generated parser.
+
+### Compiling the Ace file
+
+Compiling the Ace file is somewhat straightforward; `antelope compile /path/to/file.ace` will cover most use cases.  If you want to override the type in the Ace file, you can use the `--type=` command option.  If it is giving an error, and you're not sure what's causing it, you can use the `--verbose` command option to see a backtrace.  If there are any conflicts in the
+
+By default, _Antelope_ always includes the `Output` generator as a part of the output.  This means that an `.output` file will always be generated along with any other files.  The `.output` file contains information about the parser, like the productions that were used, precedence levels, states, and lookahead sets.
+
+### Language API
+
+todo.
 
 ## Contributing
 
@@ -27,3 +97,8 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+* Only if there's a generator for it.
+[bison]: http://www.gnu.org/software/bison/
+[ll-parser]: http://i.imgur.com/XhJKrDW.png
+[tumblr-ll-parser]: http://redjazz96.tumblr.com/post/88336053195/what-antelope-does-and-what-i-hope-it-will-do-part

data/TODO.md

@@ -0,0 +1,58 @@
+# Todo
+
+- Documentation
+- Language API files
+
+## Undocumented:
+
+- `Antelope::Ace::Precedence#to_s`
+- `Antelope::Ace::Scanner::Argument#method_missing`
+- `Antelope::Ace::Scanner::Argument#==`
+- `Antelope::Ace::Scanner::Argument`
+- `Antelope::Ace::Scanner::First#scan_first_directive_arguments`
+- `Antelope::Ace::Token#inspect`
+- `Antelope::CLI`
+- `Antelope::CLI#compile_file`
+- `Antelope::CLI#compile`
+- `Antelope::Generation::Recognizer::State#===`
+- `Antelope::Generator#directives`
+- `Antelope::Generator::Base.register_as`
+- `Antelope::Generator::Base::Boolean`
+- `Antelope::Generator::C`
+- `Antelope::Generator::CHeader#guard_name`
+- `Antelope::Generator::CHeader`
+- `Antelope::Generator::CHeader#generate`
+- `Antelope::Generator::CHeader#namespace`
+- `Antelope::Generator::CSource`
+- `Antelope::Generator::CSource#namespace`
+- `Antelope::Generator::CSource#guard_name`
+- `Antelope::Generator::CSource#generate`
+- `Antelope::Generator::Output#unused_symbols`
+- `Antelope::Generator::Ruby#error_class`
+- `Antelope::Template#parse`
+- `Antelope::Template::NO_SOURCE`
+- `Antelope::Template`
+- `Antelope::Template#determine_source`
+- `Antelope::Template#normalize_input`
+- `Antelope::Template#result`
+- `Antelope::Template::Compiler#parse_comment_tag`
+- `Antelope::Template::Compiler`
+- `Antelope::Template::Compiler#parse_tag`
+- `Antelope::Template::Compiler#parse_output_tag`
+- `Antelope::Template::Compiler#compile`
+- `Antelope::Template::Compiler#parse_text`
+- `Antelope::Template::Compiler#merge_text_tokens`
+- `Antelope::Template::Error`
+- `Antelope::Template::NoTokenError`
+- `Antelope::Template::SyntaxError`
+- `Antelope::Template::Scanner#scan_ending`
+- `Antelope::Template::Scanner#scan_until_brace`
+- `Antelope::Template::Scanner#scan_text`
+- `Antelope::Template::Scanner#scan_everything`
+- `Antelope::Template::Scanner#scan_tag_type`
+- `Antelope::Template::Scanner#scan_tag_contents`
+- `Antelope::Template::Scanner#scan_tag`
+- `Antelope::Template::Scanner#scan_escaped`
+- `Antelope::Template::Scanner`
+- `Antelope::Template::Scanner#scan`
+

data/examples/deterministic.ace

@@ -1,20 +1,32 @@
 %require "~> 0.1"
-%type "ruby"
+%generator "ruby"
 
-%terminal NUMBER
-%terminal SEMICOLON ";"
-%terminal ADD "+"
-%terminal LPAREN "("
-%terminal RPAREN ")"
+%define api.push-pull pull
+%define panic-mode true
+%token <lex> NUMBER
+%token <lex> SEMICOLON ";"
+%token <lex> ADD "+"
+%token <lex> LPAREN "("
+%token <lex> RPAREN ")"
+
+%type <node> s e t
+
+%null.data api.prefix "antelope_"
+%union {
+  struct slip_parser_node* node;
+  struct slip_lex_token* lex;
+  struct slip_parser_list* list;
+}
 
 %%
 
 s: e
-e: t SEMICOLON
- | t ADD e
+e: t[a] SEMICOLON[b] { $$ = $1 }
+ | t[a] ADD[b] e[c]  { $$ = $1 + $2 }
+ | error[a]
 
 t: NUMBER
- | LPAREN e RPAREN
+ | LPAREN e RPAREN   { $$ = $2 }
 
 %%
 

data/examples/example.ace

@@ -1,27 +1,31 @@
 %require "~> 0.1"
-%type "ruby"
+%generator "ruby"
 
+%null.data ruby.error-class { SyntaxError }
+%panic-mode true
 %terminal NUMBER
 %terminal MULTIPLY "*"
+%terminal EXPONENTIATE "^"
 %terminal DIVIDE "/"
 %terminal ADD "+"
 %terminal SUBTRACT "-"
 %terminal LPAREN "("
 %terminal RPAREN ")"
 
-%nonassoc LPAREN RPAREN
+%right EXPONENTIATE
 %left MULTIPLY DIVIDE
 %left ADD SUBTRACT
 
 %%
 
-expression: NUMBER                         { |a| a[1]        }
-          | expression ADD expression      { |a, _, b| a + b }
-          | expression SUBTRACT expression { |a, _, b| a - b }
-          | expression MULTIPLY expression { |a, _, b| a * b }
-          | expression DIVIDE expression   { |a, _, b| a / b }
-          | LPAREN expression RPAREN       { |_, a, _| a     }
-          | LPAREN error RPAREN
+expression: NUMBER                             { |a| a[1]        }
+          | expression EXPONENTIATE expression { |a, _, b| a** b }
+          | expression ADD expression          { |a, _, b| a + b }
+          | expression SUBTRACT expression     { |a, _, b| a - b }
+          | expression MULTIPLY expression     { |a, _, b| a * b }
+          | expression DIVIDE expression       { |a, _, b| a / b }
+          | LPAREN expression RPAREN           { |_, a, _| a     }
+          | LPAREN error RPAREN                { |_, e, _| e[1]  }
 
 %%
 
@@ -34,9 +38,11 @@ class ExampleParser
 end
 
 input = [
+  [:LPAREN],
   [:NUMBER, 2],
   [:ADD],
-  [:NUMBER, 2],
+  [:ADD, 2],
+  [:RPAREN],
   [:MULTIPLY],
   [:NUMBER, 3]
 ]