feat: added Ascii enum with handy bytes

Author: petrknap

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.

composer.json

@@ -25,6 +25,7 @@
   ],
   "homepage": "https://github.com/petrknap/php-binary",
   "keywords": [
+    "ascii",
     "base64",
     "binary",
     "checksum",

src/Ascii.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @see https://datatracker.ietf.org/doc/html/rfc20
+ */
+enum Ascii: string
+{
+    public const ACKNOWLEDGE = "\x06";
+    public const END_OF_TEXT = "\x03";
+    public const END_OF_TRANSMISSION = "\x04";
+    public const GROUP_SEPARATOR = "\x1D";
+    public const NEGATIVE_ACKNOWLEDGE = "\x15";
+    public const NULL = "\x00";
+    public const RECORD_SEPARATOR = "\x1E";
+    public const START_OF_HEADING = "\x01";
+    public const START_OF_TEXT = "\x02";
+    public const UNIT_SEPARATOR = "\x1F";
+
+    case Acknowledge = self::ACKNOWLEDGE;
+    /**
+     * @note starts a footer
+     */
+    case EndOfText = self::END_OF_TEXT;
+    case EndOfTransmission = self::END_OF_TRANSMISSION;
+    case GroupSeparator = self::GROUP_SEPARATOR;
+    case NegativeAcknowledge = self::NEGATIVE_ACKNOWLEDGE;
+    case Null = self::NULL;
+    case RecordSeparator = self::RECORD_SEPARATOR;
+    case StartOfHeading = self::START_OF_HEADING;
+    /**
+     * @note terminates the header
+     */
+    case StartOfText = self::START_OF_TEXT;
+    case UnitSeparator = self::UNIT_SEPARATOR;
+
+    /**
+     * @see implode()
+     */
+    public function join(string $element1, string ...$elementN): string
+    {
+        return implode($this->value, [$element1, ...$elementN]);
+    }
+}

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',
         ];
     }
 }