readability

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 14, 2026 License: MIT Imports: 9 Imported by: 0

README

Readability

A Go library and CLI tool for measuring text readability. It implements 15 standard readability formulas commonly used in education, publishing, and content analysis. This is a Go rewrite of the Python textstat library.

Features

  • 15 readability formulas including Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, Dale-Chall, and more
  • Zero dependencies beyond the Go standard library
  • Library and CLI for use in Go programs or from the command line
  • Tested against textstat to ensure compatible results

Installation

Library
go get github.com/geordee/readability
CLI

Build from source:

go build -o readability ./cmd/readability

Or install to your $GOPATH/bin (so it's available globally):

go install ./cmd/readability

Quick Start

As a Library
package main

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

func main() {
    text := "The quick brown fox jumps over the lazy dog."
    a := readability.Analyzer{}

    score, err := a.Score(text, "flesch_reading_ease")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Flesch Reading Ease: %.2f\n", score)

    // Compute all formulas at once
    scores := a.ScoreAll(text)
    for formula, s := range scores {
        fmt.Printf("%s: %.2f\n", formula, s)
    }

    // Get raw text statistics
    stats := a.Analyze(text)
    fmt.Printf("Words: %d, Sentences: %d, Syllables: %d\n",
        stats.Words, stats.Sentences, stats.Syllables)
}
As a CLI Tool
# Score a single file
readability -f flesch_kincaid_grade essay.txt

# Score all text files in a directory
readability -f gunning_fog ./documents/

# Read from stdin
echo "The cat sat on the mat." | readability -f flesch_reading_ease

# List available formulas
readability -f help

Available Formulas

Formula Output Description
flesch_reading_ease 0-100+ score Higher = easier to read
flesch_kincaid_grade US grade level Grade level needed to understand text
gunning_fog US grade level Estimates years of education needed
smog_index US grade level Based on polysyllable word count
coleman_liau_index US grade level Character-based, no syllable counting
automated_readability_index US grade level Character-based formula
dale_chall_readability_score Raw score Uses familiar-word list
dale_chall_readability_score_v2 Raw score Variant with syllable threshold
linsear_write_formula US grade level Easy/hard word ratio over first 100 words
spache_readability US grade level Designed for primary-grade text
lix Index Scandinavian readability index
rix Index Simplified LIX variant
mcalpine_eflaw Index Counts mini-words (3 letters or fewer)
text_standard US grade level Consensus grade from multiple formulas
reading_time Seconds Estimated reading time

See the formulas reference for details on each formula.

Documentation

License

This project is a Go port of the textstat library created by Shivam Bansal, built using Claude Code. See LICENSE for details.

Documentation

Overview

Package readability provides text readability analysis using standard formulas.

It is a Go rewrite of the Python textstat library, targeting English text.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormulaNames 

func FormulaNames() []string

FormulaNames returns all formula names as strings, sorted.

Types

type Analysis 

type Analysis struct {
	// contains filtered or unexported fields
}

Analysis holds all pre-computed values any formula needs, computed once per text. An Analysis is immutable after construction via NewAnalysis.

func NewAnalysis 

func NewAnalysis(text string) *Analysis

NewAnalysis pre-computes all text statistics needed by readability formulas.

func (*Analysis) AutomatedReadabilityIndex 

func (a *Analysis) AutomatedReadabilityIndex() float64

AutomatedReadabilityIndex calculates the Automated Readability Index.

func (*Analysis) ColemanLiauIndex 

func (a *Analysis) ColemanLiauIndex() float64

ColemanLiauIndex calculates the Coleman-Liau Index.

func (*Analysis) DaleChallReadabilityScore 

func (a *Analysis) DaleChallReadabilityScore() float64

DaleChallReadabilityScore calculates the Dale-Chall Readability Score.

func (*Analysis) DaleChallReadabilityScoreV2 

func (a *Analysis) DaleChallReadabilityScoreV2() float64

DaleChallReadabilityScoreV2 calculates the New Dale-Chall Readability Score. Unlike v1, uses syllable_threshold=2 and checks raw_score > 0.05 for adjustment.

func (*Analysis) FleschKincaidGrade 

func (a *Analysis) FleschKincaidGrade() float64

FleschKincaidGrade calculates the Flesch-Kincaid Grade Level.

func (*Analysis) FleschReadingEase 

func (a *Analysis) FleschReadingEase() float64

FleschReadingEase calculates the Flesch Reading Ease score.

func (*Analysis) GunningFog 

func (a *Analysis) GunningFog() float64

GunningFog calculates the Gunning Fog Index.

func (*Analysis) LinsearWriteFormula 

func (a *Analysis) LinsearWriteFormula() float64

LinsearWriteFormula calculates the Linsear Write Formula with default options.

func (*Analysis) LinsearWriteFormulaOpts 

func (a *Analysis) LinsearWriteFormulaOpts(strictLower, strictUpper bool) float64

LinsearWriteFormulaOpts calculates the Linsear Write Formula with configurable bounds. strictLower: return 0 if text has fewer than 100 words. strictUpper: use only the first 100 words.

func (*Analysis) Lix 

func (a *Analysis) Lix() float64

Lix calculates the LIX readability index.

func (*Analysis) McalpineEFLAW 

func (a *Analysis) McalpineEFLAW() float64

McalpineEFLAW calculates the McAlpine EFLAW readability score.

func (*Analysis) ReadingTime 

func (a *Analysis) ReadingTime() float64

ReadingTime returns estimated reading time in seconds using the default 14.69 ms per character.

func (*Analysis) ReadingTimeWithRate 

func (a *Analysis) ReadingTimeWithRate(msPerChar float64) float64

ReadingTimeWithRate returns estimated reading time in seconds using the given ms per character.

func (*Analysis) Rix 

func (a *Analysis) Rix() float64

Rix calculates the RIX readability index. Uses the same long word count as LIX (> 6 letters, apostrophes removed).

func (*Analysis) Score 

func (a *Analysis) Score(formula Formula) (float64, error)

Score calculates the given readability formula.

func (*Analysis) ScoreAll 

func (a *Analysis) ScoreAll() map[Formula]float64

ScoreAll calculates all formulas and returns a map of formula → score.

func (*Analysis) SmogIndex 

func (a *Analysis) SmogIndex() float64

SmogIndex calculates the SMOG Index.

func (*Analysis) SpacheReadability 

func (a *Analysis) SpacheReadability() float64

SpacheReadability calculates the Spache Readability Formula.

func (*Analysis) SpacheReadabilityInt 

func (a *Analysis) SpacheReadabilityInt() int

SpacheReadabilityInt returns the Spache score truncated to an integer.

func (*Analysis) Stats 

func (a *Analysis) Stats() Stats

Stats returns raw text counting statistics.

func (*Analysis) TextStandard 

func (a *Analysis) TextStandard() float64

TextStandard estimates grade level as the mode of grade estimates from multiple formulas.

func (*Analysis) TextStandardString 

func (a *Analysis) TextStandardString() string

TextStandardString returns the text standard grade level as a string like "6th and 7th grade".

type Analyzer deprecated 

type Analyzer struct{}

Analyzer is a convenience type whose methods accept text and internally construct an Analysis for each call.

Deprecated: prefer NewAnalysis(text) for direct access to methods and to reuse a single Analysis across multiple formula calls.

func (*Analyzer) Analyze 

func (az *Analyzer) Analyze(text string) Stats

Analyze returns raw text counting statistics.

func (*Analyzer) LinsearWrite 

func (az *Analyzer) LinsearWrite(text string, strictLower, strictUpper bool) float64

LinsearWrite calculates the Linsear Write Formula with configurable bounds. strictLower: return 0 if text has fewer than 100 words. strictUpper: use only the first 100 words (default behavior).

func (*Analyzer) ReadingTime 

func (az *Analyzer) ReadingTime(text string, msPerChar float64) float64

ReadingTime returns estimated reading time in seconds using the given ms per character.

func (*Analyzer) Score 

func (az *Analyzer) Score(text string, formula Formula) (float64, error)

Score calculates the given readability formula for text.

func (*Analyzer) ScoreAll 

func (az *Analyzer) ScoreAll(text string) map[Formula]float64

ScoreAll calculates all formulas for text and returns a map of formula → score.

func (*Analyzer) SpacheReadabilityInt 

func (az *Analyzer) SpacheReadabilityInt(text string) int

SpacheReadabilityInt returns the Spache score truncated to an integer.

func (*Analyzer) TextStandardString 

func (az *Analyzer) TextStandardString(text string) string

TextStandardString returns grade level as a string like "6th and 7th grade".

type Formula 

type Formula string

Formula identifies a readability formula by name. 

const (
	FleschReadingEase           Formula = "flesch_reading_ease"
	FleschKincaidGrade          Formula = "flesch_kincaid_grade"
	GunningFog                  Formula = "gunning_fog"
	SmogIndex                   Formula = "smog_index"
	ColemanLiauIndex            Formula = "coleman_liau_index"
	AutomatedReadabilityIndex   Formula = "automated_readability_index"
	DaleChallReadabilityScore   Formula = "dale_chall_readability_score"
	DaleChallReadabilityScoreV2 Formula = "dale_chall_readability_score_v2"
	LinsearWriteFormula         Formula = "linsear_write_formula"
	SpacheReadability           Formula = "spache_readability"
	Lix                         Formula = "lix"
	McalpineEFLAW               Formula = "mcalpine_eflaw"
	Rix                         Formula = "rix"
	TextStandard                Formula = "text_standard"
	ReadingTime                 Formula = "reading_time"
)

func AllFormulas 

func AllFormulas() []Formula

AllFormulas returns a sorted list of all available formula names.

func (Formula) Valid 

func (f Formula) Valid() bool

Valid reports whether f is a recognized formula.

type Stats 

type Stats struct {
	Chars             int
	Letters           int
	Words             int
	Sentences         int
	Syllables         int
	LongWords         int
	PolysyllableWords int
	MonosyllableWords int
}

Stats holds raw text counting statistics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.