feat: 添加sentenceFull，支持保留其他字符 (#198)

* feat: 添加sentenceFull，支持保留其他字符

* feat: 添加sentenceFull，支持保留其他字符

README.md

@@ -71,6 +71,10 @@ echo Pinyin::sentence('带着希望去旅行，比到达终点更美好');
 // 去除声调
 echo Pinyin::sentence('带着希望去旅行，比到达终点更美好', 'none');
 // dai zhe xi wang qu lv xing ， bi dao da zhong dian geng mei hao
+
+// 保留所有其他字符
+echo Pinyin::sentenceFull('ル是片假名，π是希腊字母', 'none');
+// ル shi pian jia ming ，π shi xi la zi mu
 ```
 
 ### 生成用于链接的拼音字符串
@@ -223,7 +227,7 @@ php ./bin/pinyin --help
 # Options:
 #     -j, --json               输出 JSON 格式.
 #     -c, --compact            不格式化输出 JSON.
-#     -m, --method=[method]    转换方式，可选：sentence/permalink/abbr/nameAbbr/name/passportName/phrase/polyphones/chars.
+#     -m, --method=[method]    转换方式，可选：sentence/sentenceFull/permalink/abbr/nameAbbr/name/passportName/phrase/polyphones/chars.
 #     --no-tone                不使用音调.
 #     --tone-style=[style]     音调风格，可选值：symbol/none/number, default: none.
 #     -h, --help               显示帮助.

bin/pinyin

@@ -15,7 +15,7 @@ Usage:
 Options:
     -j, --json               输出 JSON 格式.
     -c, --compact            不格式化输出 JSON.
-    -m, --method=[method]    转换方式，可选：sentence/permalink/abbr/nameAbbr/name/passportName/phrase/polyphones/chars.
+    -m, --method=[method]    转换方式，可选：sentence/sentenceFull/permalink/abbr/nameAbbr/name/passportName/phrase/polyphones/chars.
     --no-tone                不使用音调.
     --tone-style=[style]     音调风格，可选值：symbol/none/number, default: none.
     -h, --help               显示帮助.

phpunit.xml

@@ -1,17 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         backupGlobals="false"
+         backupStaticProperties="false"
          bootstrap="vendor/autoload.php"
          colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
+
          processIsolation="false"
-         stopOnFailure="false">
-    <testsuites>
-        <testsuite name="overtrue/pinyin Test Suite (All PHP version)">
-            <directory>./tests/</directory>
-            <exclude>./tests/*.php</exclude>
-        </testsuite>
-    </testsuites>
+         stopOnFailure="false"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.4/phpunit.xsd"
+         cacheDirectory=".phpunit.result.cache"
+         >
+  <testsuites>
+    <testsuite name="overtrue/pinyin Test Suite (All PHP version)">
+      <directory>./tests/</directory>
+      <exclude>./tests/*.php</exclude>
+    </testsuite>
+  </testsuites>
 </phpunit>

src/Collection.php

@@ -56,7 +56,7 @@ public function offsetGet(mixed $offset): mixed
 
     public function offsetSet(mixed $offset, mixed $value): void
     {
-        if (null === $offset) {
+        if ($offset === null) {
             $this->items[] = $value;
         } else {
             $this->items[$offset] = $value;

src/Converter.php

@@ -26,6 +26,8 @@ class Converter
 
     protected bool $noWords = false;
 
+    protected bool $keepOtherCharacters = false;
+
     protected string $yuTo = 'v';
 
     protected string $toneStyle = self::TONE_STYLE_SYMBOL;
@@ -77,6 +79,13 @@ public function noWords(): static
         return $this;
     }
 
+    public function keepOtherCharacters(): static
+    {
+        $this->keepOtherCharacters = true;
+
+        return $this;
+    }
+
     public function onlyHans(): static
     {
         // 中文汉字不含符号
@@ -165,7 +174,9 @@ public function convert(string $string, callable $beforeSplit = null): Collectio
         }, $string);
 
         // 过滤掉不保留的字符
-        $string = \preg_replace(\sprintf('~[^%s]~u', \implode($this->regexps)), '', $string);
+        if (! $this->keepOtherCharacters) {
+            $string = \preg_replace(\sprintf('~[^%s]~u', \implode($this->regexps)), '', $string);
+        }
 
         // 多音字
         if ($this->polyphonic) {

src/Pinyin.php

@@ -41,6 +41,11 @@ public static function sentence(string $string, string $toneStyle = Converter::T
         return self::withToneStyle($toneStyle)->convert($string);
     }
 
+    public static function sentenceFull(string $string, string $toneStyle = Converter::TONE_STYLE_SYMBOL): Collection
+    {
+        return self::keepOtherCharacters()->withToneStyle($toneStyle)->convert($string);
+    }
+
     public static function polyphones(string $string, string $toneStyle = Converter::TONE_STYLE_SYMBOL, bool $asList = false): Collection
     {
         return self::polyphonic($asList)->withToneStyle($toneStyle)->convert($string);

tests/PinyinTest.php

@@ -268,6 +268,11 @@ public function test_sentence()
         $this->assertPinyin('java gōng chéng shī', Pinyin::sentence('java工程师'));
     }
 
+    public function test_sentenceFull()
+    {
+        $this->assertPinyin('ル shì piàn jiǎ míng ，π shì xī là zì mǔ', Pinyin::sentenceFull('ル是片假名，π是希腊字母'));
+    }
+
     public function test_issues()
     {
         $this->assertPinyin('ā lè tài', Pinyin::sentence('阿勒泰'));

tests/benchmark.php

@@ -3,6 +3,7 @@
 require __DIR__.'/../vendor/autoload.php';
 
 use Overtrue\Pinyin\Pinyin;
+
 use function Termwind\{render};
 
 $totalStart = microtime(true);