File Toolkit/Console/Format/Formatter.php

1:	<?php declare(strict_types=1);
2:
3:	namespace Salient\Console\Format;
4:
5:	use Salient\Console\HasConsoleRegex;
6:	use Salient\Contract\Console\Format\FormatInterface;
7:	use Salient\Contract\Console\Format\FormatterInterface;
8:	use Salient\Contract\Console\Format\MessageFormatInterface;
9:	use Salient\Contract\Console\ConsoleInterface as Console;
10:	use Salient\Core\Concern\ImmutableTrait;
11:	use Salient\Utility\Exception\ShouldNotHappenException;
12:	use Salient\Utility\Regex;
13:	use Salient\Utility\Str;
14:	use Closure;
15:	use LogicException;
16:
17:	/**
18:	* @api
19:	*/
20:	class Formatter implements FormatterInterface, HasConsoleRegex
21:	{
22:	use ImmutableTrait;
23:
24:	public const DEFAULT_LEVEL_PREFIX_MAP = [
25:	Console::LEVEL_EMERGENCY => '! ',
26:	Console::LEVEL_ALERT => '! ',
27:	Console::LEVEL_CRITICAL => '! ',
28:	Console::LEVEL_ERROR => '! ',
29:	Console::LEVEL_WARNING => '^ ',
30:	Console::LEVEL_NOTICE => '> ',
31:	Console::LEVEL_INFO => '- ',
32:	Console::LEVEL_DEBUG => ': ',
33:	];
34:
35:	public const DEFAULT_TYPE_PREFIX_MAP = [
36:	Console::TYPE_PROGRESS => '⠿ ', // U+283F
37:	Console::TYPE_GROUP_START => '» ', // U+00BB
38:	Console::TYPE_GROUP_END => '« ', // U+00AB
39:	Console::TYPE_SUMMARY => '» ', // U+00BB
40:	Console::TYPE_SUCCESS => '✔ ', // U+2714
41:	Console::TYPE_FAILURE => '✘ ', // U+2718
42:	];
43:
44:	/**
45:	* @link https://github.com/sindresorhus/cli-spinners
46:	*
47:	* @var list<string>
48:	*/
49:	protected const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
50:
51:	private const TAG_MAP = [
52:	'___' => self::TAG_HEADING,
53:	'***' => self::TAG_HEADING,
54:	'##' => self::TAG_HEADING,
55:	'__' => self::TAG_BOLD,
56:	'**' => self::TAG_BOLD,
57:	'_' => self::TAG_ITALIC,
58:	'*' => self::TAG_ITALIC,
59:	'<' => self::TAG_UNDERLINE,
60:	'~~' => self::TAG_LOW_PRIORITY,
61:	];
62:
63:	private static self $NullFormatter;
64:	private static TagFormats $NullTagFormats;
65:	private static MessageFormats $NullMessageFormats;
66:	private static TagFormats $LoopbackTagFormats;
67:	private TagFormats $TagFormats;
68:	private MessageFormats $MessageFormats;
69:	/** @var Closure(): (int\|null) */
70:	private Closure $WidthCallback;
71:	/** @var array<Console::LEVEL_,string> /
72:	private array $LevelPrefixMap;
73:	/** @var array<Console::TYPE_,string> /
74:	private array $TypePrefixMap;
75:	/** @var array{int<0,max>,float\|null} */
76:	private array $SpinnerState;
77:
78:	/**
79:	* @api
80:	*
81:	* @param (Closure(): (int\|null))\|null $widthCallback
82:	* @param array<Console::LEVEL_*,string> $levelPrefixMap
83:	* @param array<Console::TYPE_*,string> $typePrefixMap
84:	*/
85:	public function __construct(
86:	?TagFormats $tagFormats = null,
87:	?MessageFormats $messageFormats = null,
88:	?Closure $widthCallback = null,
89:	array $levelPrefixMap = Formatter::DEFAULT_LEVEL_PREFIX_MAP,
90:	array $typePrefixMap = Formatter::DEFAULT_TYPE_PREFIX_MAP
91:	) {
92:	$this->TagFormats = $tagFormats ?? self::getNullTagFormats();
93:	$this->MessageFormats = $messageFormats ?? self::getNullMessageFormats();
94:	$this->WidthCallback = $widthCallback ?? fn() => null;
95:	$this->LevelPrefixMap = $levelPrefixMap;
96:	$this->TypePrefixMap = $typePrefixMap;
97:	$spinnerState = [0, null];
98:	$this->SpinnerState = &$spinnerState;
99:	}
100:
101:	/**
102:	* @inheritDoc
103:	*/
104:	public function removesEscapes(): bool
105:	{
106:	return $this->TagFormats->removesEscapes();
107:	}
108:
109:	/**
110:	* @inheritDoc
111:	*/
112:	public function wrapsAfterFormatting(): bool
113:	{
114:	return $this->TagFormats->wrapsAfterFormatting();
115:	}
116:
117:	/**
118:	* @inheritDoc
119:	*/
120:	public function withRemoveEscapes(bool $remove = true)
121:	{
122:	return $this->with('TagFormats', $this->TagFormats->withRemoveEscapes($remove));
123:	}
124:
125:	/**
126:	* @inheritDoc
127:	*/
128:	public function withWrapAfterFormatting(bool $value = true)
129:	{
130:	return $this->with('TagFormats', $this->TagFormats->withWrapAfterFormatting($value));
131:	}
132:
133:	/**
134:	* @inheritDoc
135:	*/
136:	public function getTagFormat(int $tag): FormatInterface
137:	{
138:	return $this->TagFormats->getFormat($tag);
139:	}
140:
141:	/**
142:	* @inheritDoc
143:	*/
144:	public function getMessageFormat(
145:	int $level,
146:	int $type = Console::TYPE_STANDARD
147:	): MessageFormatInterface {
148:	return $this->MessageFormats->getFormat($level, $type);
149:	}
150:
151:	/**
152:	* @inheritDoc
153:	*/
154:	public function getMessagePrefix(
155:	int $level,
156:	int $type = Console::TYPE_STANDARD
157:	): string {
158:	if (
159:	$type === Console::TYPE_UNDECORATED
160:	\|\| $type === Console::TYPE_UNFORMATTED
161:	) {
162:	return '';
163:	}
164:
165:	if ($type === Console::TYPE_PROGRESS) {
166:	$now = (float) (hrtime(true) / 1000);
167:	if ($this->SpinnerState[1] === null) {
168:	$this->SpinnerState[1] = $now;
169:	} elseif ($now - $this->SpinnerState[1] >= 80000) {
170:	$this->SpinnerState[0]++;
171:	$this->SpinnerState[0] %= count(static::SPINNER_FRAMES);
172:	$this->SpinnerState[1] = $now;
173:	}
174:	$prefix = static::SPINNER_FRAMES[$this->SpinnerState[0]] . ' ';
175:	}
176:
177:	return $prefix
178:	?? $this->TypePrefixMap[$type]
179:	?? $this->LevelPrefixMap[$level]
180:	?? '';
181:	}
182:
183:	/**
184:	* @inheritDoc
185:	*/
186:	public function format(
187:	string $string,
188:	bool $unwrap = false,
189:	$wrapTo = null,
190:	bool $unformat = false,
191:	string $break = "\n"
192:	): string {
193:	if ($string === '' \|\| $string === "\r") {
194:	return $string;
195:	}
196:
197:	// [ [ Offset, length, replacement ], ... ]
198:	/** @var array<array{int,int,string}> */
199:	$replace = [];
200:	$append = '';
201:	$removeEscapes = $this->removesEscapes();
202:	$wrapAfterFormatting = $this->wrapsAfterFormatting();
203:	$wrapFormats = $wrapAfterFormatting
204:	? $this->TagFormats
205:	: self::getNullTagFormats();
206:	$formats = $unformat
207:	? self::getLoopbackTagFormats()
208:	: $this->TagFormats;
209:
210:	// Preserve trailing carriage returns
211:	if ($string[-1] === "\r") {
212:	$append .= "\r";
213:	$string = substr($string, 0, -1);
214:	}
215:
216:	// Normalise line endings and split the string into text, code blocks
217:	// and code spans
218:	if (!Regex::matchAll(
219:	self::FORMAT_REGEX,
220:	Str::setEol($string),
221:	$matches,
222:	\PREG_SET_ORDER \| \PREG_UNMATCHED_AS_NULL,
223:	)) {
224:	throw new ShouldNotHappenException(sprintf(
225:	'Unable to parse: %s',
226:	$string,
227:	));
228:	}
229:
230:	$string = '';
231:	foreach ($matches as $match) {
232:	$indent = (string) $match['indent'];
233:
234:	if ($match['breaks'] !== null) {
235:	$breaks = $match['breaks'];
236:	if ($unwrap && strpos($breaks, "\n") !== false) {
237:	/** @var string */
238:	$breaks = substr(Str::unwrap(".$breaks.", "\n", false, true, true), 1, -1);
239:	}
240:	$string .= $indent . $breaks;
241:	continue;
242:	}
243:
244:	// Treat unmatched backticks as text
245:	if ($match['extra'] !== null) {
246:	$string .= $indent . $match['extra'];
247:	continue;
248:	}
249:
250:	$baseOffset = strlen($string . $indent);
251:
252:	if ($match['text'] !== null) {
253:	$text = $match['text'];
254:	if ($unwrap && strpos($text, "\n") !== false) {
255:	/** @var string */
256:	$text = substr(Str::unwrap(".$text.", "\n", false, true, true), 1, -1);
257:	}
258:
259:	$adjust = 0;
260:	$text = Regex::replaceCallback(
261:	self::TAG_REGEX,
262:	function ($matches) use (
263:	&$replace,
264:	$wrapFormats,
265:	$formats,
266:	$baseOffset,
267:	&$adjust
268:	): string {
269:	$text = $this->applyTags(
270:	$matches,
271:	true,
272:	$wrapFormats->removesEscapes(),
273:	$wrapFormats,
274:	);
275:	$placeholder = Regex::replace('/[^ ]/u', 'x', $text);
276:	$formatted = $wrapFormats === $formats
277:	? $text
278:	: $this->applyTags(
279:	$matches,
280:	true,
281:	$formats->removesEscapes(),
282:	$formats,
283:	);
284:	$replace[] = [
285:	$baseOffset + $matches[0][1] + $adjust,
286:	strlen($placeholder),
287:	$formatted,
288:	];
289:	$adjust += strlen($placeholder) - strlen($matches[0][0]);
290:	return $placeholder;
291:	},
292:	$text,
293:	-1,
294:	$count,
295:	\PREG_OFFSET_CAPTURE,
296:	);
297:
298:	$string .= $indent . $text;
299:	continue;
300:	}
301:
302:	if ($match['block'] !== null) {
303:	// Reinstate unwrapped newlines before blocks
304:	if ($unwrap && $string !== '' && $string[-1] !== "\n") {
305:	$string[-1] = "\n";
306:	}
307:
308:	/** @var array{fence:string,infostring:string,block:string} $match */
309:	$formatted = $formats->apply(
310:	$match['block'],
311:	new TagAttributes(
312:	self::TAG_CODE_BLOCK,
313:	$match['fence'],
314:	0,
315:	false,
316:	$indent,
317:	Str::coalesce(trim($match['infostring']), null),
318:	)
319:	);
320:	$placeholder = '?';
321:	$replace[] = [
322:	$baseOffset,
323:	1,
324:	$formatted,
325:	];
326:
327:	$string .= $indent . $placeholder;
328:	continue;
329:	}
330:
331:	if ($match['span'] !== null) {
332:	/** @var array{backtickstring:string,span:string} $match */
333:	$span = $match['span'];
334:	// As per CommonMark:
335:	// - Convert line endings to spaces
336:	// - If the string begins and ends with a space but doesn't
337:	// consist entirely of spaces, remove both
338:	$span = Regex::replace(
339:	'/^ ((?> [^ ]+).) $/u',
340:	'$1',
341:	strtr($span, "\n", ' '),
342:	);
343:	$attributes = new TagAttributes(
344:	self::TAG_CODE_SPAN,
345:	$match['backtickstring'],
346:	);
347:	$text = $wrapFormats->apply($span, $attributes);
348:	$placeholder = Regex::replace('/[^ ]/u', 'x', $text);
349:	$formatted = $wrapFormats === $formats
350:	? $text
351:	: $formats->apply($span, $attributes);
352:	$replace[] = [
353:	$baseOffset,
354:	strlen($placeholder),
355:	$formatted,
356:	];
357:
358:	$string .= $indent . $placeholder;
359:	continue;
360:	}
361:	}
362:
363:	// Remove backslash escapes and adjust the offsets of any subsequent
364:	// replacement strings
365:	$replacements = count($replace);
366:	$adjustable = [];
367:	foreach ($replace as $i => [$offset]) {
368:	$adjustable[$i] = $offset;
369:	}
370:	$adjust = 0;
371:	$string = Regex::replaceCallback(
372:	self::ESCAPE_REGEX,
373:	function ($matches) use (
374:	$unformat,
375:	$removeEscapes,
376:	$wrapAfterFormatting,
377:	&$replace,
378:	&$adjustable,
379:	&$adjust
380:	): string {
381:	// If the escape character is being wrapped, do nothing other
382:	// than temporarily replace "\ " with "\x"
383:	if ($wrapAfterFormatting && !$removeEscapes) {
384:	if ($matches[1][0] !== ' ') {
385:	return $matches[0][0];
386:	}
387:	$placeholder = '\x';
388:	$replace[] = [$matches[0][1] + $adjust, 2, $matches[0][0]];
389:	return $placeholder;
390:	}
391:
392:	$delta = strlen($matches[1][0]) - strlen($matches[0][0]);
393:	foreach ($adjustable as $i => $offset) {
394:	if ($offset < $matches[0][1]) {
395:	continue;
396:	}
397:	$replace[$i][0] += $delta;
398:	}
399:
400:	$placeholder = null;
401:	if ($matches[1][0] === ' ') {
402:	$placeholder = 'x';
403:	}
404:
405:	if ($unformat \|\| !$removeEscapes \|\| $placeholder !== null) {
406:	// Use `$replace` to reinstate the escape after wrapping
407:	$replace[] = [
408:	$matches[0][1] + $adjust,
409:	strlen($matches[1][0]),
410:	$unformat \|\| !$removeEscapes ? $matches[0][0] : $matches[1][0],
411:	];
412:	}
413:
414:	$adjust += $delta;
415:
416:	return $placeholder ?? $matches[1][0];
417:	},
418:	$string,
419:	-1,
420:	$count,
421:	\PREG_OFFSET_CAPTURE
422:	);
423:
424:	if (is_array($wrapTo)) {
425:	for ($i = 0; $i < 2; $i++) {
426:	if ($wrapTo[$i] <= 0) {
427:	$width ??= ($this->WidthCallback)();
428:	if ($width === null) {
429:	$wrapTo = null;
430:	break;
431:	}
432:	$wrapTo[$i] = max(0, $wrapTo[$i] + $width);
433:	}
434:	}
435:	} elseif (is_int($wrapTo) && $wrapTo <= 0) {
436:	$width = ($this->WidthCallback)();
437:	$wrapTo = $width === null
438:	? null
439:	: max(0, $wrapTo + $width);
440:	}
441:	if ($wrapTo !== null) {
442:	if ($break === "\n") {
443:	$string = Str::wrap($string, $wrapTo);
444:	} else {
445:	// Only replace new line breaks with `$break`
446:	$wrapped = Str::wrap($string, $wrapTo);
447:	$length = strlen($wrapped);
448:	for ($i = 0; $i < $length; $i++) {
449:	if ($wrapped[$i] === "\n" && $string[$i] !== "\n") {
450:	$replace[] = [$i, 1, $break];
451:	}
452:	}
453:	}
454:	}
455:
456:	// Get `$replace` in reverse offset order, sorting from scratch if any
457:	// substitutions were made in the callbacks above
458:	if (count($replace) !== $replacements) {
459:	usort($replace, fn($a, $b) => $b[0] <=> $a[0]);
460:	} else {
461:	$replace = array_reverse($replace);
462:	}
463:
464:	foreach ($replace as [$offset, $length, $replacement]) {
465:	$string = substr_replace($string, $replacement, $offset, $length);
466:	}
467:
468:	return $string . $append;
469:	}
470:
471:	/**
472:	* @param array<int\|string,array{string,int}\|string> $matches
473:	*/
474:	private function applyTags(
475:	array $matches,
476:	bool $matchesHasOffset,
477:	bool $unescape,
478:	TagFormats $formats,
479:	int $depth = 0
480:	): string {
481:	/** @var string */
482:	$text = $matchesHasOffset ? $matches['text'][0] : $matches['text'];
483:	/** @var string */
484:	$tag = $matchesHasOffset ? $matches['tag'][0] : $matches['tag'];
485:
486:	$text = Regex::replaceCallback(
487:	self::TAG_REGEX,
488:	fn($matches) =>
489:	$this->applyTags($matches, false, $unescape, $formats, $depth + 1),
490:	$text,
491:	-1,
492:	$count,
493:	);
494:
495:	if ($unescape) {
496:	$text = Regex::replace(self::ESCAPE_REGEX, '$1', $text);
497:	}
498:
499:	$tagId = self::TAG_MAP[$tag] ?? null;
500:	if ($tagId === null) {
501:	throw new LogicException(sprintf('Invalid tag: %s', $tag));
502:	}
503:
504:	return $formats->apply(
505:	$text,
506:	new TagAttributes($tagId, $tag, $depth, (bool) $count),
507:	);
508:	}
509:
510:	/**
511:	* @inheritDoc
512:	*/
513:	public function formatDiff(string $diff): string
514:	{
515:	$formats = [
516:	'---' => $this->TagFormats->getFormat(self::TAG_DIFF_HEADER),
517:	'+++' => $this->TagFormats->getFormat(self::TAG_DIFF_HEADER),
518:	'@' => $this->TagFormats->getFormat(self::TAG_DIFF_RANGE),
519:	'+' => $this->TagFormats->getFormat(self::TAG_DIFF_ADDITION),
520:	'-' => $this->TagFormats->getFormat(self::TAG_DIFF_REMOVAL),
521:	];
522:
523:	$attributes = [
524:	'---' => new TagAttributes(self::TAG_DIFF_HEADER, '---'),
525:	'+++' => new TagAttributes(self::TAG_DIFF_HEADER, '+++'),
526:	'@' => new TagAttributes(self::TAG_DIFF_RANGE, '@'),
527:	'+' => new TagAttributes(self::TAG_DIFF_ADDITION, '+'),
528:	'-' => new TagAttributes(self::TAG_DIFF_REMOVAL, '-'),
529:	];
530:
531:	return Regex::replaceCallback(
532:	'/^(-{3}\|\+{3}\|[-+@]).*/m',
533:	fn($matches) =>
534:	$formats[$matches[1]]->apply($matches[0], $attributes[$matches[1]]),
535:	$diff,
536:	);
537:	}
538:
539:	/**
540:	* @inheritDoc
541:	*/
542:	public function formatMessage(
543:	string $msg1,
544:	?string $msg2 = null,
545:	int $level = Console::LEVEL_INFO,
546:	int $type = Console::TYPE_STANDARD
547:	): string {
548:	$attributes = new MessageAttributes($level, $type);
549:
550:	if ($type === Console::TYPE_UNFORMATTED) {
551:	$formats = self::getNullMessageFormats();
552:	$prefix = '';
553:	} else {
554:	$formats = $this->MessageFormats;
555:	$prefix = $this->getMessagePrefix($level, $type);
556:	}
557:
558:	return $formats
559:	->getFormat($level, $type)
560:	->apply($msg1, $msg2, $prefix, $attributes);
561:	}
562:
563:	/**
564:	* @internal
565:	*/
566:	public static function getNullFormatter(): self
567:	{
568:	return self::$NullFormatter ??= new self();
569:	}
570:
571:	private static function getNullTagFormats(): TagFormats
572:	{
573:	return self::$NullTagFormats ??= new TagFormats();
574:	}
575:
576:	private static function getNullMessageFormats(): MessageFormats
577:	{
578:	return self::$NullMessageFormats ??= new MessageFormats();
579:	}
580:
581:	private static function getLoopbackTagFormats(): TagFormats
582:	{
583:	return self::$LoopbackTagFormats ??= LoopbackFormat::getFormatter()->TagFormats;
584:	}
585:	}
586:

Namespaces

Classes