readability

readability

A pure Go library for calculating text readability metrics, including Flesch-Kincaid Grade Level. Zero external dependencies, streaming-capable, and optimized for processing large texts like books.

Originally ported from words/syllable (MIT License).

A big thanks to the Project Gutenberg and OpenBible for providing test data for the grading.

See the example folder for API usage

Features

• Flesch-Kincaid Grade Level — Direct US grade level output (5.0 = 5th grade)
• Flesch Reading Ease — 0-100 score (higher = easier)
• Automated Readability Index (ARI) — Character-based, no syllable counting needed
• Gunning Fog Index — Estimates years of education needed
• SMOG Index — Simple Measure of Gobbledygook
• Coleman-Liau Index — Character-based grade level

Why This Library?

• No regex — Uses rune iteration and string matching for better performance
• Streaming support — Process files of any size via io.Reader
• Zero dependencies — Only uses Go standard library
• Accurate syllable counting — Handles silent e, -ed/-es endings, compound vowels, and 100+ problematic words

Installation

go get github.com/acmacalister/readability

Quick Start

package main

import (
    "fmt"
    "github.com/acmacalister/readability"
)

func main() {
    text := "The quick brown fox jumps over the lazy dog."
    
    // Get Flesch-Kincaid Grade Level
    grade := readability.FleschKincaidGrade(text)
    fmt.Printf("Grade Level: %.1f\n", grade)
    
    // Get Flesch Reading Ease
    ease := readability.FleschReadingEase(text)
    fmt.Printf("Reading Ease: %.1f\n", ease)
}

Usage

From a String

grade := readability.FleschKincaidGrade(text)
ease := readability.FleschReadingEase(text)
ari := readability.AutomatedReadabilityIndex(text)
fog := readability.GunningFogIndex(text)
smog := readability.SMOGIndex(text)
cli := readability.ColemanLiauIndex(text)

From an io.Reader (Files, HTTP responses, etc.)

file, _ := os.Open("book.txt")
defer file.Close()

grade, err := readability.FleschKincaidGradeReader(file)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Book grade level: %.1f\n", grade)

Analyze Once, Calculate Multiple Metrics

If you need multiple metrics, analyze the text once and reuse the stats:

stats := readability.Analyze(text)

grade := readability.FleschKincaidGradeFromStats(stats)
ease := readability.FleschReadingEaseFromStats(stats)
ari := readability.AutomatedReadabilityIndexFromStats(stats)
fog := readability.GunningFogIndexFromStats(stats)

Streaming Large Files

For memory-efficient processing of large files:

file, _ := os.Open("large-book.txt")
defer file.Close()

stats, err := readability.AnalyzeReader(file)
if err != nil {
    log.Fatal(err)
}

grade := readability.FleschKincaidGradeFromStats(stats)

Syllable Counting Only

If you only need syllable counts:

count := readability.Count("beautiful") // returns 3

// Or from a reader
file, _ := os.Open("document.txt")
count, err := readability.CountReader(file)

Grade Level Interpretation

Flesch-Kincaid Grade Level

Flesch Reading Ease

API Reference

Types

// Stats holds text statistics for readability calculations
type Stats struct {
    Characters int // Letter/digit count (for ARI)
    Words      int
    Sentences  int
    Syllables  int
}

// Analyzer provides streaming text analysis
type Analyzer struct { /* ... */ }

Functions

Analysis

func Analyze(text string) Stats
func AnalyzeReader(r io.Reader) (Stats, error)
func NewAnalyzer() *Analyzer

Flesch-Kincaid Grade Level

func FleschKincaidGrade(text string) float64
func FleschKincaidGradeReader(r io.Reader) (float64, error)
func FleschKincaidGradeFromStats(stats Stats) float64

Flesch Reading Ease

func FleschReadingEase(text string) float64
func FleschReadingEaseReader(r io.Reader) (float64, error)
func FleschReadingEaseFromStats(stats Stats) float64

Automated Readability Index

func AutomatedReadabilityIndex(text string) float64
func AutomatedReadabilityIndexReader(r io.Reader) (float64, error)
func AutomatedReadabilityIndexFromStats(stats Stats) float64

Other Metrics

func GunningFogIndex(text string) float64
func GunningFogIndexFromStats(stats Stats) float64

func SMOGIndex(text string) float64
func SMOGIndexFromStats(stats Stats) float64

func ColemanLiauIndex(text string) float64
func ColemanLiauIndexFromStats(stats Stats) float64

Syllable Counting

func Count(text string) int
func CountReader(r io.Reader) (int, error)
func NewCounter() *Counter

Performance

Benchmarks on Apple M1:

BenchmarkAnalyze-8              500000    2341 ns/op    0 B/op    0 allocs/op
BenchmarkAnalyzeLongText-8        5000  234521 ns/op    0 B/op    0 allocs/op
BenchmarkFleschKincaidGrade-8     5000  234892 ns/op    0 B/op    0 allocs/op

Accuracy Notes

The syllable counter handles most English words accurately, including:

• Silent 'e' endings (make, love, time)
• -ed endings (jumped vs wanted)
• -es endings (boxes vs makes)
• Compound vowels (beautiful, idea, video)
• Common prefixes/suffixes (un-, -ness, -tion)
• 100+ problematic words (people, queue, recipe, Wednesday, etc.)

For maximum accuracy with book-length texts, the errors tend to average out. If you need per-word precision, consider supplementing with a dictionary lookup.

Example: Book Pipeline Integration

package main

import (
    "fmt"
    "math"
    "os"
    
    "github.com/acmacalister/readability"
)

func main() {
    file, err := os.Open("book.txt")
    if err != nil {
        panic(err)
    }
    defer file.Close()
    
    stats, err := readability.AnalyzeReader(file)
    if err != nil {
        panic(err)
    }
    
    grade := readability.FleschKincaidGradeFromStats(stats)
    
    // Round to nearest 0.5 for storage
    roundedGrade := math.Round(grade*2) / 2
    
    fmt.Printf("Words: %d\n", stats.Words)
    fmt.Printf("Sentences: %d\n", stats.Sentences)
    fmt.Printf("Syllables: %d\n", stats.Syllables)
    fmt.Printf("Grade Level: %.1f\n", roundedGrade)
}

Running the Example

cd example
go run main.go

This demonstrates all the readability metrics, syllable counting, streaming analysis, and incremental processing.

License

MIT License - see LICENSE file for details.

Syllable counting algorithm ported from words/syllable (MIT License).