Update documentation

Author: nyamsprod

README.md

@@ -63,6 +63,8 @@ header. Content validation is out of scope for this library.**
 
 ### Parsing and Serializing Structured Fields
 
+#### Basic usage
+
 Parsing the header value is done via the `fromHttpValue` named constructor.
 The method is attached to each library's structured fields representation
 as shown below:
@@ -115,14 +117,27 @@ All five (5) structured data type as defined in the RFC are provided inside the
 
 #### Advance usage
 
-In order to allow:
+Starting with version `1.1` the internal parser has been made public in order to allow:
 
 - clearer decoupling betwen parsing and objet building
 - different parsers implementations
 - improve the package usage in testing.
 
-Starting with version `1.1` the internal parser has been made public. The class exposes
-the following method each belonging to a different contract or interface.
+Each `fromHttpValue` method signature has been updated to take a second optional argument
+that represents the parser interface to use in order to allow parsing of the HTTP string
+representation value.
+
+By default, if no parser is provided, the package will default to use the package `Parser` class,
+
+```php
+Item::fromHttpValue(Stringable|string $httpValue, ItemParser $parser = new Parser()): Item;
+InnerList::fromHttpValue(Stringable|string $httpValue, InnerListParser $parser = new Parser()): InnerList;
+Dictionary::fromHttpValue(Stringable|string $httpValue, DictionaryParser $parser = new Parser()): Dictionary;
+OuterList::fromHttpValue(Stringable|string $httpValue, ListParser $parser = new Parser()): OuterList;
+Parameters::fromHttpValue(Stringable|string $httpValue, ParametersParser $parser = new Parser()): Parameters;
+```
+
+The `Parser` class exposes the following method each belonging to a different contract or interface.
 
 ```php
 Parser::parseValue(Stringable|string $httpValue): ByteSequence|Token|DateTimeImmutable|string|int|float|bool;
@@ -133,8 +148,7 @@ Parser::parseList(Stringable|string $httpValue): array;
 Parser::parseDictionary(Stringable|string $httpValue): array;
 ```
 
-While the provided default `Parser` class implements all these methods
-you are free to only implement the methods you need.
+Once instantiated, calling one of the above listed method is straightforward:
 
 ```php
 use Bakame\Http\StructuredFields\Parser;
@@ -149,19 +163,8 @@ $parser->parseItem('@1234567890;file=24');
 //  ]
 ```
 
-Each `fromHttpValue` method signature has been updated to take a second optional argument
-that represents the parser interface to use in order to allow parsing of the HTTP string
-representation value.
-
-By default, if no parser is provided, the package will default to use the package `Parser` class,
-
-```php
-Item::fromHttpValue(Stringable|string $httpValue, ItemParser $parser = new Parser()): Item;
-InnerList::fromHttpValue(Stringable|string $httpValue, InnerListParser $parser = new Parser()): InnerList;
-Dictionary::fromHttpValue(Stringable|string $httpValue, DictionaryParser $parser = new Parser()): Dictionary;
-OuterList::fromHttpValue(Stringable|string $httpValue, ListParser $parser = new Parser()): OuterList;
-Parameters::fromHttpValue(Stringable|string $httpValue, ParametersParser $parser = new Parser()): Parameters;
-```
+**While the provided default `Parser` class implements all these methods you are free to only implement
+the methods you need.**
 
 ### Accessing Structured Fields Values
 
@@ -406,7 +409,7 @@ $map->append(string $key, $value): static;
 $map->prepend(string $key, $value): static;
 $map->mergeAssociative(...$others): static;
 $map->mergePairs(...$others): static;
-$map->remove(string ...$key): static;
+$map->remove(string|int ...$key): static;
 ```
 
 As shown below:
@@ -474,6 +477,19 @@ echo $value;                //b=?0, a=(bar "42" 42 42.0), c=@1671800423
 
 **⚠️WARNING: on duplicate `keys` pair values are merged as per RFC logic.**
 
+The `remove` always accepted string or integer as input. Since version `1.1` it will also remove
+the corresponding pair if its index is given to the method.
+
+```diff
+<?php
+
+use Bakame\Http\StructuredFields\Dictionary;
+
+$field = Dictionary::fromHttpValue('b=?0, a=(bar "42" 42 42.0), c=@1671800423');
+- echo $field->remove('b', 2)->toHttpValue(); // returns a=(bar "42" 42 42.0), c=@1671800423
++ echo $field->remove('b', 2)->toHttpValue(); // returns a=(bar "42" 42 42.0)
+```
+
 #### Automatic conversion
 
 For all containers, to ease instantiation the following automatic conversion are applied on

src/Parser.php

@@ -46,13 +46,13 @@ final class Parser implements DictionaryParser, InnerListParser, ItemParser, Lis
 
     public function parseValue(Stringable|string $httpValue): ByteSequence|Token|DateTimeImmutable|string|int|float|bool
     {
-        $itemString = trim((string) $httpValue, ' ');
-        if ('' === $itemString || 1 === preg_match(self::REGEXP_INVALID_CHARACTERS, $itemString)) {
+        $valueString = trim((string) $httpValue, ' ');
+        if ('' === $valueString || 1 === preg_match(self::REGEXP_INVALID_CHARACTERS, $valueString)) {
             throw new SyntaxError('The HTTP textual representation "'.$httpValue.'" for an item value contains invalid characters.');
         }
 
-        [$value, $offset] = self::extractValue($itemString);
-        if ('' !== substr($itemString, $offset)) {
+        [$value, $offset] = self::extractValue($valueString);
+        if ('' !== substr($valueString, $offset)) {
             throw new SyntaxError('The HTTP textual representation "'.$httpValue.'" for an item value contains invalid characters.');
         }
 
@@ -297,14 +297,11 @@ private static function extractParametersValues(Stringable|string $httpValue): a
         $remainder = $httpValue;
         while ('' !== $remainder && ';' === $remainder[0]) {
             $remainder = ltrim(substr($remainder, 1), ' ');
-
             $key = MapKey::fromStringBeginning($remainder)->value;
             $map[$key] = true;
-
             $remainder = substr($remainder, strlen($key));
             if ('' !== $remainder && '=' === $remainder[0]) {
                 $remainder = substr($remainder, 1);
-
                 [$map[$key], $offset] = self::extractValue($remainder);
                 $remainder = substr($remainder, $offset);
             }

src/ValueParser.php

@@ -12,7 +12,12 @@ interface ValueParser
     /**
      * Returns the data type value represented as a PHP type from an HTTP textual representation.
      *
-     * @see https://www.rfc-editor.org/rfc/rfc8941.html#name-parsing-an-item
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.4
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.5
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.6
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.7
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.8
+     * @see https://www.ietf.org/archive/id/draft-ietf-httpbis-sfbis-02.html#section-4.2.9
      *
      * @throws SyntaxError
      */