Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Tweaks to improve the README.

  • Loading branch information...
commit f5720be1b293aec7964bf377c601c4dd4cb43fa9 1 parent 05eb384
@richard-lyman authored
Showing with 71 additions and 40 deletions.
  1. +35 −20 README.markdown
  2. +36 −20 res/README.markdown
View
55 README.markdown
@@ -9,6 +9,7 @@
<h2>Table of Contents</h2>
+* Basic Definitions
* Name and Pronunciation
* Introduction to Reading Grammars (or, Don't Be Afraid)
* Introduction to Using Grammars (or, It's Also Easy)
@@ -18,6 +19,16 @@
* Amotoen Grammar Definition
* Recent Improvements
+<h2>Basic Definitions</h2>
+
+There are several words used in this README that might be made clearer for the beginner through short simple definitions.
+ - **Parser**: a program that takes some input, like a string or a file, and creates something else, like a structure describing the contents of the string or file
+ - **PEG**: a way of defining a parser
+ - **Grammar**: exactly the same as the concept of a grammar for a spoken language --- it provides structure to help in creating *valid* sentences
+ - **Map**: a structure in programming that acts like a dictionary where you can find a definition by looking for the related word
+ - **Vector**: a structure in programming that acts like a line of people --- the first person in line goes first and so on
+ - **Keyword**: a structure in programming that is what it sounds like, a *key* *word*
+
<h2>Name and Pronunciation</h2>
There is a PEG/Packrat library *Neotoma* (a scientific classification for pack
@@ -29,6 +40,26 @@ successfully define 'shortest path' as some stream-of-consciousness process.
I tend to pronounce Amotoen with a style that follows: Am-o-toe-n.
I tend to place emphasis on the 'toe'.
+<h2>Reading Grammars</h2>
+
+The number one goal for Amotoen is to have readable grammars.
+Once you learn a few rules you should be able to read grammars.
+ - Grammars are a Map with Keywords as keys, so it should be easy to lookup a rule
+ - Vectors represent elements that must all match in sequence
+ - Lists allow a wider range of defining how to treat elements in the list, all based on the first element in the list
+ - A * (zero-or-more) requires zero or more of the rest of the list to match
+ - A | (either) requires at least one of the rest of the list to match
+ - A % (any-not) allows anything to match as long as it isn't matched by the rest of the list
+ - An ! (not-predicate) checks to ensure that the rest of the list doesn't match
+
+There are special types of lists that allow you to inject a function call into the process.
+Lists that have an 'a' as the first element will contain an 'Aware Function'.
+Lists that have an 'f' as the first element will contain a simpler 'Function'.
+
+There are also special pre-provided keywords.
+Use of the keyword ```:$``` means that the input should be at the end at that point.
+Use of the keyword ```:.``` means that any character is accepted at that point.
+
<h2>Introduction to Reading Grammars (or, Don't Be Afraid)</h2>
Amotoen is a Clojure library that supports PEG style definitions of grammars that can produce parsers.
@@ -69,13 +100,13 @@ You should now be able to read the three rules that work with whitespace, the :W
Using a grammar like the CSV one above can produce one of two types of outputs.
The more common output would be for a provider of a grammar to process the intermediate format and produce some kind of more relevant one,
-The package com.lithinos.amotoen.grammars.csv provides a 'to-clj' function that produces a Clojure data structure representing the CSV file.
-An example of this format using the 'to-clj' function and an input of just "a,b,c\nx,y,z" is as follows:
+The package com.lithinos.amotoen.grammars.csv provides a ```to-clj``` function that produces a Clojure data structure representing the CSV file.
+An example of this format using the ```to-clj``` function and an input of just ```a,b,c\nx,y,z``` is as follows:
```[["a" "b" "c"] ["x" "y" "z"]]```
The less common output is an AST, or Abstract Syntax Tree.
You **shouldn't have to care about this first kind of output** unless you want to, since it's meant as an intermediate format.
-An example of this format using the CSV grammar and an input of just "a" is as follows:
+An example of this format using the CSV grammar and an input of just ```a``` is as follows:
```
{
:Document [
@@ -99,7 +130,7 @@ One way is to call the Amotoen function 'pegasus' and provide three arguments.
The first argument to pegasus is the key for the root rule in the grammar, the rule that should be run first.
The second argument is the grammar definition.
The third argument is something that fulfils the IAmotoen protocol, and the provided 'wrap-string' function will do just that for Strings.
-Putting all these pieces together with the input from above of "a" you get:
+Putting all these pieces together with the input from above of ```a``` you get:
```(pegasus :Document grammar (wrap-string "a"))```
Much more information can be found in the tests for CSV, the com.lithinos.amotoen.test.csv package.
@@ -119,22 +150,6 @@ result in far greater ease of use as well as increased maintainence.
In other words: **Amotoen is better than clj-peg. Amotoen is not AOT'd**.
-<h2>Reading Grammars</h2>
-
-The number one goal for Amotoen is to have readable grammars.
-Once you learn a few rules you should be able to read grammars.
- - Grammars are a Map with Keywords as keys, so it should be easy to lookup a rule
- - Vectors represent elements that must all match in sequence
- - Lists allow a wider range of defining how to treat elements in the list, all based on the first element in the list
- - A * (zero-or-more) requires zero or more of the rest of the list to match
- - A | (either) requires at least one of the rest of the list to match
- - A % (any-not) allows anything to match as long as it isn't matched by the rest of the list
- - An ! (not-predicate) checks to ensure that the rest of the list doesn't match
-
-There are special types of lists that allow you to inject a function call into the process.
-Lists that have an 'a' as the first element will contain an 'Aware Function'.
-Lists that have an 'f' as the first element will contain a simpler 'Function'.
-
<h2>Redefining Amotoen's Functionality</h2>
Aware Functions ('a') are slightly more complicated than simpler Functions ('f') but bring a **significantly** greater impact.
View
56 res/README.markdown
@@ -9,6 +9,7 @@
<h2>Table of Contents</h2>
+* Basic Definitions
* Name and Pronunciation
* Introduction to Reading Grammars (or, Don't Be Afraid)
* Introduction to Using Grammars (or, It's Also Easy)
@@ -18,6 +19,16 @@
* Amotoen Grammar Definition
* Recent Improvements
+<h2>Basic Definitions</h2>
+
+There are several words used in this README that might be made clearer for the beginner through short simple definitions.
+ - **Parser**: a program that takes some input, like a string or a file, and creates something else, like a structure describing the contents of the string or file
+ - **PEG**: a way of defining a parser
+ - **Grammar**: exactly the same as the concept of a grammar for a spoken language --- it provides structure to help in creating *valid* sentences
+ - **Map**: a structure in programming that acts like a dictionary where you can find a definition by looking for the related word
+ - **Vector**: a structure in programming that acts like a line of people --- the first person in line goes first and so on
+ - **Keyword**: a structure in programming that is what it sounds like, a *key* *word*
+
<h2>Name and Pronunciation</h2>
There is a PEG/Packrat library *Neotoma* (a scientific classification for pack
@@ -29,6 +40,26 @@ successfully define 'shortest path' as some stream-of-consciousness process.
I tend to pronounce Amotoen with a style that follows: Am-o-toe-n.
I tend to place emphasis on the 'toe'.
+<h2>Reading Grammars</h2>
+
+The number one goal for Amotoen is to have readable grammars.
+Once you learn a few rules you should be able to read grammars.
+ - Grammars are a Map with Keywords as keys, so it should be easy to lookup a rule
+ - Vectors represent elements that must all match in sequence
+ - Lists allow a wider range of defining how to treat elements in the list, all based on the first element in the list
+ - A * (zero-or-more) requires zero or more of the rest of the list to match
+ - A | (either) requires at least one of the rest of the list to match
+ - A % (any-not) allows anything to match as long as it isn't matched by the rest of the list
+ - An ! (not-predicate) checks to ensure that the rest of the list doesn't match
+
+There are special types of lists that allow you to inject a function call into the process.
+Lists that have an 'a' as the first element will contain an 'Aware Function'.
+Lists that have an 'f' as the first element will contain a simpler 'Function'.
+
+There are also special pre-provided keywords.
+Use of the keyword ```:$``` means that the input should be at the end at that point.
+Use of the keyword ```:.``` means that any character is accepted at that point.
+
<h2>Introduction to Reading Grammars (or, Don't Be Afraid)</h2>
Amotoen is a Clojure library that supports PEG style definitions of grammars that can produce parsers.
@@ -69,13 +100,13 @@ You should now be able to read the three rules that work with whitespace, the :W
Using a grammar like the CSV one above can produce one of two types of outputs.
The more common output would be for a provider of a grammar to process the intermediate format and produce some kind of more relevant one,
-The package com.lithinos.amotoen.grammars.csv provides a 'to-clj' function that produces a Clojure data structure representing the CSV file.
-An example of this format using the 'to-clj' function and an input of just "a,b,c\nx,y,z" is as follows:
+The package com.lithinos.amotoen.grammars.csv provides a ```to-clj``` function that produces a Clojure data structure representing the CSV file.
+An example of this format using the ```to-clj``` function and an input of just ```a,b,c\nx,y,z``` is as follows:
```[["a" "b" "c"] ["x" "y" "z"]]```
The less common output is an AST, or Abstract Syntax Tree.
You **shouldn't have to care about this first kind of output** unless you want to, since it's meant as an intermediate format.
-An example of this format using the CSV grammar and an input of just "a" is as follows:
+An example of this format using the CSV grammar and an input of just ```a``` is as follows:
```
{
:Document [
@@ -99,7 +130,7 @@ One way is to call the Amotoen function 'pegasus' and provide three arguments.
The first argument to pegasus is the key for the root rule in the grammar, the rule that should be run first.
The second argument is the grammar definition.
The third argument is something that fulfils the IAmotoen protocol, and the provided 'wrap-string' function will do just that for Strings.
-Putting all these pieces together with the input from above of "a" you get:
+Putting all these pieces together with the input from above of ```a``` you get:
```(pegasus :Document grammar (wrap-string "a"))```
Much more information can be found in the tests for CSV, the com.lithinos.amotoen.test.csv package.
@@ -119,22 +150,6 @@ result in far greater ease of use as well as increased maintainence.
In other words: **Amotoen is better than clj-peg. Amotoen is not AOT'd**.
-<h2>Reading Grammars</h2>
-
-The number one goal for Amotoen is to have readable grammars.
-Once you learn a few rules you should be able to read grammars.
- - Grammars are a Map with Keywords as keys, so it should be easy to lookup a rule
- - Vectors represent elements that must all match in sequence
- - Lists allow a wider range of defining how to treat elements in the list, all based on the first element in the list
- - A * (zero-or-more) requires zero or more of the rest of the list to match
- - A | (either) requires at least one of the rest of the list to match
- - A % (any-not) allows anything to match as long as it isn't matched by the rest of the list
- - An ! (not-predicate) checks to ensure that the rest of the list doesn't match
-
-There are special types of lists that allow you to inject a function call into the process.
-Lists that have an 'a' as the first element will contain an 'Aware Function'.
-Lists that have an 'f' as the first element will contain a simpler 'Function'.
-
<h2>Redefining Amotoen's Functionality</h2>
Aware Functions ('a') are slightly more complicated than simpler Functions ('f') but bring a **significantly** greater impact.
@@ -230,3 +245,4 @@ Without supplying a custom collapse function:
- Other things alike, the result should be
```{:S [(\a \a \b \b \c \c)]}```
+
Please sign in to comment.
Something went wrong with that request. Please try again.