From d28ebb20acd6cb5f2f9cc81c002a90ae249348df Mon Sep 17 00:00:00 2001 From: Matthew Hall Date: Fri, 7 Apr 2023 16:43:35 +1200 Subject: Add a bit more to the readme --- README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bf15ac4..c2cfeb1 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,11 @@ The library is still growing and breaking changes may occur at any time. ## Description Parcom is a Crystal library the provides parser combinator functionality. +Users of the Parsec parser library will be familiar with how this library works. ## Prerequisites -* Git +* Git (for installation) ## Installation @@ -34,7 +35,28 @@ shards install ## General usage Parcom parsers work by creating parser objects, and then calling their `#parse` method with the given input. -As this library use parser combinators, complex parser objects should be made by combining simple parsers together. +This will either return a `Result` object, or raise a `ParserFail` exception. + +### Working with strings + +Parcom's parser objects do not (currently) parse from strings. +Rather, they parse from custom-defined `Tokens` objects which wrap sequences of arbitrary token data. +Similar to how a string is thought of as a list of character tokens, Parcom parsers can parse sequences ofany kind of token. + +With that being said, strings can be converted to `Tokens` objects with the `.from_string` method: +``` +a_string = "foo bar" +tokens = Tokens.from_string(a_string) +``` + +Likewise, parsers cannot be created in terms of strings (yet), but as arrays of characters: + +``` +# parses the tokens 'f', 'o', 'o', in that order +p = Parser.token_sequence("foo".chars) + +result = p.parse(tokens) +``` ## Example walkthrough -- cgit v1.2.1