Download the PHP package tarsana/syntax without Composer

Tarsana Syntax

A tool to encode and decode strings based on flexible and composable syntax definitions.

Table of Contents

• Quick Example

• Installation

• Step by Step Guide

  • Parsing and Dumping Strings

  • Parsing and Dumping Numbers

  • Parsing and Dumping Booleans

  • Parsing and Dumping Arrays

  • Parsing and Dumping Optional Syntaxes Since version 2.0

  • Parsing and Dumping Objects

  • Parsing and Dumping Syntaxes Since version 1.2.0

• Development Notes & Next Steps

• Contributing

Quick Example

Warning: This is just a teaser so if the code seems confusing don't worry, you will understand it after reading the Step by Step Guide.

Let's assume that you have the following text representing a list of developers where each line follow the syntax:

Syntax helps you to parse this document and convert it to manipulable objects easily.

Let's do it:

$developers will contain the following:

You modified $developers and want to save it back to the document following the same syntax ? You can do it:

Installation

Install it using composer

Step by Step Guide

The class Tarsana\Syntax\Factory provides useful static methods to create syntaxes. In this guide, we will start with the basics then show how to use SyntaxSyntax to do things faster.

Parsing and Dumping Strings

Parsing and Dumping Numbers

Parsing and Dumping Booleans

Parsing and Dumping Arrays

Tarsana\Syntax\ArraySyntax represents an array of elements having the same syntax and separated by the same string. So an ArraySyntax is constructed using a Syntax (could be NumberSyntax, StringSyntax or any other) and a separator.

• if the Syntax argument is missing, an instance of StringSyntax is used by default.

• if the separator argument is missing, ',' is used by default.

Parsing and Dumping Optional Syntaxes

Tarsana\Syntax\Optional represents an optional syntax. Given a syntax and a static default value; it will try to parse inputs using the syntax and return the default value when in case of failure.

Parsing and Dumping Objects

Tarsana\Syntax\ObjectSyntax represents an object in which every field can have its own syntax. It's defined by providing an associative array of fields and a separator (if missing, the separator by default is ':').

Parsing and Dumping Syntaxes

Now you know how to parse and dump basic types : string, boolean, number, array, optional and object. But you may notice that writing code for complex syntaxes (object including arrays including objects ...) requires many complex lines of code. SyntaxSyntax was introduced to solve this issue. As the name shows, it's a Syntax that parses and dumps syntaxes, a meta syntax!

So instead of writing this:

You simply write this

Rules

• S::string() is string.
• S::number() is number.
• S::boolean() is boolean.
• S::syntax() is syntax.
• S::optional($type, $default) is (type:default) where type is the string corresponding to $type and default is json_encode($default).
• S::array($type, $separator) is [type|separator] wheretype is the string corresponding to $type and separator is the same as $separator. If the separator is omitted (ie. [type]); the default value is ,. t)`.
• S::object(['name1' => $type1, 'name2' => $type2], $separator) is {name1:type1, name2:type2 |separator] . If the separator is missing the default value is :.

Examples

Development Notes & Next Steps

• version 2.1.0

  • syntax added to the string representation of a syntax and corresponds to the S::syntax() instance.

• version 2.0.0

  • Separators and default values can be specified when creating syntax from string.
  • Escaping separators is now possible.
  • OptionalSyntax added.
  • Attributes default and description removed from Syntax class.
  • Upgraded to PHPUnit 6 and PHP 7.
  • No dependencies.
  • Detailed Exceptions with position of errors.
  • Better Factory methods.

• version 1.2.1:

  • tarsana/functional dependency updated

  • couple of bug fixes

• version 1.2.0:

  • SyntaxSyntax added.

  • separator and itemSyntax getters and setters added to ArraySyntax.

  • separator and fields getters and setters added to ObjectSyntax.

• version 1.1.0:

  • description attribut added to Syntax to hold additional details.

• version 1.0.1:

  • Tests coverage is now 100%

  • Some small bugs of ArraySyntax and ObjectSyntax fixed.
• version 1.0.0: String, Number, Boolean, Array and Object syntaxes.

Contributing

Please take a look at the code and see how other syntax classes are done and tested before fixing or creating a syntax. All feedbacks and pull requests are welcome :D