class FrontMatter

class FrontMatter {
    
    /**
     * The separator used to indicate front matter data.
     *
     * @var string
     */
    const SEPARATOR = '---';
    
    /**
     * The regular expression used to extract the YAML front matter content.
     *
     * @var string
     */
    const REGEXP = '/\\A(' . self::SEPARATOR . '(.*?)?\\R' . self::SEPARATOR . ')(\\R.*)?\\Z/s';
    
    /**
     * The parsed source.
     *
     * @var array
     */
    protected $parsed;
    
    /**
     * A serializer.
     *
     * @var string
     */
    protected $serializer;
    
    /**
     * The source.
     *
     * @var string
     */
    protected $source;
    
    /**
     * FrontMatter constructor.
     *
     * @param string $source
     *   A string source.
     * @param string $serializer
     *   The name of a class that implements
     *   \Drupal\Component\Serialization\SerializationInterface.
     */
    public function __construct(string $source, string $serializer = '\\Drupal\\Component\\Serialization\\Yaml') {
        assert(is_subclass_of($serializer, SerializationInterface::class), sprintf('The $serializer parameter must reference a class that implements %s.', SerializationInterface::class));
        $this->serializer = $serializer;
        $this->source = $source;
    }
    
    /**
     * Creates a new FrontMatter instance.
     *
     * @param string $source
     *   A string source.
     * @param string $serializer
     *   The name of a class that implements
     *   \Drupal\Component\Serialization\SerializationInterface.
     *
     * @return static
     */
    public static function create(string $source, string $serializer = '\\Drupal\\Component\\Serialization\\Yaml') {
        return new static($source, $serializer);
    }
    
    /**
     * Parses the source.
     *
     * @return array
     *   An associative array containing:
     *   - content: The real content.
     *   - data: The front matter data extracted and decoded.
     *   - line: The line number where the real content starts.
     *
     * @throws \Drupal\Component\FrontMatter\Exception\FrontMatterParseException
     */
    protected function parse() : array {
        if (!$this->parsed) {
            $content = $this->source;
            $data = [];
            $line = 1;
            // Parse front matter data.
            if (preg_match(static::REGEXP, $content, $matches)) {
                // Extract the source content.
                $content = !empty($matches[3]) ? trim($matches[3]) : '';
                // Extract the front matter data and typecast to an array to ensure
                // top level scalars are in an array.
                $raw = !empty($matches[2]) ? trim($matches[2]) : '';
                if ($raw) {
                    try {
                        $data = (array) $this->serializer::decode($raw);
                    } catch (InvalidDataTypeException $exception) {
                        // Rethrow a specific front matter parse exception.
                        throw new FrontMatterParseException($exception);
                    }
                }
                // Determine the real source line by counting all newlines in the first
                // match (which includes the front matter separators) and append a new
                // line to denote that the content should start after it.
                if (!empty($matches[1])) {
                    $line += preg_match_all('/\\R/', $matches[1] . "\n");
                }
            }
            // Set the parsed data.
            $this->parsed = [
                'content' => $content,
                'data' => $data,
                'line' => $line,
            ];
        }
        return $this->parsed;
    }
    
    /**
     * Retrieves the extracted source content.
     *
     * @return string
     *   The extracted source content.
     *
     * @throws \Drupal\Component\FrontMatter\Exception\FrontMatterParseException
     */
    public function getContent() : string {
        return $this->parse()['content'];
    }
    
    /**
     * Retrieves the extracted front matter data.
     *
     * @return array
     *   The extracted front matter data.
     *
     * @throws \Drupal\Component\FrontMatter\Exception\FrontMatterParseException
     */
    public function getData() : array {
        return $this->parse()['data'];
    }
    
    /**
     * Retrieves the line where the source content starts, after any data.
     *
     * @return int
     *   The source content line.
     *
     * @throws \Drupal\Component\FrontMatter\Exception\FrontMatterParseException
     */
    public function getLine() : int {
        return $this->parse()['line'];
    }

}