From 3727c4e1af12b9e4a8811c182ec21dc437fdc9da Mon Sep 17 00:00:00 2001 From: Iurii Rogulia Date: Sat, 19 Sep 2026 19:41:18 +0300 Subject: [PATCH 1/2] Add the narrowNbsp option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements spec 1.3.0's nbsp.md 3.1a (polytypo/polytypo@3a2355d, canonical issue #31), porting polytypo-js@964db2d. `narrowNbsp: 'nbsp'` makes the engine emit U+00A0 everywhere it would emit U+202F — the narrow no-break space many common faces do not carry, where a browser falls back mid-line and a PDF renderer with no fallback drops the glyph. It rewrites the rule's target rather than post-processing the output, and a test shows why that distinction is the whole feature: str_replace over the default output produces the same text and is not a fixed point — feed it back through transform() and N2 converts it straight back. The option is resolved once at the call boundary into a code point (Engine\NarrowTarget) and reaches the rules as RuleContext::$narrowTarget, so no rule sees the option's string. CODE_INVALID_OPTION is the eighth error code, general to every option added from 1.3.0 on. Validation order is mode -> narrowNbsp -> rules -> locale -> dialect, and the check runs whether or not `nbsp` is enabled — it belongs to the call, so `rules: ['nbsp' => false]` does not suppress it. All four precedence pairs are in one test. The conformance runner now carries the case's own options into the idempotency re-run, which spec 1.3.0 made contract: a case with narrowNbsp is a fixed point under that option and not under the defaults. This runner named its arguments on each call rather than reusing one value, so all three call sites gained the argument explicitly. Verified beyond the suite: all 1226 runnable text/html canonical fixture cases at spec 1.3.0 pass and are idempotent against this build. 1148 tests, 2974 assertions; PHPStan level 8 and phpcs clean. Co-Authored-By: Claude Opus 5 --- src/Engine/NarrowTarget.php | 42 +++++++++++ src/Engine/RuleContext.php | 6 ++ src/Engine/Rules/NbspRule.php | 14 ++-- src/Polytypo.php | 53 +++++++++++--- src/PolytypoException.php | 3 + tests/ConformanceTest.php | 11 ++- tests/NarrowNbspTest.php | 134 ++++++++++++++++++++++++++++++++++ 7 files changed, 243 insertions(+), 20 deletions(-) create mode 100644 src/Engine/NarrowTarget.php create mode 100644 tests/NarrowNbspTest.php diff --git a/src/Engine/NarrowTarget.php b/src/Engine/NarrowTarget.php new file mode 100644 index 0000000..bb22434 --- /dev/null +++ b/src/Engine/NarrowTarget.php @@ -0,0 +1,42 @@ + $localeData * @return array */ - private static function prepare(array $localeData): array + private static function prepare(array $localeData, int $narrowTarget = 0x202F): array { $data = $localeData['nbsp']; @@ -248,7 +248,7 @@ private static function prepare(array $localeData): array continue; } - $target = $pair['innerSpace'] === 'nbsp' ? self::NBSP : self::NNBSP; + $target = $pair['innerSpace'] === 'nbsp' ? self::NBSP : $narrowTarget; $quotePairs[] = ['open' => $openCp, 'close' => $closeCp, 'target' => $target]; } @@ -929,11 +929,15 @@ private static function forwardBindingSubRule( */ public static function scan(array $cp, array $localeData, RuleContext $ctx): array { - $prep = self::prepare($localeData); + $prep = self::prepare($localeData, $ctx->narrowTarget); $claims = array_fill(0, count($cp) + 1, null); - self::punctuationSubRule($cp, $prep, $claims, $prep['beforePunctuation'], self::NBSP, self::NNBSP); // N1 - self::punctuationSubRule($cp, $prep, $claims, $prep['narrowBeforePunctuation'], self::NNBSP, self::NBSP); // N2 + self::punctuationSubRule($cp, $prep, $claims, $prep['beforePunctuation'], self::NBSP, self::NNBSP); // N1 + // N2's target is NARROW-TARGET (nbsp.md 3.1a); the last argument is the NOBREAK member + // that is not the target, which is what the sub-rule converts. With the substitution on, + // N2 and N1 want the same character -- never different ones. + $narrowOther = $ctx->narrowTarget === self::NBSP ? self::NNBSP : self::NBSP; + self::punctuationSubRule($cp, $prep, $claims, $prep['narrowBeforePunctuation'], $ctx->narrowTarget, $narrowOther); // N2 self::shortWordsSubRule($cp, $prep, $claims); // N3 self::abbreviationsSubRule($cp, $prep, $claims); // N4 self::unitsSubRule($cp, $prep, $claims); // N5 diff --git a/src/Polytypo.php b/src/Polytypo.php index ed42cb6..6b1adda 100644 --- a/src/Polytypo.php +++ b/src/Polytypo.php @@ -5,6 +5,7 @@ namespace Polytypo; use Polytypo\Engine\Codepoints; +use Polytypo\Engine\NarrowTarget; use Polytypo\Engine\Pipeline; use Polytypo\Engine\RuleContext; use Polytypo\Modes\Html; @@ -44,12 +45,14 @@ public static function transform( string $mode = 'text', ?string $dialect = null, ?array $rules = null, + ?string $narrowNbsp = null, ): string { $resolvedMode = self::resolveMode($mode); + $narrowTarget = NarrowTarget::resolve($narrowNbsp); return match ($resolvedMode) { - 'text' => self::transformText($input, $locale, $dialect, $rules), - 'html' => self::transformHtml($input, $locale, $dialect, $rules), + 'text' => self::transformText($input, $locale, $dialect, $rules, $narrowTarget), + 'html' => self::transformHtml($input, $locale, $dialect, $rules, $narrowTarget), // 'markdown': no dialect is implemented by this runtime (verified this session: // league/commonmark gives no position data at all on inline text nodes, and no other // maintained PHP CommonMark/GFM library with the needed raw-extent span property @@ -82,12 +85,14 @@ public static function analyze( string $mode = 'text', ?string $dialect = null, ?array $rules = null, + ?string $narrowNbsp = null, ): array { $resolvedMode = self::resolveMode($mode); + $narrowTarget = NarrowTarget::resolve($narrowNbsp); return match ($resolvedMode) { - 'text' => self::analyzeText($input, $locale, $dialect, $rules), - 'html' => self::analyzeHtml($input, $locale, $dialect, $rules), + 'text' => self::analyzeText($input, $locale, $dialect, $rules, $narrowTarget), + 'html' => self::analyzeHtml($input, $locale, $dialect, $rules, $narrowTarget), // 'markdown': not implemented by this runtime, exactly as for transform() -- A1 // requires analyze() to reject what transform() rejects, with the same code. default => self::transformMarkdown($input, $locale, $dialect, $rules), @@ -107,7 +112,13 @@ private static function resolveMode(string $mode): string } /** @param array|null $rules */ - private static function transformText(string $input, string $locale, ?string $dialect, ?array $rules): string + private static function transformText( + string $input, + string $locale, + ?string $dialect, + ?array $rules, + int $narrowTarget, + ): string { if ($dialect !== null) { throw new PolytypoException( @@ -117,14 +128,20 @@ private static function transformText(string $input, string $locale, ?string $di } [, $localeData, $plan] = Pipeline::prepare($locale, $rules); $cp = Codepoints::toCodepoints($input); - $ctx = new RuleContext(mode: 'text', dialect: null, locale: $locale); + $ctx = new RuleContext(mode: 'text', dialect: null, locale: $locale, narrowTarget: $narrowTarget); $result = Pipeline::runRules($cp, $plan, $localeData, $ctx); return Codepoints::fromCodepoints($result); } /** @param array|null $rules */ - private static function transformHtml(string $input, string $locale, ?string $dialect, ?array $rules): string + private static function transformHtml( + string $input, + string $locale, + ?string $dialect, + ?array $rules, + int $narrowTarget, + ): string { if ($dialect !== null) { throw new PolytypoException( @@ -134,7 +151,7 @@ private static function transformHtml(string $input, string $locale, ?string $di } [$resolvedLocale, $localeData, $plan] = Pipeline::prepare($locale, $rules); $spans = Html::htmlSpans($input); - $ctx = new RuleContext(mode: 'html', dialect: null, locale: $resolvedLocale); + $ctx = new RuleContext(mode: 'html', dialect: null, locale: $resolvedLocale, narrowTarget: $narrowTarget); $cp = Codepoints::toCodepoints($input); return Runner::runOverSpans($cp, $spans, $plan, $localeData, $ctx); @@ -163,7 +180,13 @@ private static function transformMarkdown(string $input, string $locale, ?string * @param array|null $rules * @return Change[] */ - private static function analyzeText(string $input, string $locale, ?string $dialect, ?array $rules): array + private static function analyzeText( + string $input, + string $locale, + ?string $dialect, + ?array $rules, + int $narrowTarget, + ): array { if ($dialect !== null) { throw new PolytypoException( @@ -173,7 +196,7 @@ private static function analyzeText(string $input, string $locale, ?string $dial } [, $localeData, $plan] = Pipeline::prepare($locale, $rules); $cp = Codepoints::toCodepoints($input); - $ctx = new RuleContext(mode: 'text', dialect: null, locale: $locale); + $ctx = new RuleContext(mode: 'text', dialect: null, locale: $locale, narrowTarget: $narrowTarget); return Pipeline::runRulesRecording($cp, $plan, $localeData, $ctx, array_keys($cp), count($cp)); } @@ -182,7 +205,13 @@ private static function analyzeText(string $input, string $locale, ?string $dial * @param array|null $rules * @return Change[] */ - private static function analyzeHtml(string $input, string $locale, ?string $dialect, ?array $rules): array + private static function analyzeHtml( + string $input, + string $locale, + ?string $dialect, + ?array $rules, + int $narrowTarget, + ): array { if ($dialect !== null) { throw new PolytypoException( @@ -192,7 +221,7 @@ private static function analyzeHtml(string $input, string $locale, ?string $dial } [$resolvedLocale, $localeData, $plan] = Pipeline::prepare($locale, $rules); $spans = Html::htmlSpans($input); - $ctx = new RuleContext(mode: 'html', dialect: null, locale: $resolvedLocale); + $ctx = new RuleContext(mode: 'html', dialect: null, locale: $resolvedLocale, narrowTarget: $narrowTarget); return Runner::analyzeOverSpans(Codepoints::toCodepoints($input), $spans, $plan, $localeData, $ctx); } diff --git a/src/PolytypoException.php b/src/PolytypoException.php index e81a896..4e2c75a 100644 --- a/src/PolytypoException.php +++ b/src/PolytypoException.php @@ -21,6 +21,9 @@ final class PolytypoException extends \RuntimeException public const CODE_MALFORMED_LOCALE_DATA = 'POLYTYPO_MALFORMED_LOCALE_DATA'; public const CODE_RULE_CONTRACT = 'POLYTYPO_RULE_CONTRACT'; public const CODE_MALFORMED_INPUT = 'POLYTYPO_MALFORMED_INPUT'; + // Spec 1.3.0. Deliberately general: every option added from 1.3.0 on shares this code, while + // `mode` and `dialect` keep their own because callers branch on them. + public const CODE_INVALID_OPTION = 'POLYTYPO_INVALID_OPTION'; private readonly string $errorCode; diff --git a/tests/ConformanceTest.php b/tests/ConformanceTest.php index 627e739..68ff72d 100644 --- a/tests/ConformanceTest.php +++ b/tests/ConformanceTest.php @@ -57,10 +57,15 @@ public function testFixture(string $file, array $case): void $locale = $case['locale']; $mode = $case['mode'] ?? 'text'; $rules = $case['rules'] ?? null; + // Spec 1.3.0's case-level option (nbsp.md 3.1a). It is passed on BOTH calls below: a + // case carrying it is a fixed point under its own options and not under the defaults, + // so carrying it into the idempotency re-run is contract (ARCHITECTURE.md 6.1), not + // convenience. + $narrowNbsp = $case['narrowNbsp'] ?? null; if (isset($case['throws'])) { try { - Polytypo::transform($case['in'], $locale, mode: $mode, rules: $rules); + Polytypo::transform($case['in'], $locale, mode: $mode, rules: $rules, narrowNbsp: $narrowNbsp); self::fail('expected ' . $case['throws'] . ' to be thrown'); } catch (PolytypoException $e) { self::assertSame($case['throws'], $e->getErrorCode()); @@ -70,11 +75,11 @@ public function testFixture(string $file, array $case): void } $expected = $case['out']; - $got = Polytypo::transform($case['in'], $locale, mode: $mode, rules: $rules); + $got = Polytypo::transform($case['in'], $locale, mode: $mode, rules: $rules, narrowNbsp: $narrowNbsp); self::assertSame($expected, $got, "out = " . self::escape($got) . ', want ' . self::escape($expected)); // Free coverage, and the most common port bug (ARCHITECTURE.md 6.1). - $twice = Polytypo::transform($expected, $locale, mode: $mode, rules: $rules); + $twice = Polytypo::transform($expected, $locale, mode: $mode, rules: $rules, narrowNbsp: $narrowNbsp); self::assertSame($expected, $twice, 'not idempotent: transform(out) = ' . self::escape($twice)); } diff --git a/tests/NarrowNbspTest.php b/tests/NarrowNbspTest.php new file mode 100644 index 0000000..5f7668e --- /dev/null +++ b/tests/NarrowNbspTest.php @@ -0,0 +1,134 @@ +assertSame("Un délai{$nn}? Vraiment{$nn}! Et puis{$nn}; voilà.", self::fr($input)); + $this->assertSame( + "Un délai{$nb}? Vraiment{$nb}! Et puis{$nb}; voilà.", + self::fr($input, 'nbsp'), + ); + } + + public function testNormalisesAnAuthoredNarrowSpaceAtAClaimedIndex(): void + { + $nb = self::NBSP; + $nn = self::NNBSP; + $this->assertSame("Oui{$nb}?", self::fr("Oui{$nn}?", 'nbsp')); + $this->assertSame("Oui{$nn}?", self::fr("Oui{$nn}?")); + // Elsewhere it is left alone: the option changes what is written, not which indices are + // claimed. + $this->assertSame("mot{$nn}mot", self::fr("mot{$nn}mot", 'nbsp')); + } + + public function testClaimsTheSameIndicesUnderTheSameGuards(): void + { + $nb = self::NBSP; + $this->assertSame("12:30 et http://x{$nb}; oui", self::fr('12:30 et http://x ; oui', 'nbsp')); + // N1 (the colon) and N8 (fr's primary pair, innerSpace "nbsp") already wrote U+00A0. + $this->assertSame( + "Il a dit{$nb}: «{$nb}oui{$nb}»{$nb}; puis{$nb}?", + self::fr('Il a dit : « oui » ; puis ?', 'nbsp'), + ); + } + + /** @return array */ + public static function localesWithoutNarrowSpaces(): array + { + return ['en-US' => ['en-US'], 'de-DE' => ['de-DE'], 'ru' => ['ru']]; + } + + #[DataProvider('localesWithoutNarrowSpaces')] + public function testIsANoOpWhereNothingEmitsANarrowSpace(string $locale): void + { + $input = 'She said “hi” — really...'; + $this->assertSame( + Polytypo::transform($input, $locale), + Polytypo::transform($input, $locale, narrowNbsp: 'nbsp'), + ); + } + + public function testIsAFixedPointUnderTheOption(): void + { + $nn = self::NNBSP; + foreach (['Un délai ? Vraiment !', "Oui{$nn}?", 'Il a dit : « oui » ;'] as $input) { + $once = self::fr($input, 'nbsp'); + $this->assertSame($once, self::fr($once, 'nbsp'), $input); + } + } + + public function testPostProcessingTheDefaultOutputIsNotAFixedPoint(): void + { + // Which is why the option moves the target instead: a caller's str_replace is stable + // only as long as it always runs. Feed it back through the default pipeline and N2 + // converts it straight back. + $nb = self::NBSP; + $nn = self::NNBSP; + $postProcessed = str_replace($nn, $nb, self::fr('Un délai ?')); + $this->assertSame("Un délai{$nb}?", $postProcessed); + $this->assertSame("Un délai{$nn}?", self::fr($postProcessed)); + } + + public function testValidationAndItsOrder(): void + { + $codeOf = static function (callable $run): string { + try { + $run(); + } catch (PolytypoException $e) { + return $e->getErrorCode(); + } + + return 'NO THROW'; + }; + + $this->assertSame( + PolytypoException::CODE_INVALID_OPTION, + $codeOf(static fn () => Polytypo::transform('x', 'fr', narrowNbsp: 'wide')), + ); + $this->assertSame( + PolytypoException::CODE_INVALID_MODE, + $codeOf(static fn () => Polytypo::transform('x', 'fr', 'yaml', narrowNbsp: 'wide')), + ); + $this->assertSame( + PolytypoException::CODE_INVALID_OPTION, + $codeOf(static fn () => Polytypo::transform('x', 'fr', rules: ['nope' => true], narrowNbsp: 'wide')), + ); + $this->assertSame( + PolytypoException::CODE_INVALID_OPTION, + $codeOf(static fn () => Polytypo::transform('x', 'xx', narrowNbsp: 'wide')), + ); + // The check belongs to the call, not to the rule. + $this->assertSame( + PolytypoException::CODE_INVALID_OPTION, + $codeOf(static fn () => Polytypo::transform('x', 'fr', rules: ['nbsp' => false], narrowNbsp: 'wide')), + ); + } + + public function testAcceptsTheExplicitDefault(): void + { + $nn = self::NNBSP; + $this->assertSame("Un délai{$nn}?", self::fr('Un délai ?', 'narrow')); + } +} From 3fe48fed1ab65ba8564d7ebb407e94151e326639 Mon Sep 17 00:00:00 2001 From: Iurii Rogulia Date: Sun, 20 Sep 2026 11:53:08 +0300 Subject: [PATCH 2/2] Keep the brace on the declaration line in transform helpers Co-Authored-By: Claude Opus 5 --- src/Polytypo.php | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/src/Polytypo.php b/src/Polytypo.php index 6b1adda..579dfda 100644 --- a/src/Polytypo.php +++ b/src/Polytypo.php @@ -118,8 +118,7 @@ private static function transformText( ?string $dialect, ?array $rules, int $narrowTarget, - ): string - { + ): string { if ($dialect !== null) { throw new PolytypoException( PolytypoException::CODE_INVALID_DIALECT, @@ -141,8 +140,7 @@ private static function transformHtml( ?string $dialect, ?array $rules, int $narrowTarget, - ): string - { + ): string { if ($dialect !== null) { throw new PolytypoException( PolytypoException::CODE_INVALID_DIALECT, @@ -186,8 +184,7 @@ private static function analyzeText( ?string $dialect, ?array $rules, int $narrowTarget, - ): array - { + ): array { if ($dialect !== null) { throw new PolytypoException( PolytypoException::CODE_INVALID_DIALECT, @@ -211,8 +208,7 @@ private static function analyzeHtml( ?string $dialect, ?array $rules, int $narrowTarget, - ): array - { + ): array { if ($dialect !== null) { throw new PolytypoException( PolytypoException::CODE_INVALID_DIALECT,