Skip to content

Commit 275df07

Browse files
vanderleevanderlee
authored
Merge pull request #58 from vanderlee/master_splitWords
Added splitWords and various code quality improvements
2 parents a8f336f + 44b4a7b commit 275df07

23 files changed

+1521
-272
lines changed

‎.github/workflows/tests.yml

+33-4
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414

1515
strategy:
1616
matrix:
17-
php: [ '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2' ]
17+
php: [ '5.6', '7.4', '8.2' ]
1818

1919
steps:
2020
- name: Checkout repository
@@ -28,14 +28,43 @@ jobs:
2828
with:
2929
php-version: ${{ matrix.php }}
3030

31-
- name: Install dependencies
32-
run: |
33-
composer install
31+
- name: Install dependencies (using the workflow cache)
32+
uses: ramsey/composer-install@v2
3433

3534
- name: Run tests
3635
run: |
3736
./vendor/bin/phpunit
3837
38+
api-documentation:
39+
name: 'Check API documentation'
40+
runs-on: ubuntu-latest
41+
42+
steps:
43+
- name: Checkout repository
44+
uses: actions/checkout@v3
45+
46+
- name: Setup PHP 7.4
47+
uses: shivammathur/setup-php@v2
48+
with:
49+
php-version: 7.4
50+
51+
- name: Prepare environment
52+
run: |
53+
composer dump-autoload --dev
54+
55+
- name: Check API documentation
56+
run: |
57+
LOG_LEVEL=4 ./build/generate-docs
58+
59+
if [ -n "$(git status --porcelain)" ]; then
60+
echo "The API documentation in README.md is NOT UP-TO-DATE."
61+
echo "Run './build/generate-docs' locally to update it."
62+
exit 1
63+
else
64+
echo "The API documentation in README.md is up-to-date."
65+
exit 0
66+
fi
67+
3968
# The coverage service on https://coveralls.io requires registration of this project
4069
# for receiving the coverage report.
4170
#

‎README.md

+111-56
Original file line numberDiff line numberDiff line change
@@ -38,94 +38,129 @@ echo $syllable->hyphenateText('Provide a plethora of paragraphs');
3838
The following is an incomplete list, containing only the most common methods.
3939
For a complete documentation of all classes, read the generated [PHPDoc](doc).
4040

41-
### public static __construct( $language = 'en', $hyphen = null )
42-
Create a new Syllable class, with defaults
41+
### public __construct($language = 'en', string|Hyphen $hyphen = null)
42+
43+
Create a new Syllable class, with defaults.
44+
45+
### public static setCacheDir(string $dir)
4346

44-
### public static setCacheDir( $dir )
4547
Set the directory where compiled language files may be stored.
4648
Default to the `cache` subdirectory of the current directory.
4749

48-
### public static setLanguageDir( $dir )
50+
### public static setEncoding(string|null $encoding = null)
51+
52+
Set the character encoding to use.
53+
Specify `null` encoding to not apply any encoding at all.
54+
55+
### public static setLanguageDir(string $dir)
56+
4957
Set the directory where language source files can be found.
5058
Default to the `languages` subdirectory of the current directory.
5159

52-
### public static function setEncoding( $encoding = null )
53-
Specify the character encoding to use or disable character encoding handling
54-
completely by specifying `null` as encoding. The default encoding is `UTF-8`,
55-
which will work in most situations.
60+
### public setLanguage(string $language)
5661

57-
### public setLanguage( $language )
5862
Set the language whose rules will be used for hyphenation.
5963

60-
### public setHyphen( Mixed $hyphen )
64+
### public setHyphen(mixed $hyphen)
65+
6166
Set the hyphen text or object to use as a hyphen marker.
6267

63-
### public getHyphen( ) : Syllable_Hyphen_Interface
64-
Get the hyphen object used as a hyphen marker.
68+
### public getHyphen(): Hyphen
69+
70+
Get the current hyphen object.
71+
72+
### public setCache(Cache $cache = null)
73+
74+
### public getCache(): Cache
75+
76+
### public setSource($source)
77+
78+
### public getSource(): Source
79+
80+
### public setMinWordLength(int $length = 0)
81+
82+
Words need to contain at least this many character to be hyphenated.
83+
84+
### public getMinWordLength(): int
85+
86+
### public setLibxmlOptions(int $libxmlOptions)
6587

66-
### public setMinWordLength( integer $length = 0 )
67-
Set the minimum length required for a word to be hyphenated.
68-
Any words with less characters than this length will not be hyphenated.
88+
Options to use for HTML parsing by libxml.
89+
See https://www.php.net/manual/de/libxml.constants.php.
6990

70-
### public getMinWordLength( ) : int
71-
Get the minimum length required for a word to be hyphenated.
91+
### public excludeAll()
92+
93+
Exclude all elements.
94+
95+
### public excludeElement(string|string[] $elements)
96+
97+
Add one or more elements to exclude from HTML.
98+
99+
### public excludeAttribute(string|string[] $attributes, $value = null)
100+
101+
Add one or more elements with attributes to exclude from HTML.
102+
103+
### public excludeXpath(string|string[] $queries)
104+
105+
Add one or more xpath queries to exclude from HTML.
106+
107+
### public includeElement(string|string[] $elements)
108+
109+
Add one or more elements to include from HTML.
110+
111+
### public includeAttribute(string|string[] $attributes, $value = null)
112+
113+
Add one or more elements with attributes to include from HTML.
114+
115+
### public includeXpath(string|string[] $queries)
116+
117+
Add one or more xpath queries to include from HTML.
118+
119+
### public splitWord(string $word): array
72120

73-
### public array splitWord( $word )
74121
Split a single word on where the hyphenation would go.
122+
Punctuation is not supported, only simple words. For parsing whole sentences
123+
please use Syllable::splitWords() or Syllable::splitText().
124+
125+
### public splitWords(string $text): array
126+
127+
Split a text into an array of punctuation marks and words,
128+
splitting each word on where the hyphenation would go.
129+
130+
### public splitText(string $text): array
75131

76-
### public array splitText( $text )
77132
Split a text on where the hyphenation would go.
78133

79-
### public string hyphenateWord( $word )
134+
### public hyphenateWord(string $word): string
135+
80136
Hyphenate a single word.
81137

82-
### public string hyphenateText( $text )
138+
### public hyphenateText(string $text): string
139+
83140
Hyphenate all words in the plain text.
84141

85-
### public string hyphenateHtml( $html )
86-
Hyphenate all readable text in the HTML, excluding HTML tags and attributes.
142+
### public hyphenateHtml(string $html): string
143+
144+
Hyphenate all readable text in the HTML, excluding HTML tags and
145+
attributes.
146+
147+
### public histogramText(string $text): array
87148

88-
### public array histogramText( $text )
89149
Count the number of syllables in the text and return a map with
90150
syllable count as key and number of words for that syllable count as
91151
the value.
92152

93-
### public integer countWordsText( $text )
94-
Count the number of words in the text.
153+
### public countWordsText(string $text): int
95154

96-
### public integer countSyllablesText( $text )
97-
Count the number of syllables in the text.
98-
99-
### public integer countPolysyllablesText( $text )
100-
Count the number of polysyllables (words with 3 or more syllables) in the text.
101-
102-
### public function excludeAll()
103-
Exclude all HTML elements from hyphenation, allowing explicit whitelisting.
104-
105-
### public function excludeElement( $elements )
106-
Exclude from hyphenation all HTML content within the given elements.
107-
108-
### public function excludeAttribute( $attributes, $value = null )
109-
Exclude from hyphenation all HTML content within elements with the given
110-
attributes. If a value is specified, only those elements with attributes with
111-
that specific value are excluded.
155+
Count the number of words in the text.
112156

113-
### public function excludeXpath( $queries )
114-
Exclude from hyphenation all HTML content within elements matching the
115-
specified xpath queries.
157+
### public countSyllablesText(string $text): int
116158

117-
### public function includeElement( $elements )
118-
Hyphenate all HTML content within the given elements,
119-
ignoring any rules which might exclude them from hyphenation.
159+
Count the number of syllables in the text.
120160

121-
### public function includeAttribute( $attributes, $value = null )
122-
Hyphenate all HTML content within elements with the given attributes. If a value
123-
is specified, only those elements with attributes with that specific value are
124-
included, ignoring any rules which might exclude them from hyphenation.
161+
### public countPolysyllablesText(string $text): int
125162

126-
### public function includeXpath( $queries )
127-
Hyphenate all HTML content within elements matching the specified xpath queries,
128-
ignoring any rules which might exclude them from hyphenation.
163+
Count the number of polysyllables in the text.
129164

130165
Example
131166
-------
@@ -209,14 +244,34 @@ LOG_LEVEL=0 ./build/update-language-files
209244
```
210245
to silently run the script without outputting any logging.
211246

247+
### Update API documentation
248+
249+
Run
250+
```
251+
composer dump-autoload --dev
252+
./build/generate-docs
253+
```
254+
to update the API documentation in this README.md. This should be done when the Syllable class has been modified.
255+
Optionally, you can use environment variables to modify the documentation update process:
256+
257+
#### WITH_COMMIT
258+
259+
Create (1) or skip (0) a Git commit from the adapted files.
260+
Default: `0`.
261+
262+
#### LOG_LEVEL
263+
264+
Set the verbosity of the script to verbose (6), warnings and errors (4), errors only (3) or silent (0).
265+
Default: `6`.
266+
212267
### Create release
213268

214269
Run
215270
```
216271
composer dump-autoload --dev
217272
./build/create-release
218273
```
219-
to create a local release of the project by adding a changelog to this README.md.
274+
to create a local release of the project by adding a changelog to this README.md.
220275
Optionally, you can use environment variables to modify the release process:
221276

222277
#### RELEASE_TYPE

0 commit comments

Comments
 (0)