Add InnerList auto conversion

Author: nyamsprod

README.md

@@ -335,18 +335,23 @@ use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 
 $value = Dictionary::new()
-    ->add('a', Item::fromToken('bar'))
+    ->add('a', InnerList::new(Item::fromToken('bar'), tem::fromString('bar'))
     ->prepend('b', Item::false())
     ->append('c', Item::fromDateString('2022-12-23 13:00:23'))
 ;
 
-echo $value->toHttpValue(); //"b=?0, a=bar, c=@1671800423"
-echo $value;                //"b=?0, a=bar, c=@1671800423"
+echo $value->toHttpValue(); //b=?0, a=(bar "bar"), c=@1671800423
+echo $value;                //b=?0, a=(bar "bar"), c=@1671800423
 ```
 
-**Of note: For all containers, if the submitted type is not a `StructuredField`
-implementing object, it will be passed to `Item::new` to convert it into a
-bare `Item` instances.**
+#### Automatic conversion.
+
+For all containers to ease instantiaiton the following automatic conversion are applied on
+the member argument of each modifying methods, if the submitted type is:
+
+-  a `StructuredField` implementing object, it will be passed as is
+-  an iterable structure it will be converted to an `InnerList` instance using `InnerList::new`
+-  otherwise the value will be converted to an `Item` using `Item::new`.
 
 This means that the previous example can be rewritten like this:
 
@@ -356,7 +361,7 @@ use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 
 $value = Dictionary::new()
-    ->add('a', 'bar')
+    ->add('a', [Token::fromString('bar'), 'bar'])
     ->prepend('b', false)
     ->append('c', new DateTimeImmutable('2022-12-23 13:00:23'))
 ;

src/Dictionary.php

@@ -234,7 +234,10 @@ public function pair(int $index): array
         return [...$this->toPairs()][$this->filterIndex($index)];
     }
 
-    public function add(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
+    /**
+     * @param SfMember|SfMemberInput $member
+     */
+    public function add(string $key, iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
     {
         $members = $this->members;
         $members[MapKey::from($key)->value] = self::filterMember($member);
@@ -265,7 +268,10 @@ public function remove(string|int ...$keys): static
         return $this->newInstance($members);
     }
 
-    public function append(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
+    /**
+     * @param SfMember|SfMemberInput $member
+     */
+    public function append(string $key, iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
     {
         $members = $this->members;
         unset($members[$key]);
@@ -274,7 +280,10 @@ public function append(string $key, StructuredField|Token|ByteSequence|DateTimeI
         return $this->newInstance($members);
     }
 
-    public function prepend(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
+    /**
+     * @param SfMember|SfMemberInput $member
+     */
+    public function prepend(string $key, iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
     {
         $members = $this->members;
         unset($members[$key]);

src/OuterList.php

@@ -156,8 +156,10 @@ public function get(string|int $key): StructuredField
 
     /**
      * Inserts members at the beginning of the list.
+     *
+     * @param SfMember|SfMemberInput ...$members
      */
-    public function unshift(StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
+    public function unshift(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
     {
         if ([] === $members) {
             return $this;
@@ -168,8 +170,10 @@ public function unshift(StructuredField|Token|ByteSequence|DateTimeInterface|str
 
     /**
      * Inserts members at the end of the list.
+     *
+     * @param SfMember|SfMemberInput ...$members
      */
-    public function push(StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
+    public function push(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
     {
         if ([] === $members) {
             return $this;
@@ -181,9 +185,11 @@ public function push(StructuredField|Token|ByteSequence|DateTimeInterface|string
     /**
      * Inserts members starting at the given index.
      *
+     * @param SfMember|SfMemberInput ...$members
+     *
      * @throws InvalidOffset If the index does not exist
      */
-    public function insert(int $key, StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
+    public function insert(int $key, iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool ...$members): static
     {
         $offset = $this->filterIndex($key);
 
@@ -200,7 +206,10 @@ public function insert(int $key, StructuredField|Token|ByteSequence|DateTimeInte
         };
     }
 
-    public function replace(int $key, StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
+    /**
+     * @param SfMember|SfMemberInput $member
+     */
+    public function replace(int $key, iterable|StructuredField|Token|ByteSequence|DateTimeInterface|string|int|float|bool $member): static
     {
         if (null === ($offset = $this->filterIndex($key))) {
             throw InvalidOffset::dueToIndexNotFound($key);