Improve interface name

Author: nyamsprod

CHANGELOG.md

@@ -6,9 +6,9 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
-- Introduce the`StructuredFieldContainer` interface.
-- `OrderedList`, `InnerList` now implements the `StructuredFieldList` interface.
-- `Parameters` and `Dictionnary` now implements the PHP `StructuredFieldOrderedMap` interface.
+- Introduce the`MemberContainer` interface.
+- `OrderedList`, `InnerList` now implements the `MemberList` interface.
+- `Parameters` and `Dictionnary` now implements the PHP `MemberOrderedMap` interface.
 - `Token::value` is a readonly property.
 - `Item::value` method returns the decoded value of an Item (returns value can be `float|int|string|bool`).
 - `Item::fromToken`, `Item::fromDecodedByteSequence` , `Item::fromEncodedByteSequence` to ease specific string initiation 

docs/basic-usage.md

@@ -7,7 +7,7 @@ an HTTP field value can be:
 - a [Dictionary](ordered-maps.md);
 - a [List](lists.md);
 
-For each of these top-level types, the package provides a dedicated value object to parse the textual
+For each of these top-level types, the package provides a dedicated object to parse the textual
 representation of the field and to serialize the value object back to the textual representation.
 
 - Parsing is done via a common named constructor `fromHttpValue` which expects the Header or Trailer string value.

docs/containers.md

@@ -5,9 +5,9 @@ use Bakame\Http\StructuredFields;
 
 $parameters = StructuredFields\Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
 count($parameters); // returns 3
-$parameters->isEmpty(); // returns false
+$parameters->hasMembers(); // returns true
 $parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'
-$parameters->clear()->isEmpty(); // returns true
+$parameters->clear()->hasNoMembers(); // returns true
 ```
 
 The package exposes [ordered maps](ordered-maps.md)
@@ -20,22 +20,22 @@ and [lists](lists.md)
 - OrderedList,
 - and InnerList
 
-with different requirements. At any given time it is possible with each of these objects to:
+with different requirements.
+
+At any given time it is possible with each of these objects to:
 
 - iterate over its members using the `IteratorAggregate` interface;
 - know the number of members it contains via the `Countable` interface;
-- Access container members via the `ArrayAccess` interface;
-- tell whether the container is empty or not using the `isEmpty` and/or `hasMembers` methods from the `StrucutedFieldContainer` interface;
-- clear its content using the `clear` method from the `StrucutedFieldContainer` interface;
-- unwrap Item value using the `values`, `value` methods from the `StrucutedFieldContainer` interface;
+- access container members via the `ArrayAccess` interface;
+- tell whether the container contains or not members with the `hasNoMembers` and/or `hasMembers` methods from the `MemberContainer` interface;
+- clear its content using the `clear` method from the `MemberContainer` interface;
+- unwrap Item value using the `values`, `value` methods from the `MemberContainer` interface;
 
 getter methods:
 
 - `get` to access an element at a given index (negative indexes are supported)
 - `has` tell whether an element is attached to the container using its `index`;
 
-
-
 **Of note:**
 
 - All setter methods are chainable

docs/item.md

@@ -30,7 +30,7 @@ echo $token->value; // displays 'bar'
 ```
 
 The Token data type is a special string as defined in the RFC. To distinguish it from a normal string,
-the `Bakame\Http\StructuredFields\Token` class is used.
+the `Bakame\Http\StructuredFields\Token` class can be used.
 
 To instantiate the class you are required to use the `Token::fromString` named constructor.
 The class also exposes its value via the public readonly property `value` to enable its textual representation.
@@ -52,14 +52,15 @@ To distinguish it from a normal string, the `Bakame\Http\StructuredFields\ByteSe
 
 To instantiate the class you are required to use the `ByteSequence::fromDecoded` or `ByteSequence::fromEncoded`
 named constructors. The class also exposes the complementary public methods `ByteSequence::decoded`,
-`ByteSequence::encoded`  to enable its textual representation.
+`ByteSequence::encoded` to enable the correct textual representation.
 
 ## Usages
 
-Items can be associated with an ordered maps of key-value pairs also known as parameters, where the
+Items can be associated with parameters that are an ordered maps of key-value pairs where the
 keys are strings and the value are bare items. Their public API is covered in the [ordered maps section](ordered-maps.md].
 
 **An item without any parameter associated to it is said to be a bare item.**
+**Exception will be thrown when trying to access or serialize a parameter object containing non-bare items.**
 
 ```php
 use Bakame\Http\StructuredFields;
@@ -77,6 +78,15 @@ Instantiation via type recognition is done using the `Item::from` named construc
 - The second argument, which is optional, MUST be an iterable construct  
   where its index represents the parameter key and its value an item or an item type value;
 
+It is possible to use
+
+- `Item::fromToken` internally use `Token::fromString` to
+- `Item::fromEncodedByteSequence` internally use `ByteSequence::fromEncoded`
+- `Item::fromDecodedByteSequence` internally use `ByteSequence::fromDecoded`
+
+Those listed named constructores expect a string or a stringable object as its first argument and the
+same argument definition as in `Item::from` for parameters argument.
+
 ```php
 use Bakame\Http\StructuredFields;
 
@@ -93,28 +103,17 @@ $item->parameters->value("a"); // returns the decoded value 'Hello World'
 echo $item->toHttpValue();     // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
-It is possible to use
-
-- `Item::fromToken` internally use `Token::fromString` to
-- `Item::fromEncodedByteSequence` internally use `ByteSequence::fromEncoded`
-- `Item::fromDecodedByteSequence` internally use `ByteSequence::fromDecoded`
-
-Thos listed named constructores expect a string as its first argument and the 
-same argument definition as in `Item::from` for parameters argument.
-
 `Item::fromPair` is an alternative to the `Item::from` named constructor, it expects
 a tuple composed by an array as a list where:
 
 - The first member on index `0` represents one of the six (6) item type value;
 - The second optional member, on index `1`, **MUST** be an iterable construct containing
   tuples of key-value pairs;
 
-Once instantiated, accessing `Item` properties is done via two (2) readonly properties:
-
-- `Item::value` which returns the instance underlying value
-- `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
+Once instantiated, accessing `Item` properties is done via:
 
-And on method called `Item::decodedValue()` which returns the underlying value fully decoded.
+- the method `Item::value` which returns the instance underlying value fully decoded;
+- the readonly property `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 ```php
 use Bakame\Http\StructuredFields;

docs/lists.md

@@ -27,8 +27,11 @@ setter methods
 - `replace` to replace an element at a given position in the list;
 - `remove` to remove elements based on their position;
 
-Additionally, both classes implements PHP `ArrayAccess` interface as syntactic sugar methods
-around the `get`, `has`, `push`, `remove` and `replace` methods.
+In addition to `StructuredField` specific interfaces, both classes implements:
+
+- PHP `Countable` interface.
+- PHP `IteratorAggregate` interface.
+- PHP `ArrayAccess` interface.
 
 ```php
 use Bakame\Http\StructuredFields;
@@ -68,6 +71,7 @@ your logic**
 ```php
 use Bakame\Http\StructuredFields;
 
-$innerList = StructuredFields\OrderedList::fromList([42, 42.0, "42"], ["a" => true]);
+$innerList = StructuredFields\OrderedList::fromList([42, 42.0]);
 $innerList[2] = StructuredFields\Token::fromString('forty-two'); // will throw
+echo $innerList->toHttpValue(), PHP_EOL;
 ```

docs/ordered-maps.md

@@ -54,12 +54,11 @@ echo $dictionary
     ->toHttpValue(); // returns "a=?0, z=42.0"
 ```
 
-## Parameters specific methods
+In addition to `StructuredField` specific interfaces, both classes implements:
 
-The `Parameters` instance exposes the following additional methods:
-
-- `Parameters::values` to list all existing Bare Item values as an array list;
-- `Parameters::value` to return the value of the Bare Item associated to the `$key` or `null` if the key is unknown or invalid;
+- PHP `Countable` interface.
+- PHP `IteratorAggregate` interface.
+- PHP `ArrayAccess` interface.
 
 ```php
 use Bakame\Http\StructuredFields;
@@ -69,7 +68,7 @@ $parameters->keys();     // returns ['b', 'foo']
 $parameters->values();   // returns [true, 'bar']
 $parameters->value('b'); // returns true
 $parameters->get('b');   // returns Item::from(true)
-$parameters['b']; // returns Item::from(true)
+$parameters['b'];        // returns Item::from(true)
 iterator_to_array($parameters->toPairs(), true); // returns [['b', Item::from(true)], ['foo', Item::from('bar')]]
 iterator_to_array($parameters, true); // returns ['b' => Item::from(true), 'foo' => Item::from('bar')]
 $parameters->mergeAssociative(

src/Dictionary.php

@@ -16,9 +16,9 @@
 use function is_array;
 
 /**
- * @implements StructuredFieldOrderedMap<string, Item|InnerList<int, Item>>
+ * @implements MemberOrderedMap<string, Item|InnerList<int, Item>>
  */
-final class Dictionary implements StructuredFieldOrderedMap
+final class Dictionary implements MemberOrderedMap
 {
     /** @var array<string, Item|InnerList<int, Item>> */
     private array $members = [];
@@ -53,11 +53,11 @@ public static function fromAssociative(iterable $members = []): self
      * the first member represents the instance entry key
      * the second member represents the instance entry value
      *
-     * @param StructuredFieldOrderedMap<string, Item|InnerList<int, Item>>|iterable<array{0:string, 1:InnerList<int, Item>|Item|ByteSequence|Token|bool|int|float|string}> $pairs
+     * @param MemberOrderedMap<string, Item|InnerList<int, Item>>|iterable<array{0:string, 1:InnerList<int, Item>|Item|ByteSequence|Token|bool|int|float|string}> $pairs
      */
-    public static function fromPairs(StructuredFieldOrderedMap|iterable $pairs = []): self
+    public static function fromPairs(MemberOrderedMap|iterable $pairs = []): self
     {
-        if ($pairs instanceof StructuredFieldOrderedMap) {
+        if ($pairs instanceof MemberOrderedMap) {
             $pairs = $pairs->toPairs();
         }
 
@@ -97,14 +97,14 @@ public function count(): int
         return count($this->members);
     }
 
-    public function isEmpty(): bool
+    public function hasNoMembers(): bool
     {
         return [] === $this->members;
     }
 
     public function hasMembers(): bool
     {
-        return !$this->isEmpty();
+        return !$this->hasNoMembers();
     }
 
     /**
@@ -355,9 +355,9 @@ public function mergeAssociative(iterable ...$others): self
     /**
      * Merges multiple instances using iterable pairs.
      *
-     * @param StructuredFieldOrderedMap<string, Item|InnerList<int, Item>>|iterable<array{0:string, 1:InnerList<int, Item>|Item|ByteSequence|Token|bool|int|float|string}> ...$others
+     * @param MemberOrderedMap<string, Item|InnerList<int, Item>>|iterable<array{0:string, 1:InnerList<int, Item>|Item|ByteSequence|Token|bool|int|float|string}> ...$others
      */
-    public function mergePairs(StructuredFieldOrderedMap|iterable ...$others): self
+    public function mergePairs(MemberOrderedMap|iterable ...$others): self
     {
         foreach ($others as $other) {
             $this->members = [...$this->members, ...self::fromPairs($other)->members];

src/DictionaryTest.php

@@ -31,7 +31,7 @@ public function it_can_be_instantiated_with_an_collection_of_item_or_inner_list(
 
         self::assertEquals($arrayParams, iterator_to_array($instance));
         $instance->clear();
-        self::assertTrue($instance->isEmpty());
+        self::assertTrue($instance->hasNoMembers());
         self::assertFalse($instance->hasMembers());
     }
 
@@ -63,7 +63,7 @@ public function it_can_add_or_remove_members(): void
         $instance = Dictionary::fromAssociative($arrayParams);
 
         self::assertCount(2, $instance);
-        self::assertFalse($instance->isEmpty());
+        self::assertFalse($instance->hasNoMembers());
         $instance->delete('boolean');
 
         self::assertCount(1, $instance);
@@ -82,7 +82,7 @@ public function it_can_add_or_remove_members(): void
 
         $instance->delete('foobar', 'string');
         self::assertCount(0, $instance);
-        self::assertTrue($instance->isEmpty());
+        self::assertTrue($instance->hasNoMembers());
     }
 
     /** @test */

src/InnerList.php

@@ -14,9 +14,9 @@
 use function count;
 
 /**
- * @implements StructuredFieldList<int, Item>
+ * @implements MemberList<int, Item>
  */
-final class InnerList implements StructuredFieldList
+final class InnerList implements MemberList
 {
     /** @var array<int, Item> */
     private array $members;
@@ -85,14 +85,14 @@ public function count(): int
         return count($this->members);
     }
 
-    public function isEmpty(): bool
+    public function hasNoMembers(): bool
     {
         return [] === $this->members;
     }
 
     public function hasMembers(): bool
     {
-        return !$this->isEmpty();
+        return !$this->hasNoMembers();
     }
 
     /**

src/InnerListTest.php

@@ -19,14 +19,14 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
         $booleanItem = Item::from(true);
         $arrayParams = [$stringItem, $booleanItem];
         $instance = InnerList::fromList($arrayParams, Parameters::fromAssociative(['test' => Item::from(42)]));
-        self::assertFalse($instance->parameters->isEmpty());
+        self::assertFalse($instance->parameters->hasNoMembers());
 
         self::assertSame($stringItem, $instance->get(0));
-        self::assertFalse($instance->isEmpty());
+        self::assertFalse($instance->hasNoMembers());
 
         self::assertEquals($arrayParams, iterator_to_array($instance));
         $instance->clear();
-        self::assertTrue($instance->isEmpty());
+        self::assertTrue($instance->hasNoMembers());
         self::assertFalse($instance->hasMembers());
     }
 
@@ -40,7 +40,7 @@ public function it_can_add_or_remove_members(): void
 
         self::assertCount(2, $instance);
         self::assertTrue($instance->has(1));
-        self::assertTrue($instance->parameters->isEmpty());
+        self::assertTrue($instance->parameters->hasNoMembers());
         self::assertFalse($instance->parameters->hasMembers());
 
         $instance->remove(1);
@@ -57,7 +57,7 @@ public function it_can_add_or_remove_members(): void
 
         $instance->remove(0, 1);
         self::assertCount(0, $instance);
-        self::assertTrue($instance->isEmpty());
+        self::assertTrue($instance->hasNoMembers());
         self::assertFalse($instance->hasMembers());
     }
 
@@ -71,7 +71,7 @@ public function it_can_unshift_insert_and_replace(): void
         $container->replace(0, ByteSequence::fromDecoded('Hello World'));
 
         self::assertCount(3, $container);
-        self::assertFalse($container->isEmpty());
+        self::assertFalse($container->hasNoMembers());
         self::assertSame('(:SGVsbG8gV29ybGQ=: 42.0 42)', $container->toHttpValue());
     }