PHPackages                             stratadox/parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. stratadox/parser

ActiveLibrary[Parsing & Serialization](/categories/parsing)

stratadox/parser
================

Parser combinator library

v0.1.1(2y ago)3131MITPHPPHP >=8.0

Since Nov 9Pushed 2y ago1 watchersCompare

[ Source](https://github.com/Stratadox/Parser)[ Packagist](https://packagist.org/packages/stratadox/parser)[ RSS](/packages/stratadox-parser/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (3)Used By (0)

Parser Combinator
=================

[](#parser-combinator)

[![Github Action](https://github.com/Stratadox/Parser/actions/workflows/php.yml/badge.svg)](https://github.com/Stratadox/Parser/actions/workflows/php.yml)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/85da88003800a211d100e79ce2f70a9203ccdf85b10a44e0a2a6ab9d075ce0a6/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f537472617461646f782f5061727365722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d61696e)](https://scrutinizer-ci.com/g/Stratadox/Parser/?branch=main)

*Simple Yet Powerful Parsing Library.*

What is this
------------

[](#what-is-this)

A library to create custom parsers. Based on the "ancient" concept of [parser combinators](https://en.wikipedia.org/wiki/Parser_combinator), this library contains a vast variety of base parsers, decorators, combinators and helpers.

Why use this
------------

[](#why-use-this)

Parsers made with this library can be used in many ways. Parsing is transforming text into a usable structure.

This can be used for various purposes, whether it be transforming json / csv / xml / yaml / etc. into some kind of data structure, or parsing a custom DSL or expression language into an abstract syntax tree.

Whether you wish to create your own file format, your own programming language, interpret existing file formats or languages... This library is here to help.

How to use this
---------------

[](#how-to-use-this)

For hands on how-tos, see the [guide](docs/guide.md).

### Installation

[](#installation)

Using composer: `composer require stratadox/parser`

### Overview

[](#overview)

There's 3 base parsers: `any`, `text` and `pattern`.

- [*Any*](docs/reference.md#any-symbol) matches any single character.
- [*Text*](docs/reference.md#text) matches a predefined string.
- [*Pattern*](docs/reference.md#pattern) matches a regular expression.

These can be upgraded by a fair amount of add-ons ("decorators"), which can be combined as needed:

- [*Repeatable*](docs/reference.md#repeatable) applies the parser any number of times, yielding a list.
- [*Map*](docs/reference.md#map) modifies successful results based on a function.
- [*Full Map*](docs/reference.md#full-map) modifies all results based on a function.
- [*Ignore*](docs/reference.md#ignore) requires the thing to be there, and then ignores it. (Miauw)
- [*Maybe*](docs/reference.md#maybe) does not require it, but uses it if it's there.
- [*Optional*](docs/reference.md#optional) combines the above two.
- [*Except*](docs/reference.md#except) "un-matches" if another parser succeeds.
- [*End*](docs/reference.md#end) returns an error state if there's unparsed content.
- [*All or Nothing*](docs/reference.md#all-or-nothing) fiddles with the parse error.

Parsers can be combined using these combinators:

- [*Either / Or*](docs/reference.md#either--or) returns the first matching parser of the lot.
- [*Sequence / AndThen*](docs/reference.md#sequence--andthen) puts several parsers one after the other.

All the above can be mixed and combined at will. To make life easier, there's a bunch of combinator shortcuts for "everyday tasks":

- [*Between*](docs/reference.md#between) matches the parser's content between start and end.
- [*Between Escaped*](docs/reference.md#between-escaped) matches unescaped content between start and end.
- [*Split*](docs/reference.md#optional-split) yields one or more results, split by a delimiter.
- [*Must Split*](docs/reference.md#mandatory-split) yields two or more results, split by a delimiter.
- [*Keep Split*](docs/reference.md#mandatory-split-with-separator) yields a structure like `{delimiter: [left, right]}`.

There's several additional helpers, which are essentially mapping shortcuts:

- [*Join*](docs/reference.md#join) implodes the array result into a string.
- [*Non-Empty*](docs/reference.md#non-empty) refuses `empty` results.
- [*At Least*](docs/reference.md#at-least) refuses arrays with fewer than x entries.
- [*At Most*](docs/reference.md#at-most) refuses arrays with more than x entries.
- [*First*](docs/reference.md#first) transforms an array result into its first item.
- [*Item*](docs/reference.md#item) transforms an array result into its nth item.

To enable lazy parsers (and/or to provide a structure), different containers are available:

- [*Lazy Container*](docs/reference.md#lazy-container) manages lazy loading, essential for recursive parsers.
- [*Eager Container*](docs/reference.md#eager-container) a basic typed list of regular parsers.
- [*Recursion-Safe Lazy Container*](docs/reference.md#recursion-safe-lazy-container)prevents infinite looping on left-recursion.
- [*Grammar Container*](docs/reference.md#grammar-container) mixes lazy and eager containers.

### Example 1: CSV

[](#example-1-csv)

For a basic "real life" example, here's a simple CSV parser:

```