Metadata (#8)

* Metadata

* Fix code style (php-cs-fixer)

* Code style

Co-authored-by: PHP CS Fixer <phpcsfixer@example.com>

tests/Pest.php

@@ -1,67 +1,63 @@
 <?php
 
-/*
-|--------------------------------------------------------------------------
-| Test Case
-|--------------------------------------------------------------------------
-|
-| The closure you provide to your test functions is always bound to a specific PHPUnit test
-| case class. By default, that class is "PHPUnit\Framework\TestCase". Of course, you may
-| need to change it using the "uses()" function to bind a different classes or traits.
-|
-*/
-
-use ArchTech\Enums\From;
-use ArchTech\Enums\InvokableCases;
-use ArchTech\Enums\Names;
-use ArchTech\Enums\Options;
-use ArchTech\Enums\Values;
+use ArchTech\Enums\{InvokableCases, Options, Names, Values, From, Metadata};
+use ArchTech\Enums\Meta\Meta;
+use ArchTech\Enums\Meta\MetaProperty;
 
 uses(ArchTech\Enums\Tests\TestCase::class)->in('Pest');
 
-/*
-|--------------------------------------------------------------------------
-| Expectations
-|--------------------------------------------------------------------------
-|
-| When you're writing tests, you often need to check that values meet certain conditions. The
-| "expect()" function gives you access to a set of "expectations" methods that you can use
-| to assert different things. Of course, you may extend the Expectation API at any time.
-|
-*/
+#[Attribute]
+class Color extends MetaProperty {}
 
-expect()->extend('toBeOne', function () {
-    return $this->toBe(1);
-});
-
-/*
-|--------------------------------------------------------------------------
-| Functions
-|--------------------------------------------------------------------------
-|
-| While Pest is very powerful out-of-the-box, you may have some testing code specific to your
-| project that you don't want to repeat in every file. Here you can also expose helpers as
-| global functions to help you to reduce the number of lines of code in your test files.
-|
-*/
-
-function something()
+#[Attribute]
+class Desc extends MetaProperty
 {
-    // ..
+    public static function method(): string
+    {
+        return 'description';
+    }
 }
 
+#[Attribute]
+class Instructions extends MetaProperty
+{
+    public static string $method = 'help';
+
+    protected function transform(mixed $value): mixed
+    {
+        return 'Help: ' . $value;
+    }
+}
+
+/**
+ * @method string description()
+ * @method string color()
+ */
+#[Meta(Color::class, Desc::class)] // variadic syntax
 enum Status: int
 {
-    use InvokableCases, Options, Names, Values, From;
+    use InvokableCases, Options, Names, Values, From, Metadata;
 
+    #[Color('orange')] #[Desc('Incomplete task')]
     case PENDING = 0;
+
+    #[Color('green')] #[Desc('Completed task')]
+    #[Instructions('Illegal meta property — not enabled on the enum')]
     case DONE = 1;
 }
 
+#[Meta([Color::class, Desc::class, Instructions::class])] // array
 enum Role
 {
-    use InvokableCases, Options, Names, Values, From;
+    use InvokableCases, Options, Names, Values, From, Metadata;
 
+    #[Color('indigo')]
+    #[Desc('Administrator')]
+    #[Instructions('Administrators can manage the entire account')]
     case ADMIN;
+
+    #[Color('gray')]
+    #[Desc('Read-only guest')]
+    #[Instructions('Guest users can only view the existing records')]
     case GUEST;
 }

tests/Pest/MetadataTest.php

@@ -0,0 +1,63 @@
+<?php
+
+test('pure enums can have metadata on cases', function () {
+    expect(Role::ADMIN->color())->toBe('indigo');
+    expect(Role::GUEST->color())->toBe('gray');
+
+    expect(Role::ADMIN->description())->toBe('Administrator');
+    expect(Role::GUEST->description())->toBe('Read-only guest');
+
+    expect(Role::ADMIN->help())->toBe('Help: Administrators can manage the entire account');
+    expect(Role::GUEST->help())->toBe('Help: Guest users can only view the existing records');
+});
+
+test('backed enums can have metadata on cases', function () {
+    expect(Status::DONE->color())->toBe('green');
+    expect(Status::PENDING->color())->toBe('orange');
+
+    expect(Status::PENDING->description())->toBe('Incomplete task');
+    expect(Status::DONE->description())->toBe('Completed task');
+});
+
+test('meta properties must be enabled on the enum to be usable on cases', function () {
+    expect(Role::ADMIN->help())->not()->toBeNull(); // enabled
+    expect(Status::DONE->help())->toBeNull(); // not enabled
+});
+
+test('meta properties can transform arguments', function () {
+    expect(
+        Instructions::make('Administrators can manage the entire account')->value
+    )->toStartWith('Help: ');
+});
+
+test('meta properties can customize the method name using a method', function () {
+    expect(Desc::method())->toBe('description');
+    expect(Status::DONE->desc())->toBeNull();
+    expect(Status::DONE->description())->not()->toBeNull();
+});
+
+test('meta properties can customize the method name using a property', function () {
+    expect(Instructions::method())->toBe('help');
+    expect(Role::ADMIN->instructions())->toBeNull();
+    expect(Role::ADMIN->help())->not()->toBeNull();
+});
+
+test('enums can be instantiated from metadata', function () {
+    expect(Role::fromMeta(Color::make('indigo')))->toBe(Role::ADMIN);
+    expect(Role::fromMeta(Color::make('gray')))->toBe(Role::GUEST);
+
+    expect(Status::fromMeta(Desc::make('Incomplete task')))->toBe(Status::PENDING);
+    expect(Status::fromMeta(Desc::make('Completed task')))->toBe(Status::DONE);
+});
+
+test('enums can be instantiated from metadata using tryFromMeta')
+    ->expect(Role::tryFromMeta(Color::make('indigo')))
+    ->toBe(Role::ADMIN);
+
+test('fromMeta throws an exception when the enum cannot be instantiated', function () {
+    Role::fromMeta(Color::make('foobar'));
+})->throws(ValueError::class, 'Enum Role does not have a case with a meta property "Color" of value "foobar"');
+
+test('tryFromMeta silently fails when the enum cannot be instantiated')
+    ->expect(Role::tryFromMeta(Color::make('foobar')))
+    ->toBe(null);