1Lingua::EN::Fathom(3) User Contributed Perl DocumentationLingua::EN::Fathom(3)
2
6 Lingua::EN::Fathom - Measure readability of English text
7
9 use Lingua::EN::Fathom;
10 my $text = Lingua::EN::Fathom->new();
12 $text->analyse_file("sample.txt"); # Analyse contents of a text file
14 $accumulate = 1; $text->analyse_block($text_string,$accumulate); #
16 Analyse contents of a text string
17 # Methods to return statistics on the analysed text $text->num_chars;
19 $text->num_words; $text->percent_complex_words; $text->num_sentences;
20 $text->num_text_lines; $text->num_non_text_lines;
21 $text->num_blank_lines; # trailing EOLs are ignored
22 $text->num_paragraphs; $text->syllables_per_word;
23 $text->words_per_sentence; $text->unique_words; $text->fog;
24 $text->flesch; $text->kincaid;
25 # Call all of the above methods and present as a formatted report
27 print($text->report);
28 # get a hash of unique words, keyed by word and occurrence as the
30 value $text->unique_words
31 # Print a list of unique words %words = $text->unique_words; foreach
33 $word ( sort keys %words ) {
34 print("$words{$word} :$word\n"); }
35
37 Lingua::EN::Syllable, Lingua::EN::Sentence
38
40 This module analyses English text in either a string or file. Totals
41 are then calculated for the number of characters, words, sentences,
42 blank and non blank (text) lines and paragraphs.
43 Three common readability statistics are also derived, the Fog, Flesch
45 and Kincaid indices.
46 All of these properties can be accessed through individual methods, or
48 by generating a text report.
49 A hash of all unique words and the number of times they occur is
51 generated.
52
54 new
55 The "new" method creates an instance of an text object This must be
56 called before any of the following methods are invoked. Note that the
57 object only needs to be created once, and can be reused with new input
58 data.
59 my $text = Lingua::EN::Fathom->new();
61 analyse_file
63 The "analyse_file" method takes as input the name of a text file.
64 Various text based statistics are calculated for the file. This method
65 and "analyse_block" are prerequisites for all the following methods. An
66 optional argument may be supplied to control accumulation of
67 statistics. If set to a non zero value, all statistics are accumulated
68 with each successive call.
69 $text->analyse_file("sample.txt");
71 analyse_block
73 The "analyse_block" method takes as input a text string. Various text
74 based statistics are calculated for the file. This method and
75 "analyse_file" are prerequisites for all the following methods. An
76 optional argument may be supplied to control accumulation of
77 statistics. If set to a non zero value, all statistics are accumulated
78 with each successive call.
79 $text->analyse_block($text_str);
81 num_chars
83 Returns the number of characters in the analysed text file or block.
84 This includes characters such as spaces, and punctuation marks.
85 num_words
87 Returns the number of words in the analysed text file or block. A word
88 must consist of letters a-z with at least one vowel sound, and
89 optionally an apostrophe or hyphen. Items such as "&, K108, NW" are not
90 counted as words.
91 percent_complex_words
93 Returns the percentage of complex words in the analysed text file or
94 block. A complex word must consist of three or more syllables. This
95 statistic is used to calculate the fog index.
96 num_sentences
98 Returns the number of sentences in the analysed text file or block. A
99 sentence is any group of words and non words terminated with a single
100 full stop. Spaces may occur before and after the full stop.
101 num_text_lines
103 Returns the number of lines containing some text in the analysed text
104 file or block.
105 num_blank_lines
107 Returns the number of lines NOT containing any text in the analysed
108 text file or block.
109 num_paragraphs
111 Returns the number of paragraphs in the analysed text file or block.
112 syllables_per_word
114 Returns the average number of syllables per word in the analysed text
115 file or block.
116 words_per_sentence
118 Returns the average number of words per sentence in the analysed text
119 file or block.
120 READABILITY
122 Three indices of text readability are calculated. They all measure
123 complexity as a function of syllables per word and words per sentence.
124 They assume the text is well formed and logical. You could analyse a
125 passage of nonsensical English and find the readability is quite good,
126 provided the words are not too complex and the sentences not too long.
127 For more information see:
129 <http://www.plainlanguage.com/Resources/readability.html>
130 fog
132 Returns the Fog index for the analysed text file or block.
133 ( words_per_sentence + percent_complex_words ) * 0.4
135 The Fog index, developed by Robert Gunning, is a well known and simple
137 formula for measuring readability. The index indicates the number of
138 years of formal education a reader of average intelligence would need
139 to read the text once and understand that piece of writing with its
140 word sentence workload.
141 18 unreadable
143 14 difficult
144 12 ideal
145 10 acceptable
146 8 childish
147 flesch
149 Returns the Flesch reading ease score for the analysed text file or
150 block.
151 206.835 - (1.015 * words_per_sentence) - (84.6 * syllables_per_word)
153 This score rates text on a 100 point scale. The higher the score, the
155 easier it is to understand the text. A score of 60 to 70 is considered
156 to be optimal.
157 kincaid
159 Returns the Flesch-Kincaid grade level score for the analysed text file
160 or block.
161 (11.8 * syllables_per_word) + (0.39 * words_per_sentence) - 15.59;
163 This score rates text on U.S. grade school level. So a score of 8.0
165 means that the document can be understood by an eighth grader. A score
166 of 7.0 to 8.0 is considered to be optimal.
167 unique_words
169 Returns a hash of unique words. The words (in lower case) are held in
170 the hash keys while the number of occurrences are held in the hash
171 values.
172 report
174 print($text->report);
175 Produces a text based report containing all Fathom statistics for the
177 currently analysed text block or file. For example:
178 Number of characters : 813 Number of words : 135
180 Percent of complex words : 20.00 Average syllables per word : 1.7704
181 Number of sentences : 12 Average words per sentence : 11.2500
182 Number of text lines : 13 Number of blank lines : 8 Number
183 of paragraphs : 4
184 READABILITY INDICES
186 Fog : 12.5000 Flesch :
188 45.6429 Flesch-Kincaid : 9.6879
189 The return value is a string containing the report contents
191
193 Lingua::EN::Syllable,Lingua::EN::Sentence,B::Fathom
194
196 Count white space and punctuation characters Allow user control over
197 what strictly defines a word
198
200 The syllable count provided in Lingua::EN::Syllable is about 90%
201 accurate Acronyms that contain vowels, like GPO, will be counted as
202 words. The fog index should exclude proper names
203
205 Lingua::EN::Fathom was written by Kim Ryan <kimryan at cpan dot org>.
206
208 Copyright (c) 2023 Kim Ryan. All rights reserved.
209 This library is free software; you can redistribute it and/or modify it
211 under the same terms as Perl itself.
212perl v5.38.0 2023-07-20 Lingua::EN::Fathom(3)