Update documentation

Author: nyamsprod

docs/basic-usage.md

@@ -11,7 +11,7 @@ For each of these top-level types, the package provides a dedicated object to pa
 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.
-- Serializing is done via a common `toHttpValue` public method. The method returns the **normalized string** representation suited for HTTP textual representation.
+- Serializing is done via a common `toHttpValue` public method or using the `__toString` method. The method returns the **normalized string** representation suited for HTTP textual representation.
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
@@ -20,14 +20,14 @@ use Bakame\Http\StructuredFields\OrderedList;
 
 $dictionary = Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
 echo $dictionary->toHttpValue(); // 'a=?0, b, c;foo=bar'
-echo $dictionary; // 'a=?0, b, c;foo=bar'
+echo $dictionary;                // 'a=?0, b, c;foo=bar'
 
 $list = OrderedList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
 echo $list->toHttpValue(); // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
-echo $list; // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
+echo $list;                // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
 
 $item = Item::fromHttpValue('"foo";a=1;b=2');
 echo $item->toHttpValue(); // "foo";a=1;b=2
-echo $item; // "foo";a=1;b=2
+echo $item;                // "foo";a=1;b=2
 ```
 

docs/containers.md

@@ -4,10 +4,10 @@
 use Bakame\Http\StructuredFields\Parameters;
 
 $parameters = Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
-count($parameters); // returns 3
-$parameters->hasMembers(); // returns true
-$parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'
-$parameters->clear()->hasMembers(); // returns false
+count($parameters);                 // returns 3
+$parameters->hasMembers();          // returns true
+$parameters->toHttpValue();         // returns ';a=1;b=2;c="hello world"'
+Paramaters::create()->hasMembers(); // returns false
 ```
 
 The package exposes [ordered maps](ordered-maps.md)
@@ -27,7 +27,7 @@ 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;
 - tell whether the container contains or not members with the `hasMembers` methods from the `Container` interface;
-- to access the members using the methods exposed by the `ArrayAccess`. **WARNING: Updating using `ArrayAccess` method is forbidden and will result in a `LogicException` being emitted.**;
+- access the members using the methods exposed by the `ArrayAccess`. **WARNING: Updating using `ArrayAccess` method is forbidden and will result in a `ForbiddenOperation` being emitted.**;
 
 getter methods:
 
@@ -36,5 +36,5 @@ getter methods:
 
 **Of note:**
 
-- All setter methods are returns a new instance with the applied changes.
+- All setter methods returns a new instance with the applied changes.
 - For setter methods, Item types are inferred using `Item::from` if a `Item` object is not provided.

docs/index.md

@@ -8,7 +8,7 @@ HTTP Structured Fields For PHP
 [![Total Downloads](https://img.shields.io/packagist/dt/bakame/http-structured-fields.svg?style=flat-square)](https://packagist.org/packages/bakame/http-structured-fields)
 [![Sponsor development of this project](https://img.shields.io/badge/sponsor%20this%20package-%E2%9D%A4-ff69b4.svg?style=flat-square)](https://github.com/sponsors/nyamsprod)
 
-The package uses value objects to parse, serialize and build [HTTP Structured Fields][1] in PHP.
+The package uses value objects to parse, serialize, build and update [HTTP Structured Fields][1] in PHP.
 
 HTTP Structured fields are intended for use by specifications of new HTTP fields that wish to 
 use a common syntax that is more restrictive than traditional HTTP field values or could
@@ -23,9 +23,10 @@ The package can be used to:
 use Bakame\Http\StructuredFields\Item;
 
 $field = Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
-echo $field->toHttpValue();                   // display "/terms";rel="copyright";anchor="#foo"
-echo $field->value();                         // display "/terms"
-echo $field->parameters->get('rel')->value(); // display "copyright"
+echo $field->toHttpValue();                // display "/terms";rel="copyright";anchor="#foo"
+echo $field;                               // display "/terms";rel="copyright";anchor="#foo"
+echo $field->value();                      // display "/terms"
+echo $field->parameters()['rel']->value(); // display "copyright"
 ```
 
 System Requirements
@@ -47,15 +48,6 @@ or download the library and:
 - use any other [PSR-4](https://www.php-fig.org/psr/psr-4/) compatible autoloader.
 - use the bundle autoloader script as shown below:
 
-~~~php
-require 'path/to/http-structured-fields/repo/autoload.php';
-
-use Bakame\Http\StructuredFields\OrderedList;
-
-$list = OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
-echo $list->get(-1)->value(); // returns '/member/*/comments'
-~~~
-
 Documentation
 ------------
 

docs/item.md

@@ -55,13 +55,30 @@ To instantiate the class you are required to use the `ByteSequence::fromDecoded`
 named constructors. The class also exposes the complementary public methods `ByteSequence::decoded`,
 `ByteSequence::encoded` to enable the correct textual representation.
 
+### Date
+
+The Date data type is a special integer as defined in the RFC to represent date as timestamp.
+They are represented in the package using PHP's `DateTimeImmutable` object. But the package
+supports any `DateTimeInterface` object as long as they are conforming to the RFC supported date range.
+
+```php
+use Bakame\Http\StructuredFields\Item;
+
+$date1 = Item::from(new DateTime('today'));
+$date2 = Item::from(new DateTimeImmutable('today'));
+
+$date1->value() == $date2->value();
+//in both cases the `value` method returns a DateTimeImmutable object.
+
+Item::from(new DateTimeImmutable('@'.PHP_INT_MAX)); // will throw
+```
+
 ## Usages
 
 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\Item;
@@ -71,10 +88,9 @@ $item->value(); // returns "hello world"
 $item->type();  // returns Type::String
 $item->parameters()['a']->value(); //returns true
 ```
-
 Instantiation via type recognition is done using the `Item::from` named constructor.
 
-- The first argument represents one of the six (6) item type value;
+- The first argument represents one of the supported type value;
 - 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;
 
@@ -96,8 +112,8 @@ $item = Item::fromPair([
         ["a", ByteSequence::fromDecoded("Hello World")],
     ]
 ]);
-$item->value(); // returns "hello world"
-$item->type();  // returns Type::String
+$item->value();                    // returns "hello world"
+$item->type();                     // returns Type::String
 $item->parameters()["a"]->type();  // returns Type::ByteSequence
 $item->parameters()["a"]->value(); // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
 echo $item->toHttpValue();         // returns "hello world";a=:SGVsbG8gV29ybGQ=:
@@ -106,13 +122,13 @@ echo $item->toHttpValue();         // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 `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;
+- The first member on index `0` represents one of the supported 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:
 
-- the method `Item::value` which returns the instance underlying value fully decoded;
+- the method `Item::type` which returns the instance type via the `Type` enum;
+- the method `Item::value` which returns the instance underlying value;
 - the method `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 ```php

docs/lists.md

@@ -17,7 +17,7 @@ Both classes expose the following:
 named constructors:
 
 - `fromList` instantiates the container with a list of members in an iterable construct;
-- `new` instantiates the container with a list of members as variadic;
+- `from` instantiates the container with a list of members as variadic;
 
 setter methods
 
@@ -27,6 +27,8 @@ setter methods
 - `replace` to replace an element at a given position in the list;
 - `remove` to remove elements based on their position;
 
+**All container classes are immutable so change will only be applied on the new instance.**
+
 In addition to `StructuredField` specific interfaces, both classes implements:
 
 - PHP `Countable` interface.
@@ -42,15 +44,19 @@ use Bakame\Http\StructuredFields\Token;
 $innerList = InnerList::fromList([42, 42.0, "42"], ["a" => true]);
 $innerList->has(2); //return true
 $innerList->has(42); //return false
-$innerList->push(Token::fromString('forty-two'));
-$innerList->remove(0, 2);
-echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
 
-$orderedList = OrderedList::from(
+$newList = $innerList
+    ->push(Token::fromString('forty-two'));
+    ->remove(0, 2);
+    
+echo $innerList;              //returns '(42 42.0 "42");a'
+echo $newList->toHttpValue(); //returns '(42.0 forty-two);a'
+
+$list = OrderedList::from(
     Item::from("42", ["foo" => "bar"]), 
-    $innerList
+    $newList
 );
-echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
+echo $list->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
 ```
 
 **if you try to set a key which does not exist an exception will be
@@ -62,7 +68,15 @@ your logic**
 use Bakame\Http\StructuredFields\OrderedList;
 use Bakame\Http\StructuredFields\Token;
 
-$innerList = OrderedList::fromList([42, 42.0]);
-$innerList->insert(2, Token::fromString('forty-two')); // will throw
-echo $innerList->toHttpValue(), PHP_EOL;
+$list = OrderedList::fromList([42, 42.0]);
+$list->insert(2, Token::fromString('forty-two')); // will throw
+```
+
+**Updating using `ArrayAccess` methods is forbidden and will result in a `ForbiddenOperation` being emitted.**
+
+```php
+use Bakame\Http\StructuredFields\OrderedList;
+
+$list = OrderedList::fromList([42, 42.0]);
+$list[0] = false; // will throw a ForbiddenOperation exception
 ```

docs/ordered-maps.md

@@ -26,6 +26,8 @@ getter methods:
 
 setter methods:
 
+**All container classes are immutable so change will only be applied on the new instance.**
+
 - `add` add an element at the end of the container if the key is new otherwise only the value is updated;
 - `append` always add an element at the end of the container, if already present the previous value is removed;
 - `prepend` always add an element at the beginning of the container, if already present the previous value is removed;
@@ -66,9 +68,9 @@ In addition to `StructuredField` specific interfaces, both classes implements:
 use Bakame\Http\StructuredFields\Parameters;
 
 $parameters = Parameters::fromAssociative(['b' => true, 'foo' => 'bar']);
-$parameters->keys();            // returns ['b', 'foo']
-$parameters->get('b');          // returns Item::from(true)
-$parameters->get('b')->value(); // returns true
+$parameters->keys();       // returns ['b', 'foo']
+$parameters->get('b');     // returns Item::from(true)
+$parameters['b']->value(); // returns 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(
@@ -79,3 +81,12 @@ $parameters->toHttpValue(); // returns ;b="false";foo="foo"
 ```
 
 **Both classes support negative indexes.**
+
+**Updating using `ArrayAccess` methods is forbidden and will result in a `ForbiddenOperation` being emitted.**
+
+```php
+use Bakame\Http\StructuredFields\Dictionary;
+
+$container = Dictionary::create();
+$container['zero'] = false; // will throw a ForbiddenOperation exception
+```