1<?php
2
3declare(strict_types=1);
4
5/*
6 * This file is part of the league/commonmark package.
7 *
8 * (c) Colin O'Dell <colinodell@gmail.com>
9 *
10 * Original code based on the CommonMark JS reference parser (https://bitly.com/commonmark-js)
11 *  - (c) John MacFarlane
12 *
13 * For the full copyright and license information, please view the LICENSE
14 * file that was distributed with this source code.
15 */
16
17namespace League\CommonMark\Util;
18
19use League\CommonMark\Exception\InvalidArgumentException;
20use League\CommonMark\Extension\CommonMark\Node\Block\HtmlBlock;
21
22/**
23 * Provides regular expressions and utilities for parsing Markdown
24 *
25 * All of the PARTIAL_ regex constants assume that they'll be used in case-insensitive searches
26 * All other complete regexes provided by this class (either via constants or methods) will have case-insensitivity enabled.
27 *
28 * @phpcs:disable Generic.Strings.UnnecessaryStringConcat.Found
29 *
30 * @psalm-immutable
31 */
32final class RegexHelper
33{
34    // Partial regular expressions (wrap with `/` on each side and add the case-insensitive `i` flag before use)
35    public const PARTIAL_ENTITY                = '&(?:#x[a-f0-9]{1,6}|#[0-9]{1,7}|[a-z][a-z0-9]{1,31});';
36    public const PARTIAL_ESCAPABLE             = '[!"#$%&\'()*+,.\/:;<=>?@[\\\\\]^_`{|}~-]';
37    public const PARTIAL_ESCAPED_CHAR          = '\\\\' . self::PARTIAL_ESCAPABLE;
38    public const PARTIAL_IN_DOUBLE_QUOTES      = '"(' . self::PARTIAL_ESCAPED_CHAR . '|[^"\x00])*"';
39    public const PARTIAL_IN_SINGLE_QUOTES      = '\'(' . self::PARTIAL_ESCAPED_CHAR . '|[^\'\x00])*\'';
40    public const PARTIAL_IN_PARENS             = '\\((' . self::PARTIAL_ESCAPED_CHAR . '|[^)\x00])*\\)';
41    public const PARTIAL_REG_CHAR              = '[^\\\\()\x00-\x20]';
42    public const PARTIAL_IN_PARENS_NOSP        = '\((' . self::PARTIAL_REG_CHAR . '|' . self::PARTIAL_ESCAPED_CHAR . '|\\\\)*\)';
43    public const PARTIAL_TAGNAME               = '[a-z][a-z0-9-]*';
44    public const PARTIAL_BLOCKTAGNAME          = '(?:address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h1|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|section|source|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)';
45    public const PARTIAL_ATTRIBUTENAME         = '[a-z_:][a-z0-9:._-]*';
46    public const PARTIAL_UNQUOTEDVALUE         = '[^"\'=<>`\x00-\x20]+';
47    public const PARTIAL_SINGLEQUOTEDVALUE     = '\'[^\']*\'';
48    public const PARTIAL_DOUBLEQUOTEDVALUE     = '"[^"]*"';
49    public const PARTIAL_ATTRIBUTEVALUE        = '(?:' . self::PARTIAL_UNQUOTEDVALUE . '|' . self::PARTIAL_SINGLEQUOTEDVALUE . '|' . self::PARTIAL_DOUBLEQUOTEDVALUE . ')';
50    public const PARTIAL_ATTRIBUTEVALUESPEC    = '(?:' . '\s*=' . '\s*' . self::PARTIAL_ATTRIBUTEVALUE . ')';
51    public const PARTIAL_ATTRIBUTE             = '(?:' . '\s+' . self::PARTIAL_ATTRIBUTENAME . self::PARTIAL_ATTRIBUTEVALUESPEC . '?)';
52    public const PARTIAL_OPENTAG               = '<' . self::PARTIAL_TAGNAME . self::PARTIAL_ATTRIBUTE . '*' . '\s*\/?>';
53    public const PARTIAL_CLOSETAG              = '<\/' . self::PARTIAL_TAGNAME . '\s*[>]';
54    public const PARTIAL_OPENBLOCKTAG          = '<' . self::PARTIAL_BLOCKTAGNAME . self::PARTIAL_ATTRIBUTE . '*' . '\s*\/?>';
55    public const PARTIAL_CLOSEBLOCKTAG         = '<\/' . self::PARTIAL_BLOCKTAGNAME . '\s*[>]';
56    public const PARTIAL_HTMLCOMMENT           = '<!---->|<!--(?:-?[^>-])(?:-?[^-])*-->';
57    public const PARTIAL_PROCESSINGINSTRUCTION = '[<][?][\s\S]*?[?][>]';
58    public const PARTIAL_DECLARATION           = '<![A-Z]+' . '\s+[^>]*>';
59    public const PARTIAL_CDATA                 = '<!\[CDATA\[[\s\S]*?]\]>';
60    public const PARTIAL_HTMLTAG               = '(?:' . self::PARTIAL_OPENTAG . '|' . self::PARTIAL_CLOSETAG . '|' . self::PARTIAL_HTMLCOMMENT . '|' .
61        self::PARTIAL_PROCESSINGINSTRUCTION . '|' . self::PARTIAL_DECLARATION . '|' . self::PARTIAL_CDATA . ')';
62    public const PARTIAL_HTMLBLOCKOPEN         = '<(?:' . self::PARTIAL_BLOCKTAGNAME . '(?:[\s\/>]|$)' . '|' .
63        '\/' . self::PARTIAL_BLOCKTAGNAME . '(?:[\s>]|$)' . '|' . '[?!])';
64    public const PARTIAL_LINK_TITLE            = '^(?:"(' . self::PARTIAL_ESCAPED_CHAR . '|[^"\x00])*"' .
65        '|' . '\'(' . self::PARTIAL_ESCAPED_CHAR . '|[^\'\x00])*\'' .
66        '|' . '\((' . self::PARTIAL_ESCAPED_CHAR . '|[^()\x00])*\))';
67
68    public const REGEX_PUNCTUATION        = '/^[\x{2000}-\x{206F}\x{2E00}-\x{2E7F}\p{Pc}\p{Pd}\p{Pe}\p{Pf}\p{Pi}\p{Po}\p{Ps}\\\\\'!"#\$%&\(\)\*\+,\-\.\\/:;<=>\?@\[\]\^_`\{\|\}~]/u';
69    public const REGEX_UNSAFE_PROTOCOL    = '/^javascript:|vbscript:|file:|data:/i';
70    public const REGEX_SAFE_DATA_PROTOCOL = '/^data:image\/(?:png|gif|jpeg|webp)/i';
71    public const REGEX_NON_SPACE          = '/[^ \t\f\v\r\n]/';
72
73    public const REGEX_WHITESPACE_CHAR         = '/^[ \t\n\x0b\x0c\x0d]/';
74    public const REGEX_UNICODE_WHITESPACE_CHAR = '/^\pZ|\s/u';
75    public const REGEX_THEMATIC_BREAK          = '/^(?:\*[ \t]*){3,}$|^(?:_[ \t]*){3,}$|^(?:-[ \t]*){3,}$/';
76    public const REGEX_LINK_DESTINATION_BRACES = '/^(?:<(?:[^<>\\n\\\\\\x00]|\\\\.)*>)/';
77
78    /**
79     * @psalm-pure
80     */
81    public static function isEscapable(string $character): bool
82    {
83        return \preg_match('/' . self::PARTIAL_ESCAPABLE . '/', $character) === 1;
84    }
85
86    /**
87     * @psalm-pure
88     */
89    public static function isLetter(?string $character): bool
90    {
91        if ($character === null) {
92            return false;
93        }
94
95        return \preg_match('/[\pL]/u', $character) === 1;
96    }
97
98    /**
99     * Attempt to match a regex in string s at offset offset
100     *
101     * @psalm-param non-empty-string $regex
102     *
103     * @return int|null Index of match, or null
104     *
105     * @psalm-pure
106     */
107    public static function matchAt(string $regex, string $string, int $offset = 0): ?int
108    {
109        $matches = [];
110        $string  = \mb_substr($string, $offset, null, 'UTF-8');
111        if (! \preg_match($regex, $string, $matches, \PREG_OFFSET_CAPTURE)) {
112            return null;
113        }
114
115        // PREG_OFFSET_CAPTURE always returns the byte offset, not the char offset, which is annoying
116        $charPos = \mb_strlen(\mb_strcut($string, 0, $matches[0][1], 'UTF-8'), 'UTF-8');
117
118        return $offset + $charPos;
119    }
120
121    /**
122     * Functional wrapper around preg_match_all which only returns the first set of matches
123     *
124     * @psalm-param non-empty-string $pattern
125     *
126     * @return string[]|null
127     *
128     * @psalm-pure
129     */
130    public static function matchFirst(string $pattern, string $subject, int $offset = 0): ?array
131    {
132        if ($offset !== 0) {
133            $subject = \substr($subject, $offset);
134        }
135
136        \preg_match_all($pattern, $subject, $matches, \PREG_SET_ORDER);
137
138        if ($matches === []) {
139            return null;
140        }
141
142        return $matches[0] ?: null;
143    }
144
145    /**
146     * Replace backslash escapes with literal characters
147     *
148     * @psalm-pure
149     */
150    public static function unescape(string $string): string
151    {
152        $allEscapedChar = '/\\\\(' . self::PARTIAL_ESCAPABLE . ')/';
153
154        $escaped = \preg_replace($allEscapedChar, '$1', $string);
155        \assert(\is_string($escaped));
156
157        return \preg_replace_callback('/' . self::PARTIAL_ENTITY . '/i', static fn ($e) => Html5EntityDecoder::decode($e[0]), $escaped);
158    }
159
160    /**
161     * @internal
162     *
163     * @param int $type HTML block type
164     *
165     * @psalm-param HtmlBlock::TYPE_* $type
166     *
167     * @phpstan-param HtmlBlock::TYPE_* $type
168     *
169     * @psalm-return non-empty-string
170     *
171     * @throws InvalidArgumentException if an invalid type is given
172     *
173     * @psalm-pure
174     */
175    public static function getHtmlBlockOpenRegex(int $type): string
176    {
177        switch ($type) {
178            case HtmlBlock::TYPE_1_CODE_CONTAINER:
179                return '/^<(?:script|pre|textarea|style)(?:\s|>|$)/i';
180            case HtmlBlock::TYPE_2_COMMENT:
181                return '/^<!--/';
182            case HtmlBlock::TYPE_3:
183                return '/^<[?]/';
184            case HtmlBlock::TYPE_4:
185                return '/^<![A-Z]/i';
186            case HtmlBlock::TYPE_5_CDATA:
187                return '/^<!\[CDATA\[/i';
188            case HtmlBlock::TYPE_6_BLOCK_ELEMENT:
189                return '%^<[/]?(?:address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[123456]|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|section|source|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)(?:\s|[/]?[>]|$)%i';
190            case HtmlBlock::TYPE_7_MISC_ELEMENT:
191                return '/^(?:' . self::PARTIAL_OPENTAG . '|' . self::PARTIAL_CLOSETAG . ')\\s*$/i';
192            default:
193                throw new InvalidArgumentException('Invalid HTML block type');
194        }
195    }
196
197    /**
198     * @internal
199     *
200     * @param int $type HTML block type
201     *
202     * @psalm-param HtmlBlock::TYPE_* $type
203     *
204     * @phpstan-param HtmlBlock::TYPE_* $type
205     *
206     * @psalm-return non-empty-string
207     *
208     * @throws InvalidArgumentException if an invalid type is given
209     *
210     * @psalm-pure
211     */
212    public static function getHtmlBlockCloseRegex(int $type): string
213    {
214        switch ($type) {
215            case HtmlBlock::TYPE_1_CODE_CONTAINER:
216                return '%<\/(?:script|pre|textarea|style)>%i';
217            case HtmlBlock::TYPE_2_COMMENT:
218                return '/-->/';
219            case HtmlBlock::TYPE_3:
220                return '/\?>/';
221            case HtmlBlock::TYPE_4:
222                return '/>/';
223            case HtmlBlock::TYPE_5_CDATA:
224                return '/\]\]>/';
225            default:
226                throw new InvalidArgumentException('Invalid HTML block type');
227        }
228    }
229
230    /**
231     * @psalm-pure
232     */
233    public static function isLinkPotentiallyUnsafe(string $url): bool
234    {
235        return \preg_match(self::REGEX_UNSAFE_PROTOCOL, $url) !== 0 && \preg_match(self::REGEX_SAFE_DATA_PROTOCOL, $url) === 0;
236    }
237}
238