From ac88484d4e59911a4f5c60b404e1acc60d24db67 Mon Sep 17 00:00:00 2001
From: Petr Knap <8299754+petrknap@users.noreply.github.com>
Date: Fri, 11 Apr 2025 23:24:55 +0200
Subject: [PATCH] feat: added `Ascii` enum with handy bytes

---
 README.md            | 23 ++++++++++++++++++++++-
 composer.json        |  1 +
 src/Ascii.php        | 31 +++++++++++++++++++++++++++++++
 tests/ReadmeTest.php |  1 +
 4 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 src/Ascii.php

diff --git a/README.md b/README.md
index 5a64616..2327bbe 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # Library for work with binary data and objects
 
 Simple library for work with binary data and objects in PHP.
-See the examples below for more information, or check out [`Encoder`](./src/Encoder.php), [`Decoder`](./src/Decoder.php), [`Serializer`](./src/Serializer.php) and [`Byter`](./src/Byter.php).
+See the examples below for more information, or check out [`Encoder`](./src/Encoder.php), [`Decoder`](./src/Decoder.php), [`Serializer`](./src/Serializer.php), [`Byter`](./src/Byter.php) and [`Ascii`](./src/Ascii.php).
+
+## Coder
 
 ```php
 namespace PetrKnap\Binary;
@@ -13,6 +15,8 @@ $decoded = Binary::decode($encoded)->base64()->zlib()->checksum()->data;
 printf('Data was coded into `%s` %s.', $encoded, $decoded === $data ? 'successfully' : 'unsuccessfully');
 ```
 
+## Serializer
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -26,6 +30,8 @@ $unserialized = Binary::unserialize($serialized);
 printf('Data was serialized into `%s` %s.', base64_encode($serialized), $unserialized === $data ? 'successfully' : 'unsuccessfully');
 ```
 
+## Self-serializer
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -54,6 +60,8 @@ printf(
 );
 ```
 
+## Byter
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -70,6 +78,19 @@ printf(
 );
 ```
 
+## ASCII
+
+```php
+namespace PetrKnap\Binary;
+
+printf(
+    Ascii::GroupSeparator->join(
+        Ascii::RecordSeparator->join(Ascii::UnitSeparator->join('200', 'EUR'), 'Maya Wilson'),
+        Ascii::RecordSeparator->join(Ascii::UnitSeparator->join('1600', 'USD'), 'Quinton Rice'),
+    ),
+);
+```
+
 ---
 
 Run `composer require petrknap/binary` to install it.
diff --git a/composer.json b/composer.json
index 283e90d..bca9b81 100755
--- a/composer.json
+++ b/composer.json
@@ -25,6 +25,7 @@
   ],
   "homepage": "https://github.com/petrknap/php-binary",
   "keywords": [
+    "ascii",
     "base64",
     "binary",
     "checksum",
diff --git a/src/Ascii.php b/src/Ascii.php
new file mode 100644
index 0000000..5ed3502
--- /dev/null
+++ b/src/Ascii.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @see https://datatracker.ietf.org/doc/html/rfc20
+ */
+enum Ascii: string
+{
+    public const FILE_SEPARATOR = "\x1C";
+    public const GROUP_SEPARATOR = "\x1D";
+    public const NULL = "\x00";
+    public const RECORD_SEPARATOR = "\x1E";
+    public const UNIT_SEPARATOR = "\x1F";
+
+    case FileSeparator = self::FILE_SEPARATOR;
+    case GroupSeparator = self::GROUP_SEPARATOR;
+    case Null = self::NULL;
+    case RecordSeparator = self::RECORD_SEPARATOR;
+    case UnitSeparator = self::UNIT_SEPARATOR;
+
+    /**
+     * @see implode()
+     */
+    public function join(string $element1, string ...$elementN): string
+    {
+        return implode($this->value, [$element1, ...$elementN]);
+    }
+}
diff --git a/tests/ReadmeTest.php b/tests/ReadmeTest.php
index 3bbe55f..8e842e1 100644
--- a/tests/ReadmeTest.php
+++ b/tests/ReadmeTest.php
@@ -24,6 +24,7 @@ public static function getExpectedOutputsOfPhpExamples(): iterable
             'serializer' => 'Data was serialized into `S7QysqoutjKxUiqpLEhVsi62srRSysxNTE/VL8hLB/GBUimJJYkgpoWxlVJngJ87L5cUFwMDA6+nh0sQkGYEYQ42ICkveqQTxCkOcndiWHdO5iVYlYtjiER48o/9Ux7aM7C9Z1qixnnFBCjB4Onq57LOKaFJyboWAA==` successfully.',
             'self-serializer' => 'Data object was serialized into `DckxCsMwDAXQq4jMJbTd6qwdewnjfMoHSw6W1KX07s324NVyK1+W6+blcS/La0yo8PBU2UcfU5whVREXacMcLRA5pe486I32FnTGKs+kywcGq3Eqe0w2ws+GwiJ1XbbfHw==` successfully.',
             'byter' => 'Hashes and data was unbitten into `IoPwxcGHZQM0gfF966vHI3kleehoRKHtC32Xh30RDlg5E026hmlpFnFwbchsoQARSibVpfbWVfuwAHLbGxjFl9eC8fiGaWkWcXBtyGyhABFKJtWl9tZV+7AActsbGMWX14Lx+A==` successfully.',
+            'ascii' => '200' . Ascii::UNIT_SEPARATOR . 'EUR' . Ascii::RECORD_SEPARATOR . 'Maya Wilson' . Ascii::GROUP_SEPARATOR . '1600' . Ascii::UNIT_SEPARATOR . 'USD' . Ascii::RECORD_SEPARATOR . 'Quinton Rice',
         ];
     }
 }