Skip to content

Commit 8b471a3

Browse files
committed
Update readme with sections on definitions and operators.
1 parent 2f4aaf5 commit 8b471a3

File tree

1 file changed

+44
-1
lines changed

1 file changed

+44
-1
lines changed

README.md

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
FootlessParser is a simple and pretty naive implementation of a parser combinator in Swift. It enables infinite lookahead, non-ambiguous parsing with error reporting.
44

5-
Also check out [a series of blog posts about the development](http://blog.nottoobadsoftware.com/footlessparser/) and [documentation from the source code](http://kareman.github.io/FootlessParser/).
5+
There is [a series of blog posts about the development](http://blog.nottoobadsoftware.com/footlessparser/) and [documentation from the source code](http://kareman.github.io/FootlessParser/).
66

77
### Introduction
88

@@ -16,6 +16,49 @@ let parser = function1 <^> parser1 <*> parser2 <|> parser3
1616

1717
`parser` will pass the input to `parser1` followed by `parser2`, pass their results to `function1` and return its result. If that fails it will pass the original input to `parser3` and return its result.
1818

19+
### Definitions
20+
21+
##### Parser
22+
A function which takes some input (a sequence of tokens) and returns either the output and the remaining unparsed part of the input, or an error description if it fails.
23+
24+
##### Token
25+
A single item from the input. Like a character from a string, an element from an array or a string from a list of command line arguments.
26+
27+
##### Parser Input
28+
Most often text, but can also be an array or really any collection of anything, provided it conforms to CollectionType.
29+
30+
### Parsers
31+
32+
The general idea is to combine very simple parsers into more complex ones. So `char("a")` creates a parser which checks if the next token from the input is an “a”. If it is it returns that “a”, otherwise it returns an error. You can then use operators and functions like `zeroOrMore` and `optional` to create ever more complex parsers. For more check out [the full list of functions](http://kareman.github.io/FootlessParser/Functions.html).
33+
34+
### Operators
35+
36+
##### <^> (map)
37+
38+
`function <^> parser1` creates a new parser which runs parser1. If it succeeds it passes the output to `function` and returns the result.
39+
40+
##### <*> (apply)
41+
42+
`function <^> parser1 <*> parser2` creates a new parser which first runs parser1. If it succeeds it runs parser2. If that also succeeds it passes both outputs to `function` and returns the result.
43+
44+
The <*> operator requires its left parser to return a function and is normally used together with <^>. `function` must take 2 parameters of the correct types, and it must be [curried](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Declarations.html#//apple_ref/doc/uid/TP40014097-CH34-ID363), like this:
45+
46+
```swift
47+
func function (a:A)(b:B) -> C
48+
```
49+
50+
This is because <*> returns the output of 2 parsers and it doesn't know what to do with them. If you want them returned in a tuple, an array or e.g. added together you can do so in the function before <^> .
51+
52+
If there are 3 parsers and 2 <*> the function must take 3 parameters, and so on.
53+
54+
##### <*
55+
56+
The same as the <*> above, except it discards the result of the parser to its right. Since it only returns one output it doesn't need to be used together with <^> . But you can of course if you want the output converted to something else.
57+
58+
##### *>
59+
60+
The same as <* , but discards the result of the parser to its left instead.
61+
1962
### Example
2063

2164
#### [CSV](http://www.computerhope.com/jargon/c/csv.htm) parser

0 commit comments

Comments
 (0)