Support for dynamic option field in structures (#36)

examples/A02_Advanced/Structures/run.php

@@ -42,6 +42,7 @@ enum Role : string {
     Field::int('age', 'Age of the person')->validIf(
         fn($value) => $value > 0, "Age has to be positive number"
     ),
+    Field::option('gender', ['male', 'female'], 'Gender of the person')->optional(),
     Field::structure('address', [
         Field::string('street', 'Street name')->optional(),
         Field::string('city', 'City name'),
@@ -57,7 +58,7 @@ enum Role : string {
 
 $text = <<<TEXT
     Jane Doe lives in Springfield, 50210. She is 25 years old and works as manager at McDonald's.
-    McDonald's in Ney York is located at 456 Elm St, NYC, 12345. His favourite books are "The Lord
+    McDonald's in Ney York is located at 456 Elm St, NYC, 12345. Her favourite books are "The Lord
     of the Rings" and "The Hobbit" by JRR Tolkien.
     TEXT;
 
@@ -70,6 +71,7 @@ enum Role : string {
 print("OUTPUT:\n");
 print("Name: " . $person->name . "\n");
 print("Age: " . $person->age . "\n");
+print("Gender: " . $person->gender . "\n");
 print("Address / city: " . $person->address->city . "\n");
 print("Address / ZIP: " . $person->address->zip . "\n");
 print("Role: " . $person->role->value . "\n");

src/Extras/Structure/Traits/Field/HandlesFieldDefinitions.php

@@ -42,6 +42,12 @@ static public function enum(string $name, string $enumClass, string $description
         return new Field($name, $description, $type);
     }
 
+    static public function option(string $name, array $values, string $description = '') : self {
+        $factory = new TypeDetailsFactory();
+        $type = $factory->optionType($values);
+        return new Field($name, $description, $type);
+    }
+
     static public function object(string $name, string $class, string $description = '') : self {
         $factory = new TypeDetailsFactory();
         $type = $factory->objectType($class);

src/Features/Schema/Contracts/CanVisitSchema.php

@@ -8,6 +8,7 @@
 use Cognesy\Instructor\Features\Schema\Data\Schema\EnumSchema;
 use Cognesy\Instructor\Features\Schema\Data\Schema\ObjectRefSchema;
 use Cognesy\Instructor\Features\Schema\Data\Schema\ObjectSchema;
+use Cognesy\Instructor\Features\Schema\Data\Schema\OptionSchema;
 use Cognesy\Instructor\Features\Schema\Data\Schema\ScalarSchema;
 use Cognesy\Instructor\Features\Schema\Data\Schema\Schema;
 
@@ -22,4 +23,5 @@ public function visitObjectSchema(ObjectSchema $schema): void;
     public function visitEnumSchema(EnumSchema $schema): void;
     public function visitScalarSchema(ScalarSchema $schema): void;
     public function visitObjectRefSchema(ObjectRefSchema $schema): void;
+    public function visitOptionSchema(OptionSchema $param) : void;
 }

src/Features/Schema/Data/Schema/OptionSchema.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Cognesy\Instructor\Features\Schema\Data\Schema;
+
+use Cognesy\Instructor\Features\Schema\Contracts\CanVisitSchema;
+
+class OptionSchema extends Schema
+{
+    public function accept(CanVisitSchema $visitor): void {
+        $visitor->visitOptionSchema($this);
+    }
+}

src/Features/Schema/Data/TypeDetails.php

@@ -18,6 +18,7 @@ class TypeDetails
      * @param TypeDetails|null $nestedType for arrays OR null
      * @param string|null $enumType for enums OR null
      * @param array|null $enumValues for enums OR null
+     * @param string|null $docString
      */
     public function __construct(
         public string $type,