add fail core function

docs/api.md

@@ -72,7 +72,7 @@ $success = $parser("foo bar");
 $fail = $parser("foobar");
 ```
 
-### `end`
+## `end`
 
 This will check to see if we are at the end of input. Success means there is nothing left to parse.
 
@@ -94,6 +94,18 @@ $success = $parser("foo");
 $failure = $parser("foobar");
 ```
 
+## `fail`
+
+Always fails.
+
+#### OOP and FP
+
+```php
+$parser = p::fail();
+
+assert(null === $parser("foo"));
+```
+
 ## `fold`
 
 Similar to `array_reduce`, this function can be used to combine values. For example, you might want to turn the array `["1","2","3"]` into the integer `123`.
@@ -128,7 +140,7 @@ $parser = p::fold(
 assert(["flowers"] === $parser("flowerflower"));
 ```
 
-### `lit`
+## `lit`
 
 Checks to see if the unparsed data starts with the *lit*eral.
 
@@ -141,7 +153,7 @@ $success = $parser("foobar");
 $fail = $parser("bar");
 ```
 
-### `map`
+## `map`
 
 This is used to convert raw data to more useful types. For example you might wish to convert a string containing an integer into an actual integer.
 
@@ -167,7 +179,7 @@ $parser = p::map(function (string $s): bool {
 assert([true] == $parser("yes")->parsed);
 ```
 
-### `not`
+## `not`
 
 Fails if the given parser is successful. Succeeds if not.
 
@@ -181,7 +193,7 @@ assert([] === $parser("bar")->parsed);
 assert("bar" === $parser("bar")->unparsed);
 ```
 
-### `or`
+## `or`
 
 Tries a list of parsers in order until one succeeds.
 

src/Functions.php

@@ -12,6 +12,7 @@ final class Functions
     const drop = self::class . "::drop";
     const end = self::class . "::end";
     const eol = self::class . "::eol";
+    const fail = self::class . "::fail";
     const float = self::class . "::float";
     const fold = self::class . "::fold";
     const hex = self::class . "::hex";
@@ -122,6 +123,16 @@ public static function eol(): callable
         return self::or(self::lit("\n"), self::lit("\r\n"), self::lit("\r"));
     }
 
+    /**
+     * @return callable(string):null
+     */
+    public static function fail(): callable
+    {
+        return function (string $s): ?r {
+            return null;
+        };
+    }
+
     /**
      * @return callable(string):?r<float>
      */

src/Oop.php

@@ -10,6 +10,7 @@ final class Oop
     //convenience constants for passing functions to functions
     const binary = self::class . "::binary";
     const eol = self::class . "::eol";
+    const fail = self::class . "::fail";
     const float = self::class . "::float";
     const hex = self::class . "::hex";
     const int = self::class . "::int";
@@ -69,6 +70,11 @@ public static function eol(): self
         return new self(p::eol());
     }
 
+    public static function fail(): self
+    {
+        return new self(p::fail());
+    }
+
     public static function float(): self
     {
         return new self(p::float());

test/Unit/FunctionsTest.php

@@ -113,6 +113,13 @@ public function test_eol(string $input, ?r $expected): void
         self::assertEquals($expected, $p($input));
     }
 
+    public function test_fail(): void
+    {
+        $parser = p::fail();
+
+        self::assertEquals(null, $parser("foo"));
+    }
+
     public function float_provider(): array
     {
         return [

test/Unit/OopTest.php

@@ -107,6 +107,13 @@ public function testEol(string $input, ?r $expected): void
         self::assertEquals($expected, $p($input));
     }
 
+    public function testFail(): void
+    {
+        $parser = p::fail();
+
+        self::assertEquals(null, $parser("foo"));
+    }
+
     public function floatProvider(): array
     {
         return [