A simple parser combinator library built in Gleam.
211 |# Run the eunit tests
213 | rebar3 eunit
214 |
215 | # Run the Erlang REPL
216 | rebar3 shell
217 | If available in Hex
220 | this package can be installed by adding simple_parser to your rebar.config dependencies:
{deps, [
222 | string_parser
223 | ]}.
224 | take_iftake_whileA Parser might fail for a number of reasons, so we enumerate
345 | them here. The Custom constructor is useful when used in combination with
346 | then to give an explanation of why the parser is failing.
pub type Error {
354 | BadParser(String)
355 | Custom(String)
356 | EOF
357 | Expected(String, got: String)
358 | UnexpectedInput(String)
359 | }BadParser(String)Custom(String)EOFExpected(String, got: String)UnexpectedInput(String)A Parser is something that takes a string and attempts to transform it
418 | into something else, often consuming some or all of the input in the process.
Parsers can be combined (that’s why they’re called parser combinators) to 420 | parse more complex structures. You could write a JSON parser, or a CSV parser, 421 | or even do fancy things like parsing and evaluating simple maths expressions.
422 |pub opaque type Parser(a)pub fn any() -> Parser(String)Parse a single grapheme from the input, it could be anything! If the input
464 | is an empty string, this will fail with the EOF error.
import gleam/result.{Ok, Error}
468 | import gleam/should
469 | import string/parser
470 |
471 | pub fn example () {
472 | let parser = parser.any()
473 |
474 | parser.run("Hello world", parser)
475 | |> should.equal(Ok("H"))
476 | }
477 | pub fn drop(keeper: Parser(a), ignorer: Parser(b)) -> Parser(a)This is one of two combinators used in conjuction with succeed
504 | (the other being keep) that come together to form a nice pipeline
505 | API for parsing.
This combinator runs two parsers in sequence, and then keeps the result of 507 | the first parser while ignoring the result of the second. This allows us to 508 | write parsers that enforce a particular structure from the input without 509 | needing to do anything with the result of those structural parsers.
510 |Think of parsing JSON, for example. We need to parse opening and closing curly 511 | braces to know it’s a valid object, and we need to parse the separating colon 512 | to differentiate between key and value. We need to parse these things, but 513 | they’re structural, we might want to parse a key/value pair into a Gleam 514 | tuple; we don’t care about the curly braces or colons but we need to know 515 | they’re there.
516 | import gleam/result.{Ok, Error}
519 | import gleam/should
520 | import gleam/string.{String}
521 | import gleam/int
522 | import string/parser.{UnexpectedInput}
523 |
524 | pub fn example () {
525 | let digit_parser = parser.any() |> parser.then(fn (c) {
526 | case int.parse(c) {
527 | Ok(num) -> parser.succeed(num)
528 | Error(_) -> parser.fail_with(UnexpectedInput)
529 | }
530 | })
531 |
532 | let parser = parser.succeed2(fn (x, y) { x + y })
533 | |> parser.keep(digit_parser)
534 | |> parser.drop(parser.spaces())
535 | |> parser.drop(parser.string("+"))
536 | |> parser.drop(parser.spaces())
537 | |> parser.keep(digit_parser)
538 |
539 | parser.run("1 + 3", parser)
540 | |> should.equal(Ok(4))
541 | }
542 | pub fn eof() -> Parser(Nil)This parser only succeeds when the input is an empty string. Why is that 569 | useful? You can use this in combination with your other parsers to ensure 570 | that you’ve consumed all the input.
571 | import gleam/function
574 | import gleam/result.{Ok, Error}
575 | import gleam/should
576 | import string/parser.{Expected}
577 |
578 | pub fn example () {
579 | let parser = parser.succeed(function.identity)
580 | |> parser.keep(parser.string("Hello"))
581 | |> parser.drop(parser.eof())
582 |
583 | parser.run("Hello", parser)
584 | |> should.equal(Ok("Hello"))
585 |
586 | parser.run("Hello world", parser)
587 | |> should.equal(Error(Expected("End of file", got: " world")))
588 | }
589 | pub fn fail(message: String) -> Parser(a)Create a Parser that always fails regardless of the input. This
616 | uses the Custom error constructor of the Error type. If you’d
617 | like to return a more specific error, you can look at fail_with
618 | instead.
import gleam/result.{Ok, Error}
622 | import gleam/should
623 | import gleam/string
624 | import string/parser.{Custom}
625 |
626 | pub fn example () {
627 | let is_not_space = fn (c) { c != " " }
628 | let parse_four_letter_word = fn (s) {
629 | case string.length(s) {
630 | True ->
631 | parser.succeed(s)
632 |
633 | False ->
634 | parser.fail("Expected a four letter word.")
635 | }
636 | }
637 | let parser = parser.take_while(is_not_space)
638 | |> parser.then(parse_four_letter_word)
639 |
640 | parser.run("Hello world", parser)
641 | |> should.equal(Error(Custom("Expected a four letter word.")))
642 | }
643 | pub fn fail_with(error: Error) -> Parser(a)Create a Parser that always fails regardless of the input. Unlike
670 | fail, you can use any of the constructors for the Error
671 | type here.
import gleam/result.{Ok, Error}
675 | import gleam/should
676 | import gleam/string
677 | import string/parser.{Expected}
678 |
679 | pub fn example () {
680 | let is_not_space = fn (c) { c != " " }
681 | let parse_four_letter_word = fn (s) {
682 | case string.length(s) {
683 | True ->
684 | parser.succeed(s)
685 |
686 | False ->
687 | parser.fail_with(Expected("A four letter word", got: s))
688 | }
689 | }
690 | let parser = parser.take_while(is_not_space)
691 | |> parser.then(parse_four_letter_word)
692 |
693 | parser.run("Hello world", parser)
694 | |> should.equal(Error(Expected("A four letter word", got: s))
695 | }
696 | pub fn keep(
717 | mapper: Parser(fn(a) -> b),
718 | parser: Parser(a),
719 | ) -> Parser(b)This is one of two combinators used in conjuction with succeed
726 | (the other being drop) that come together to form a nice pipeline
727 | API for parsing.
The first argument is a function wrapped up in a Parser, usually
729 | created using succeed. The second argument is a parser for the
730 | value we want to keep. This parser combines the two by applying that value
731 | to the function.
When you use one of the succeed{N} functions such as succeed2
733 | you’ll get back a [Parser] for a function. You might then work out that you
734 | can use keep again, and voila we have a neat declarative pipline parser
735 | that describes what results we want to keep and how.
The explanation is a bit wordy and compicated, but its useage is intuitive.
737 | If you’ve been looking at the rest of the docs for this package, you’ll already
738 | have seen keep used all over the place.
import gleam/result.{Ok, Error}
742 | import gleam/should
743 | import gleam/string.{String}
744 | import gleam/int
745 | import string/parser.{UnexpectedInput}
746 |
747 | pub fn example () {
748 | let digit_parser = parser.any() |> parser.then(fn (c) {
749 | case int.parse(c) {
750 | Ok(num) -> parser.succeed(num)
751 | Error(_) -> parser.fail_with(UnexpectedInput)
752 | }
753 | })
754 |
755 | let parser = parser.succeed2(fn (x, y) { x + y })
756 | |> parser.keep(digit_parser)
757 | |> parser.drop(parser.spaces())
758 | |> parser.drop(parser.string("+"))
759 | |> parser.drop(parser.spaces())
760 | |> parser.keep(digit_parser)
761 |
762 | parser.run("1 + 3", parser)
763 | |> should.equal(Ok(4))
764 | }
765 | pub fn map(parser: Parser(a), f: fn(a) -> b) -> Parser(b)A combinator that transforms a parsed value by applying a function to it and
792 | returning a new Parser with that transformed value. This follows
793 | the same pattern as gleam/option.map
794 | or gleam/result.map.
pub fn example () {
800 | let parser = parser.any() |> parser.map(string.repeat(5))
801 |
802 | parser.run("Hello world", parser)
803 | |> should.equal(Ok("HHHHH"))
804 |
805 | parser.run("", parser)
806 | |> should.equal(Error(parser.EOF))
807 | }
808 | pub fn map2(
829 | parser_a: Parser(a),
830 | parser_b: Parser(b),
831 | f: fn(a, b) -> c,
832 | ) -> Parser(c)A combinator that combines two parsed values by applying a function to them
839 | both and returning a new Parser containing the combined value.
Fun fact, keep is defined using this combinator.
import gleam/result.{Ok, Error}
844 | import gleam/should
845 | import gleam/string
846 | import string/parser
847 |
848 | pub fn example () {
849 | let parser = parser.map2(
850 | parser.string("Hello"),
851 | parser.string("world"),
852 | fn (hello, world) {
853 | string.concat([ hello, " ", world ])
854 | }
855 | )
856 |
857 | parser.run("Helloworld", parser)
858 | |> should.equal(Ok("Hello world"))
859 | }
860 | pub fn one_of(parsers: List(Parser(a))) -> Parser(a)A combinator that tries a list of parsers in sequence until one succeeds. If
887 | you pass in an empty list this parser will fail with the BadParser constructor
888 | of the Error type.
pub fn example () {
895 | let beam_lang = parser.oneOf(
896 | parser.string("Erlang"),
897 | parser.string("Elixir"),
898 | parser.string("Gleam")
899 | )
900 | let parser = parser.succeed2(string.append)
901 | |> parser.keep(parser.string("Hello "))
902 | |> parser.keep(beam_lang)
903 |
904 | parser.run("Hello Gleam", parser)
905 | |> should.equal(Ok("Hello Gleam"))
906 | }
907 | pub fn run(input: String, parser: Parser(a)) -> Result(a, Error)Run a parser and get back its result. If the supplied parser doesn’t entirely 934 | consume its input, the remaining string is dropped, never to be seen again.
935 | import gleam/result.{Ok, Error}
938 | import gleam/should
939 | import string/parser
940 |
941 | pub fn example () {
942 | let parser = parser.any() |> parser.map(string.repeat(5))
943 |
944 | parser.run("Hello world", parser)
945 | |> should.equal(Ok("HHHHH"))
946 |
947 | parser.run("", parser)
948 | |> should.equal(Error(parser.EOF))
949 | }
950 | pub fn spaces() -> Parser(Nil)Parse zero or more spaces in sequence.
977 | import gleam/result.{Ok, Error}
980 | import gleam/should
981 | import string/parser.{Expected}
982 |
983 | pub fn example () {
984 | let parser = parser.succeed("No spaces required")
985 | |> parser.drop(parser.string("Hello"))
986 | |> parser.drop(parser.spaces())
987 | |> parser.drop(parser.string("world"))
988 |
989 | parser.run("Helloworld", parser)
990 | |> should.equal(Ok("No spaces required"))
991 |
992 | let is_space = fn (c) { c == " " }
993 | let parser = parser.succeed("At least one space required")
994 | |> parser.drop(parser.string("Hello"))
995 | |> parser.drop(parser.take_if(is_space))
996 | |> parser.drop(parser.spaces())
997 | |> parser.drop(parser.string("world"))
998 |
999 | parser.run("Helloworld", parser)
1000 | |> should.equal(Error(Expected(" ", got: "world")))
1001 |
1002 | parser.run("Hello world", parser)
1003 | |> should.equal(Ok("At least one space required"))
1004 | }
1005 | pub fn string(value: String) -> Parser(String)Parse an exact string from the input. If you were writing a programming 1032 | language parser, you might use this to parse keywords or symbols.
1033 | import gleam/result.{Ok, Error}
1036 | import gleam/should
1037 | import gleam/string.{String}
1038 | import string/parser.{Expected}
1039 |
1040 | type VariableDeclaration {
1041 | VariableDeclaration(var: String)
1042 | }
1043 |
1044 | pub fn example () {
1045 | let is_not_space = fn (c) { c != " " }
1046 | let parser = parser.succeed(VariableDeclaration)
1047 | |> parser.drop(parser.string("var"))
1048 | |> parser.drop(parser.spaces())
1049 | |> parser.keep(parser.take_while(is_not_space))
1050 | |> parser.drop(parser.string(";"))
1051 |
1052 | parser.run("var x;", parser)
1053 | |> should.equal(Ok(VariableDeclaration(var: "x")))
1054 |
1055 | parser.run("let x;", parser)
1056 | |> should.equal(Error(Expected("var", got: "let x;")))
1057 | }
1058 | pub fn succeed(value: a) -> Parser(a)Ignore the input string and succeed with the given value. Commonly used in
1085 | combination with keep and drop by passing in a function
1086 | to succeed and then using keep to call that function with the
1087 | result of another parser.
If that sounds a bit baffling, see the example below. It is a rewrite of
1089 | the example used for Parser but one that is able to parse
1090 | and ignore leading whitespace from the input.
import gleam/result.{Ok, Error}
1094 | import gleam/should
1095 | import string/parser
1096 |
1097 | pub fn example () {
1098 | let parser = parser.succeed(string.repeat(5))
1099 | |> parser.drop(parser.spaces())
1100 | |> parser.keep(parser.any())
1101 |
1102 | parser.run("Hello world", parser)
1103 | |> should.equal(Ok("HHHHH"))
1104 |
1105 | parser.run(" Hello world", parser)
1106 | |> should.equal(Ok("HHHHH"))
1107 | }
1108 | pub fn succeed2(f: fn(a, b) -> c) -> Parser(fn(a) -> fn(b) -> c)Like succeed but for a function that takes four arguments.
1135 | Functions in Gleam aren’t automatically curried like they are in languages
1136 | like Elm or Haskell, and that is problematic for our succeed
1137 | parser to work correctly. To address this, succeed2 takes a
1138 | function expecting two arguments, and calls function.curry2 to turn
1139 | it into a sequence functions that are expecting one argument.
You could implement this yourself by doing function.curry2(f) |> parser.succeed
1141 | where f is the two-argument function you want to use.
import gleam/result.{Ok, Error}
1145 | import gleam/should
1146 | import string/parser
1147 |
1148 | pub fn example () {
1149 | let is_not_space = fn (c) { c != " " }
1150 | let parser = parser.succeed2(string.append)
1151 | |> parser.keep(parser.take_while(is_not_space))
1152 | |> parser.drop(parser.spaces())
1153 | |> parser.keep(parser.take_while(is_not_space))
1154 |
1155 | parser.run("Hello world", parser)
1156 | |> should.equal(Ok("Helloworld"))
1157 | }
1158 | pub fn succeed3(
1179 | f: fn(a, b, c) -> d,
1180 | ) -> Parser(fn(a) -> fn(b) -> fn(c) -> d)Like succeed but for a function that takes four arguments.
1187 | Functions in Gleam aren’t automatically curried like they are in languages
1188 | like Elm or Haskell, and that is problematic for our succeed
1189 | parser to work correctly. To address this, succeed3 takes a
1190 | function expecting three arguments, and calls function.curry4 to turn
1191 | it into a sequence functions that are expecting one argument.
For an example of how this is used, take a look at the examples given for
1193 | succeed and succeed2.
pub fn succeed4(
1213 | f: fn(a, b, c, d) -> e,
1214 | ) -> Parser(fn(a) -> fn(b) -> fn(c) -> fn(d) -> e)Like succeed but for a function that takes four arguments.
1221 | Functions in Gleam aren’t automatically curried like they are in languages
1222 | like Elm or Haskell, and that is problematic for our succeed
1223 | parser to work correctly. To address this, succeed4 takes a
1224 | function expecting four arguments, and calls function.curry4 to turn
1225 | it into a sequence functions that are expecting one argument.
For an example of how this is used, take a look at the examples given for
1227 | succeed and succeed2.
pub fn take_if(predicate: fn(String) -> Bool) -> Parser(String)Pop a grapheme off the input and test it against some predicate function. If
1253 | it passes then succeed with that grapheme, otherwise fail with the
1254 | UnexpectedInput constructor of the Error type. This is in
1255 | contrast to take_while which will always succeed even if no
1256 | graphemes pass the predicate.
import gleam/result.{Ok, Error}
1260 | import gleam/should
1261 | import string/parser.{UnexpectedInput, EOF}
1262 |
1263 | pub fn example () {
1264 | let is_digit = fn (c) {
1265 | case c {
1266 | "0" | "1" | "2" | "3" | "4" -> True
1267 | "5" | "6" | "7" | "8" | "9" -> True
1268 | _ -> False
1269 | }
1270 | }
1271 | let parser = parser.take_while(is_digit)
1272 |
1273 | parser.run("1337", parser)
1274 | |> should.equal(Ok("1"))
1275 |
1276 | parser.run("Hello world", parser)
1277 | |> should.equal(Error(UnexpectedInput))
1278 |
1279 | parser.run("", parser)
1280 | |> should.equal(Error(EOF))
1281 | }
1282 | pub fn take_while(
1303 | predicate: fn(String) -> Bool,
1304 | ) -> Parser(String)Pop a grapheme off the input string and test it against some predicate function. 1311 | If it passes, pop the next grapheme off and so on until the predicate test 1312 | fails. Join all the passing graphemes back together into a single string and 1313 | succeed with that result.
1314 |This parser always succeeds. If you use [take_while`](#take_while) to
1315 | parse an empty string, or if no graphemes pass the predicate, this will succeed
1316 | with an empty string of its own.
import gleam/result.{Ok, Error}
1320 | import gleam/should
1321 | import string/parser
1322 |
1323 | pub fn example () {
1324 | let is_digit = fn (c) {
1325 | case c {
1326 | "0" | "1" | "2" | "3" | "4" -> True
1327 | "5" | "6" | "7" | "8" | "9" -> True
1328 | _ -> False
1329 | }
1330 | }
1331 | let parser = parser.take_while(is_digit)
1332 |
1333 | parser.run("1337", parser)
1334 | |> should.equal(Ok("1337"))
1335 |
1336 | parser.run("Hello world", parser)
1337 | |> should.equal(Ok(""))
1338 |
1339 | parser.run("", parser)
1340 | |> should.equal(Ok(""))
1341 | }
1342 | pub fn then(
1363 | parser: Parser(a),
1364 | f: fn(a) -> Parser(b),
1365 | ) -> Parser(b)A combinator that can take the result of one parser, and use it to create
1372 | a new parser. This follows the same pattern as
1373 | gleam/option.then or
1374 | gleam/result.then.
This is useful if you want to transform or validate a parsed value and fail 1376 | if something is wrong.
1377 | pub fn example () {
1383 | let is_digit = fn (c) {
1384 | case c {
1385 | "0" | "1" | "2" | "3" | "4" -> True
1386 | "5" | "6" | "7" | "8" | "9" -> True
1387 | _ -> False
1388 | }
1389 | }
1390 | let parse_digits = fn (digits) {
1391 | case int.parse(digits) {
1392 | Ok(num) ->
1393 | parser.succeed(num)
1394 |
1395 | Error(_) ->
1396 | parser.fail_with(UnexpectedInput)
1397 | }
1398 |
1399 | let parser = parser.take_while(is_digit)
1400 | |> parser.then(parse_digits)
1401 |
1402 | parser.run("1337", parser)
1403 | |> should.equal(Ok(1337))
1404 |
1405 | parser.run("Hello world", parser)
1406 | |> should.equal(Error(UnexpectedInput))
1407 | }
1408 |