Merge branch 'develop'

* develop: (25 commits)
  specify next release
  update documentation link
  move fold doc
  move state doc
  fix links
  move validation doc
  move either doc
  move maybe doc
  move regexp doc
  move str doc
  move map doc
  rearrange methods by groups
  move set doc
  flag methods that load data into memory
  rearrange methods by groups
  move sequence doc
  move structures section to its own chapter
  hide navigation
  fix list
  update monoids
  ...

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: ci
+on:
+  push:
+    branches: [master]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,2 +1,3 @@
 composer.lock
 vendor
+.cache

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 5.5.0 - 2024-06-02
+
+### Changed
+
+- A lazy `Sequence::takeEnd()` no longer loads the whole sequence in memory, only the number of elements taken + 1.
+
 ## 5.4.0 - 2024-05-29
 
 ### Added

Makefile

@@ -0,0 +1,6 @@
+# This command is intended to be run on your computer
+serve-doc:
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+
+build-doc:
+	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

README.md

@@ -6,7 +6,7 @@
 
 A set of classes to wrap PHP primitives to build immutable data.
 
-[Documentation](docs/README.md)
+[Documentation](https://innmind.github.io/Immutable/)
 
 ## Installation
 

docs/MONOIDS.md

@@ -1,10 +1,17 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Monoids
 
 Monoids describe a way to combine two values of a given type. A monoid contains an identity value that when combined with another value doesn't change its value. The combine operation has to be associative meaning `combine(a, combine(b, c))` is the same as `combine(combine(a, b), c)`.
 
 A simple monoid is an addition because adding `0` (the identity value) to any other integer won't change the value and `add(1, add(2, 3))` is the the same result as `add(add(1, 2), 3)` (both return 6).
 
 This library comes with a few monoids:
+
 - `Innmind\Immutable\Monoid\Concat` to append 2 instances of `Innmind\Immutable\Str` together
 - `Innmind\Immutable\Monoid\Append` to append 2 instances of `Innmind\Immutable\Sequence` together
 - `Innmind\Immutable\Monoid\MergeSet` to append 2 instances of `Innmind\Immutable\Set` together
@@ -38,3 +45,5 @@ return static function() {
     }
 };
 ```
+
+You can take a look at the [proofs](https://github.com/Innmind/Immutable/tree/master/proofs/monoid) for this package monoids to better understand how thiw works.

docs/PHILOSOPHY.md

@@ -1,6 +1,13 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Philosophy
 
 This project was born after working with other programming languages (like [Scala](https://scala-lang.org)) and discovering [functional programming](https://en.wikipedia.org/wiki/Functional_programming). This taught me 2 things:
+
 - higher order functions on data structures
 - immutability
 

docs/README.md

@@ -1,3 +1,9 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Getting Started
 
 This project brings a set of immutable data structure to bring a uniformity on how to handle data.
@@ -9,31 +15,3 @@ Before diving in the documentation you may want to read about the [philosophy](P
 ```sh
 composer require innmind/immutable
 ```
-
-## Structures
-
-This library provides the 10 following structures:
-
-- [`Sequence`](SEQUENCE.md)
-- [`Set`](SET.md)
-- [`Map`](MAP.md)
-- [`Str`](STR.md)
-- [`RegExp`](REGEXP.md)
-- [`Maybe`](MAYBE.md)
-- [`Either`](EITHER.md)
-- [`Validation`](VALIDATION.md)
-- [`State`](STATE.md)
-- [`Fold`](FOLD.md)
-
-See the documentation for each structure to understand how to use them.
-
-All structures are typed with [`vimeo/psalm`](https://psalm.dev), you must use it in order to verify that you use this library correctly.
-
-## Use cases
-
-- [How to read a file](LAZY_FILE.md)
-- [Parsing strings](PARSING.md)
-
-## Testing
-
-This package provides sets that can be used with [BlackBox](BLACKBOX.md).

docs/assets/stylesheets/extra.css

@@ -0,0 +1,113 @@
+@font-face {
+  font-family: "Monaspace Neon";
+  font-weight: normal;
+  font-style: normal;
+  src: url("../fonts/MonaspaceNeon-Regular.woff");
+}
+
+:root {
+  --md-code-font: "Monaspace Neon";
+}
+
+:root {
+  --light-md-code-hl-number-color: #f76d47;
+  --light-md-code-hl-function-color: #6384b9;
+  --light-md-code-hl-operator-color: #39adb5;
+  --light-md-code-hl-constant-color: #7c4dff;
+  --light-md-code-hl-string-color: #9fc06f;
+  --light-md-code-hl-punctuation-color: #39adb5;
+  --light-md-code-hl-keyword-color: #7c4dff;
+  --light-md-code-hl-variable-color: #80cbc4;
+  --light-md-code-hl-comment-color: #ccd7da;
+  --light-md-code-bg-color: #fafafa;
+  --light-md-code-fg-color: #ffb62c;
+  --light-md-code-hl-variable-color: #6384b9;
+  --dark-md-code-hl-number-color: #f78c6c;
+  --dark-md-code-hl-function-color: #82aaff;
+  --dark-md-code-hl-operator-color: #89ddff;
+  --dark-md-code-hl-constant-color: #c792ea;
+  --dark-md-code-hl-string-color: #c3e88d;
+  --dark-md-code-hl-punctuation-color: #89ddff;
+  --dark-md-code-hl-keyword-color: #c792ea;
+  --dark-md-code-hl-variable-color: #e8f9f9;
+  --dark-md-code-hl-comment-color: #546e7a;
+  --dark-md-code-bg-color: #263238;
+  --dark-md-code-fg-color: #ffcb6b;
+  --dark-md-code-hl-variable-color: #82aaff;
+}
+
+@media (prefers-color-scheme: light) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+    --md-code-bg-color: var(--light-md-code-bg-color);
+    --md-code-fg-color: var(--light-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php > * {
+  --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+  --md-code-bg-color: var(--light-md-code-bg-color);
+  --md-code-fg-color: var(--light-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php .na {
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+}
+
+@media (prefers-color-scheme: dark) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+    --md-code-bg-color: var(--dark-md-code-bg-color);
+    --md-code-fg-color: var(--dark-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php > * {
+  --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+  --md-code-bg-color: var(--dark-md-code-bg-color);
+  --md-code-fg-color: var(--dark-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php .na {
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+}

docs/EITHER.md → docs/structures/either.md

@@ -32,8 +32,8 @@ function accessResource(User $user): Either {
 }
 ```
 
-> **Note**
-> `ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
+!!! note ""
+    `ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
 
 ## `::left()`
 
@@ -43,8 +43,8 @@ This builds an `Either` instance with the given value in the left hand side.
 $either = Either::left($anyValue);
 ```
 
-> **Note**
-> usually this side is used for errors.
+!!! note ""
+    Usually this side is used for errors.
 
 ## `::right()`
 
@@ -54,8 +54,8 @@ This builds an `Either` instance with the given value in the right hand side.
 $either = Either::right($anyValue);
 ```
 
-> **Note**
-> usually this side is used for valid values.
+!!! note ""
+    Usually this side is used for valid values.
 
 ## `::defer()`
 
@@ -75,7 +75,8 @@ $either = Either::defer(static function() {
 
 Methods called (except `match`) on a deferred `Either` will not be called immediately but will be composed to be executed once you call `match`.
 
-> **Warning** this means that if you never call `match` on a deferred `Either` it will do nothing.
+!!! warning ""
+    This means that if you never call `match` on a deferred `Either` it will do nothing.
 
 ## `->map()`
 
@@ -85,7 +86,9 @@ This will apply the map transformation on the right value if there is one, other
 /** @var Either<Error, User> */
 $either = identify($serverRequest);
 /** @var Either<Error, Impersonated> */
-$impersonated = $either->map(fn(User $user): Impersonated => $user->impersonateAdmin());
+$impersonated = $either->map(
+    fn(User $user): Impersonated => $user->impersonateAdmin(),
+);
 ```
 
 ## `->flatMap()`
@@ -109,12 +112,14 @@ $response = identify($serverRequest)
     ->flatMap(fn(User $user): Either => accessResource($user))
     ->match(
         fn(Resource $resource) => new Response(200, $resource->toString()),
-        fn(Error $error) => new Response(400, $error->message()), // here the error can be from identify or from accessResource
+        fn(Error $error) => new Response(400, $error->message()), //(1)
     );
 ```
 
-> **Note**
-> `Response` is an imaginary class.
+1. Here the error can be from `identify` or from `accessResource`.
+
+!!! note ""
+    `Response` is an imaginary class.
 
 ## `->otherwise()`
 
@@ -148,11 +153,14 @@ identify($request)
         fn() => new Error('User is not allowed'),
     )
     ->match(
-        fn(User $user) => doSomething($user), // here we know the user is allowed
-        fn(Error $error) => print($error->message()), // can be "User not found" or "User is not allowed"
+        fn(User $user) => doSomething($user), //(1)
+        fn(Error $error) => print($error->message()), //(2)
     );
 ```
 
+1. Here we know the user is allowed.
+2. Can be "User not found" or "User is not allowed".
+
 ## `->leftMap()`
 
 This is similar to the `->map()` function but will be applied on the left value only.
@@ -165,7 +173,7 @@ $either = identify($request)
 
 ## `->maybe()`
 
-This returns a [`Maybe`](MAYBE.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
+This returns a [`Maybe`](maybe.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
 
 ```php
 Either::right('something')->maybe()->match(

docs/FOLD.md → docs/structures/fold.md

@@ -1,6 +1,6 @@
 # `Fold`
 
-The `Fold` monad is intented to work with _(infinte) stream of data_ by folding each element to a single value. This monad distinguishes between the type used to fold and the result type, this allows to inform the _stream_ that it's no longer necessary to extract elements as the folding is done.
+The `Fold` monad is intented to work with _(infinite) stream of data_ by folding each element to a single value. This monad distinguishes between the type used to fold and the result type, this allows to inform the _stream_ that it's no longer necessary to extract elements as the folding is done.
 
 An example is reading from a socket as it's an infinite stream of strings: