Skip to content

Commit

Permalink
Merge pull request #142 from d-plaindoux/dev
Browse files Browse the repository at this point in the history 
0.8 release
  • Loading branch information
@nicolas-zozol
nicolas-zozol committed May 15, 2019
2 parents 75baf14 + eb7398c commit ed334be
Show file tree
Hide file tree
Showing 36 changed files with 873 additions and 470 deletions.
44 changes: 25 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Masala Parser is a Javascript implementation of the Haskell **Parsec**.

### Use cases

* It can create a full parser from scratch
* It can create a **full parser from scratch**
* It can extract data from a big text and **replace complex regexp**
* It works in any **browser**
* There is a good **typescript** type declaration
Expand Down Expand Up @@ -41,10 +41,19 @@ Check the [Change Log](./changelog.md) if you can from a previous version.

# Reference

You will find an [Masala Parser online reference](documentation/typedoc/modules/_masala_parser_d_.html), generated from typescript interface.
You will find an [Masala Parser online reference](http://www.robusta.io/masala-parser/ts/modules/_masala_parser_d_.html), generated from typescript interface.

# Quick Examples

## Hello World

```js
const helloParser = C.string('hello');
const white = C.char(' ');
const worldParser = C.char('world');
const combinator = helloParser.then(white.rep()).then(worldParser);
```

## Floor notation

```js
Expand Down Expand Up @@ -75,11 +84,14 @@ Let's say we have a document :

>>> The James Bond series, by writer Ian Fleming, focuses on a fictional British Secret Service agent created in 1953, who featured him in twelve novels and two short-story collections. Since Fleming's death in 1964, eight other authors have written authorised Bond novels or novelizations: Kingsley Amis, Christopher Wood, John Gardner, Raymond Benson, Sebastian Faulks, Jeffery Deaver, William Boyd and Anthony Horowitz.
There are many way to analyze this document, for example finding names inside. But what is a name ? We can say that it
is a combination of two following words starting with an uppercase. But what is a word ? What are following words ?
What is a starting uppercase word ?
The parser could fetch every names, ie two consecutive words starting with uppercase.
The parser will read through the document and aggregate a Response,
which contains a value and the current offset in the text.

The goal of a parser is to find out. The goal of Masala Parser is to make this easy.
This value will evolve when the parser will meet new characters,
but also with some function calls, such as the `map()` function.

![](./documentation/parsec-monoid.png)



Expand Down Expand Up @@ -115,25 +127,19 @@ After parsing, there are two subtypes of `Response`:
Like a language, the parser is built then executed. With Masala, we build using other parsers.

```js
const parser1 = C.string('hello');
const helloParser = C.string('hello');
const white = C.char(' ');
const parser2 = C.char('world');
const myNewParser = parser1.then(white.rep()).then(parser2);
const worldParser = C.char('world');
const combinator = helloParser.then(white.rep()).then(worldParser);
```

There is a compiling time when you combine your parser, and an execution time when the parser
runs its `parse(stream)` function. You will have the `Response` after parsing.


So after building, the parser is executed against a stream of token. For simplicity, we will use a stream of characters, which is a text :)
So after building, the parser is executed against a stream of token.
For simplicity, we will use a stream of characters, which is a text :)

The parser will read through the document and aggregate a Response, which contains a value and the current offset in the text.

This value will evolve when the parser will meet new characters,
but also with some function calls, such as the `map()` function.

![](./documentation/parsec-monoid.png)



## Hello Gandhi
Expand All @@ -149,9 +155,9 @@ var helloParser = C.string("Hello")
.then(C.letters()) // succession of A-Za-z letters
.last(); // keeping previous letters

var response = helloParser.val("Hello Gandhi"); // val(x) is a shortcut for parse(Stream.ofString(x));
var value = helloParser.val("Hello Gandhi"); // val(x) is a shortcut for parse(Stream.ofString(x)).value;

assertEquals('Gandhi', response.value);
assertEquals('Gandhi', value);
```


Expand Down
2 changes: 1 addition & 1 deletion documentation/typedoc/assets/js/search.js
View file

Large diffs are not rendered by default.

77 changes: 71 additions & 6 deletions documentation/typedoc/classes/_masala_parser_d_.genlex.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,8 @@ <h2>Index</h2>
<section class="tsd-index-section tsd-is-not-exported">
<h3>Methods</h3>
<ul class="tsd-index-list">
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-not-exported"><a href="_masala_parser_d_.genlex.html#get" class="tsd-kind-icon">get</a></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-not-exported"><a href="_masala_parser_d_.genlex.html#keywords" class="tsd-kind-icon">keywords</a></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-not-exported"><a href="_masala_parser_d_.genlex.html#setseparatorrepetition" class="tsd-kind-icon">set<wbr>Separator<wbr>Repetition</a></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-not-exported"><a href="_masala_parser_d_.genlex.html#setseparators" class="tsd-kind-icon">set<wbr>Separators</a></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-has-type-parameter tsd-is-not-exported"><a href="_masala_parser_d_.genlex.html#setseparatorsparser" class="tsd-kind-icon">set<wbr>Separators<wbr>Parser</a></li>
Expand All @@ -107,6 +109,60 @@ <h3>Methods</h3>
</section>
<section class="tsd-panel-group tsd-member-group tsd-is-not-exported">
<h2>Methods</h2>
<section class="tsd-panel tsd-member tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a name="get" class="tsd-anchor"></a>
<h3>get</h3>
<ul class="tsd-signatures tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<li class="tsd-signature tsd-kind-icon">get<span class="tsd-signature-symbol">(</span>tokenName<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><a href="../interfaces/_masala_parser_d_.token.html" class="tsd-signature-type">Token</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">&gt;</span></li>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L883">masala-parser.d.ts:883</a></li>
</ul>
</aside>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
<h5>tokenName: <span class="tsd-signature-type">string</span></h5>
</li>
</ul>
<h4 class="tsd-returns-title">Returns <a href="../interfaces/_masala_parser_d_.token.html" class="tsd-signature-type">Token</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">&gt;</span></h4>
</li>
</ul>
</section>
<section class="tsd-panel tsd-member tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a name="keywords" class="tsd-anchor"></a>
<h3>keywords</h3>
<ul class="tsd-signatures tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<li class="tsd-signature tsd-kind-icon">keywords<span class="tsd-signature-symbol">(</span>tokens<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><a href="../interfaces/_masala_parser_d_.token.html" class="tsd-signature-type">Token</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></li>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L881">masala-parser.d.ts:881</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>tonkenize all items, given them the name of the token
Exemple : keywords([&#39;AND&#39;, &#39;OR&#39;]) will create the tokens named &#39;AND&#39; and &#39;OR&#39; with C.string(&#39;AND&#39;), C.string(&#39;OR)</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
<h5>tokens: <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span></h5>
<div class="tsd-comment tsd-typography">
</div>
</li>
</ul>
<h4 class="tsd-returns-title">Returns <a href="../interfaces/_masala_parser_d_.token.html" class="tsd-signature-type">Token</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></h4>
</li>
</ul>
</section>
<section class="tsd-panel tsd-member tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a name="setseparatorrepetition" class="tsd-anchor"></a>
<h3>set<wbr>Separator<wbr>Repetition</h3>
Expand All @@ -117,7 +173,7 @@ <h3>set<wbr>Separator<wbr>Repetition</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L862">masala-parser.d.ts:862</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L874">masala-parser.d.ts:874</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
Expand Down Expand Up @@ -149,7 +205,7 @@ <h3>set<wbr>Separators</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L846">masala-parser.d.ts:846</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L858">masala-parser.d.ts:858</a></li>
</ul>
</aside>
<h4 class="tsd-parameters-title">Parameters</h4>
Expand All @@ -172,7 +228,7 @@ <h3>set<wbr>Separators<wbr>Parser</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L854">masala-parser.d.ts:854</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L866">masala-parser.d.ts:866</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
Expand Down Expand Up @@ -210,7 +266,7 @@ <h3>tokenize</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L840">masala-parser.d.ts:840</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L852">masala-parser.d.ts:852</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
Expand Down Expand Up @@ -260,7 +316,7 @@ <h3>tokens</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L844">masala-parser.d.ts:844</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L856">masala-parser.d.ts:856</a></li>
</ul>
</aside>
<h4 class="tsd-returns-title">Returns <a href="../modules/_masala_parser_d_.html#tokencollection" class="tsd-signature-type">TokenCollection</a></h4>
Expand All @@ -277,7 +333,7 @@ <h3>use</h3>
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/da715d0/masala-parser.d.ts#L842">masala-parser.d.ts:842</a></li>
<li>Defined in <a href="https://github.com/d-plaindoux/masala-parser/blob/c3af2fd/masala-parser.d.ts#L854">masala-parser.d.ts:854</a></li>
</ul>
</aside>
<h4 class="tsd-type-parameters-title">Type parameters</h4>
Expand Down Expand Up @@ -319,6 +375,12 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">P</span><
<li class="current tsd-kind-class tsd-parent-kind-external-module tsd-is-not-exported">
<a href="_masala_parser_d_.genlex.html" class="tsd-kind-icon">Gen<wbr>Lex</a>
<ul>
<li class=" tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a href="_masala_parser_d_.genlex.html#get" class="tsd-kind-icon">get</a>
</li>
<li class=" tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a href="_masala_parser_d_.genlex.html#keywords" class="tsd-kind-icon">keywords</a>
</li>
<li class=" tsd-kind-method tsd-parent-kind-class tsd-is-not-exported">
<a href="_masala_parser_d_.genlex.html#setseparatorrepetition" class="tsd-kind-icon">set<wbr>Separator<wbr>Repetition</a>
</li>
Expand Down Expand Up @@ -431,6 +493,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">P</span><
<li class=" tsd-kind-variable tsd-parent-kind-external-module">
<a href="../modules/_masala_parser_d_.html#n" class="tsd-kind-icon">N</a>
</li>
<li class=" tsd-kind-function tsd-parent-kind-external-module tsd-has-type-parameter">
<a href="../modules/_masala_parser_d_.html#tuple-1" class="tsd-kind-icon">tuple</a>
</li>
</ul>
</nav>
</div>
Expand Down
Loading

0 comments on commit ed334be

Please sign in to comment.