ReadabilityScoreKit
Six classic English readability formulas in Swift, with no dependencies and no data files.
import ReadabilityScoreKit
if let scores = Readability.score("The cat sat on the mat. The dog ran.") {
print(scores.fleschReadingEase) // 117.66750000000002
print(scores.readingEaseBand) // veryEasy
print(scores.averageGradeLevel) // -1.6140688888888892
}
What it computes
| Score | Published as | Formula |
|---|
fleschReadingEase | Flesch, 1948 | 206.835 - 1.015 x (words / sentences) - 84.6 x (syllables / words) |
fleschKincaidGrade | Kincaid et al., 1975 | 0.39 x (words / sentences) + 11.8 x (syllables / words) - 15.59 |
gunningFog | Gunning, 1952 | 0.4 x [(words / sentences) + 100 x (complex words / words)] |
smogIndex | McLaughlin, 1969 | 1.0430 x sqrt(polysyllables x (30 / sentences)) + 3.1291 |
colemanLiauIndex | Coleman and Liau, 1975 | 0.0588 x L - 0.296 x S - 15.8 |
automatedReadabilityIndex | Smith and Senter, 1967 | 4.71 x (characters / words) + 0.5 x (words / sentences) - 21.43 |
Five of the six are expressed as a U.S. school grade. Flesch Reading Ease is a 0-100-ish
scale where higher means easier; it is unbounded, so very short simple sentences can score
above 100 and very dense ones below zero.
averageGradeLevel is the mean of the five grade formulas, which is steadier than any one
of them on short text.
Installation
.package(url: "https://github.com/theluckystrike/ReadabilityScoreKit.git", from: "1.0.0")
.target(name: "YourTarget", dependencies: ["ReadabilityScoreKit"])
Counts, and where they come from
Every formula reads from one TextStatistics value, so two scores for the same text always
agree about how many words it contains. You can inspect or supply the counts yourself:
let stats = Readability.statistics(for: text)
stats.wordCount
stats.sentenceCount
stats.syllableCount
stats.polysyllableCount // three or more syllables
let scores = ReadabilityScores(statistics: stats)
- Words are whitespace-separated tokens containing at least one letter or digit, so a
bare
-- is not counted.
- Sentences are runs of
., ! or ?. Wait!!! is one break, not three. Text with no
terminal punctuation is treated as a single sentence so headlines still score.
- Characters are letters and digits only, excluding whitespace and punctuation.
- Syllables come from a vowel-group heuristic (see below).
Readability.score returns nil for text with no words, rather than zero, so
"unmeasurable" stays distinguishable from "scored zero".
Accuracy: read this before trusting a number
The syllable count is a heuristic, not a dictionary lookup. It counts maximal vowel runs,
drops a silent trailing e, and adds one back for a consonant + le ending, with plurals
normalised so circles scores the same as circle. That gets ordinary English words right
most of the time, and gets some of them wrong: names, loanwords, and words where a vowel pair
spans a syllable boundary such as cre-ate. Flesch, Flesch-Kincaid, Gunning Fog and SMOG all
inherit that error. Coleman-Liau and ARI are character-based and do not.
Gunning's original definition of a "complex word" also excluded proper nouns, familiar jargon,
compounds, and words made polysyllabic only by an -es or -ed suffix. This implementation
applies none of those exclusions, so gunningFog reads a little high on text full of names.
Markdown, HTML tags and code are not stripped. Strip them before scoring or they are counted
as words.
Treat every score as a band, not a measurement.
Platforms
Pure Swift with no dependencies and no Foundation requirement in the scoring path. Builds
anywhere a Swift 5.9 toolchain runs.
Tests
swift test
The formula tests use fixed counts so each constant is checked against the published formula
by hand, rather than against this package's own tokenizer. The tokenizer and syllable counter
are tested separately.
See also
The same six formulas, implemented as hosted web tools:
Useful for sanity-checking this library's output against an independent implementation.
Licence
MIT. See LICENSE.
