Adds mrkdwn text formatting helpers (#18)

README.md

@@ -215,42 +215,47 @@ $message = Message::fromArray($decodedMessageJson);
 $message = Message::fromJson($messageJson);
 ```
 
-## Supported Elements
-
-The following are supported elements from the Block Kit documentation:
-
-| **Type** | **Element**        | **Supported?** |
-|----------|--------------------|----------------|
-| Surface  | App Home           | ✅             |
-| Surface  | Message            | ✅             |
-| Surface  | Model              | ✅             |
-| Block    | Actions            | ✅             |
-| Block    | Checkboxes         | ✅             |
-| Block    | Context            | ✅             |
-| Block    | Divider            | ✅             |
-| Block    | File               | ✅             |
-| Block    | Header             | ✅             |
-| Block    | Image              | ✅             |
-| Block    | Input              | ✅             |
-| Block    | Section            | ✅             |
-| Input    | Button             | ✅️             |
-| Input    | Date Picker        | ✅             |
-| Input    | Multi-select Menus | ✅✅✅✅✅    |
-| Input    | Overflow Menu      | ✅             |
-| Input    | Plain Text Input   | ✅             |
-| Input    | Radio Buttons      | ✅             |
-| Input    | Select Menus       | ✅✅✅✅✅    |
-| Input    | Time Picker        | ✅             |
-| Partial  | Confirm Dialog     | ✅             |
-| Partial  | Mrkdwn Text        | ✅             |
-| Partial  | Fields             | ✅             |
-| Partial  | Option             | ✅             |
-| Partial  | Option Group       | ✅             |
-| Partial  | Plain Text         | ✅             |
-
-### Virtual Elements
-
-The following are virtual/custom elements composed of one or more blocks:
+### Message Formatting
+
+The `Formatter` class exists to provide helpers for formatting "mrkdwn" text. These helpers can be used so that you
+don't have to have the Slack mrkdwn syntax memorized. Also, these functions will properly escape `<`, `>`, and `&`
+characters automatically, if it's needed.
+
+Example:
+```php
+// Note: $event is meant to represent some kind of DTO from your own application.
+$fmt = Kit::formatter();
+$msg = Kit::newMessage()->text($fmt->sub(
+    'Hello, {audience}! On {date}, {host} will be hosting an AMA in the {channel} channel at {time}.',
+    [
+        'audience' => $fmt->atHere(),
+        'date'     => $fmt->date($event->timestamp),
+        'host'     => $fmt->user($event->hostId),
+        'channel'  => $fmt->channel($event->channelId),
+        'time'     => $fmt->time($event->timestamp),
+    ]
+));
+```
+
+Example Result:
+```json
+{
+	"blocks": [
+		{
+			"type": "section",
+			"text": {
+				"type": "mrkdwn",
+				"text": "Hello, <!here>! On <!date^1608322949^{date}|2020-12-18T20:22:29+00:00>, <@U12345678> will be hosting an AMA in the <#C12345678> channel at <!date^1608322949^{time}|2020-12-18T20:22:29+00:00>."
+			}
+		}
+	]
+}
+```
+
+## Virtual Elements
+
+In addition to the standard Block Kit elements, the following are virtual/custom elements composed of one or
+more blocks:
 
 * `TwoColumnTable` - Uses Sections with Fields to create a two-column table with an optional header.
 

composer.json

@@ -26,17 +26,22 @@
         }
     },
     "scripts": {
-        "gen-test": "php bin/gen-test.php",
         "stan": "phpstan analyse -c phpstan.neon",
         "style-fix": "phpcbf --standard=PSR12 src tests",
         "style-lint": "phpcs --standard=PSR12 src tests",
         "test": "phpunit --bootstrap=vendor/autoload.php --no-coverage tests",
+        "test-all":  [
+            "@style-lint",
+            "@stan",
+            "@test-coverage"
+        ],
         "test-ci": "phpunit --bootstrap=vendor/autoload.php --coverage-text --whitelist=src --do-not-cache-result tests",
         "test-coverage": [
             "phpunit --bootstrap=vendor/autoload.php --coverage-html=build/coverage --whitelist=src tests",
             "open build/coverage/index.html"
         ],
         "test-debug": "phpunit --bootstrap=vendor/autoload.php --no-coverage --debug tests",
-        "test-dox": "phpunit --bootstrap=vendor/autoload.php --no-coverage --testdox tests"
+        "test-dox": "phpunit --bootstrap=vendor/autoload.php --no-coverage --testdox tests",
+        "test-gen": "php bin/gen-test.php"
     }
 }

src/Blocks/Context.php

@@ -50,7 +50,7 @@ public function plainText(string $text, ?bool $emoji = null): self
         return $this->add(new PlainText($text, $emoji));
     }
 
-    public function mrkdwnText(string $text, bool $verbatim = false): self
+    public function mrkdwnText(string $text, ?bool $verbatim = null): self
     {
         return $this->add(new MrkdwnText($text, $verbatim));
     }

src/Blocks/Section.php

@@ -4,7 +4,15 @@
 
 namespace Jeremeamia\Slack\BlockKit\Blocks;
 
-use Jeremeamia\Slack\BlockKit\{Element, Exception, HydrationData, Inputs, Partials, Type};
+use Jeremeamia\Slack\BlockKit\{
+    Element,
+    Exception,
+    HydrationData,
+    Inputs,
+    Kit,
+    Partials,
+    Type,
+};
 
 class Section extends BlockElement
 {
@@ -83,10 +91,10 @@ public function plainText(string $text, ?bool $emoji = null): self
 
     /**
      * @param string $text
-     * @param bool $verbatim
+     * @param bool|null $verbatim
      * @return self
      */
-    public function mrkdwnText(string $text, bool $verbatim = false): self
+    public function mrkdwnText(string $text, ?bool $verbatim = null): self
     {
         return $this->setText(new Partials\MrkdwnText($text, $verbatim));
     }
@@ -97,7 +105,7 @@ public function mrkdwnText(string $text, bool $verbatim = false): self
      */
     public function code(string $code): self
     {
-        return $this->setText(new Partials\MrkdwnText("```\n{$code}\n```"));
+        return $this->setText(new Partials\MrkdwnText(Kit::formatter()->codeBlock($code), true));
     }
 
     /**

src/Config.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jeremeamia\Slack\BlockKit;
+
+/**
+ * Stores configuration settings.
+ */
+final class Config
+{
+    /** @var bool|null */
+    private $defaultVerbatimSetting = null;
+
+    /** @var bool|null */
+    private $defaultEmojiSetting = null;
+
+    public static function new(): self
+    {
+        return new self();
+    }
+
+    public function getDefaultVerbatimSetting(): ?bool
+    {
+        return $this->defaultVerbatimSetting;
+    }
+
+    public function setDefaultVerbatimSetting(?bool $verbatim): self
+    {
+        $this->defaultVerbatimSetting = $verbatim;
+
+        return $this;
+    }
+
+    public function getDefaultEmojiSetting(): ?bool
+    {
+        return $this->defaultEmojiSetting;
+    }
+
+    public function setDefaultEmojiSetting(?bool $emoji): self
+    {
+        $this->defaultEmojiSetting = $emoji;
+
+        return $this;
+    }
+}

src/Exception.php

@@ -7,6 +7,8 @@
 use RuntimeException;
 use Throwable;
 
+use function vsprintf;
+
 class Exception extends RuntimeException
 {
     public function __construct(string $message, array $args = [], Throwable $previous = null)