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");
14 $accumulate = 1;
16 $text->analyse_block($text_string,$accumulate);
17 $num_chars = $text->num_chars;
19 $num_words = $text->num_words;
20 $percent_complex_words = $text->percent_complex_words;
21 $num_sentences = $text->num_sentences;
22 $num_text_lines = $text->num_text_lines;
23 $num_blank_lines = $text->num_blank_lines;
24 $num_paragraphs = $text->num_paragraphs;
25 $syllables_per_word = $text->syllables_per_word;
26 $words_per_sentence = $text->words_per_sentence;
27 %words = $text->unique_words;
30 foreach $word ( sort keys %words )
31 {
32 print("$words{$word} :$word\n");
33 }
34 $fog = $text->fog;
36 $flesch = $text->flesch;
37 $kincaid = $text->kincaid;
38 print($text->report);
40
42 Perl, version 5.001 or higher, Lingua::EN::Syllable
43
45 This module analyses English text in either a string or file. Totals
46 are then calculated for the number of characters, words, sentences,
47 blank and non blank (text) lines and paragraphs.
48 Three common readability statistics are also derived, the Fog, Flesch
50 and Kincaid indices.
51 All of these properties can be accessed through individual methods, or
53 by generating a text report.
54 A hash of all unique words and the number of times they occur is
56 generated.
57
59 new
60 The "new" method creates an instance of an text object This must be
61 called before any of the following methods are invoked. Note that the
62 object only needs to be created once, and can be reused with new input
63 data.
64 my $text = Lingua::EN::Fathom->new();
66 analyse_file
68 The "analyse_file" method takes as input the name of a text file.
69 Various text based statistics are calculated for the file. This method
70 and "analyse_block" are prerequisites for all the following methods. An
71 optional argument may be supplied to control accumulation of
72 statistics. If set to a non zero value, all statistics are accumulated
73 with each successive call.
74 $text->analyse_file("sample.txt");
76 analyse_block
78 The "analyse_block" method takes as input the name of a text file.
79 Various text based statistics are calculated for the file. This method
80 and "analyse_file" are prerequisites for all the following methods. An
81 optional argument may be supplied to control accumulation of
82 statistics. If set to a non zero value, all statistics are accumulated
83 with each successive call.
84 $text->analyse_block("sample.txt");
86 num_chars
88 Returns the number of characters in the analysed text file or block.
89 This includes characters such as spaces, and punctuation marks.
90 num_words
92 Returns the number of words in the analysed text file or block. A word
93 must consist of letters a-z with at least one vowel sound, and
94 optionally an apostrophe or hyphen. Items such as "&, K108, NW" are not
95 counted as words.
96 percent_complex_words
98 Returns the percentage of complex words in the analysed text file or
99 block. A complex word must consist of three or more syllables. This
100 statistic is used to calculate the fog index.
101 num_sentences
103 Returns the number of sentences in the analysed text file or block. A
104 sentence is any group of words and non words terminated with a single
105 full stop. Spaces may occur before and after the full stop.
106 num_text_lines
108 Returns the number of lines containing some text in the analysed text
109 file or block.
110 num_blank_lines
112 Returns the number of lines NOT containing any text in the analysed
113 text file or block.
114 num_paragraphs
116 Returns the number of paragraphs in the analysed text file or block.
117 syllables_per_word
119 Returns the average number of syllables per word in the analysed text
120 file or block.
121 words_per_sentence
123 Returns the average number of words per sentence in the analysed text
124 file or block.
125 READABILITY
127 Three indices of text readability are calculated. They all measure
128 complexity as a function of syllables per word and words per sentence.
129 They assume the text is well formed and logical. You could analyse a
130 passage of nonsensical English and find the readability is quite good,
131 provided the words are not too complex and the sentences not too long.
132 For more information see:
134 <http://www.plainlanguage.com/Resources/readability.html>
135 fog
137 Returns the Fog index for the analysed text file or block.
138 ( words_per_sentence + percent_complex_words ) * 0.4
140 The Fog index, developed by Robert Gunning, is a well known and simple
142 formula for measuring readability. The index indicates the number of
143 years of formal education a reader of average intelligence would need
144 to read the text once and understand that piece of writing with its
145 word sentence workload.
146 18 unreadable
148 14 difficult
149 12 ideal
150 10 acceptable
151 8 childish
152 flesch
154 Returns the Flesch reading ease score for the analysed text file or
155 block.
156 206.835 - (1.015 * words_per_sentence) - (84.6 * syllables_per_word)
158 This score rates text on a 100 point scale. The higher the score, the
160 easier it is to understand the text. A score of 60 to 70 is considered
161 to be optimal.
162 kincaid
164 Returns the Flesch-Kincaid grade level score for the analysed text file
165 or block.
166 (11.8 * syllables_per_word) + (0.39 * words_per_sentence) - 15.59;
168 This score rates text on U.S. grade school level. So a score of 8.0
170 means that the document can be understood by an eighth grader. A score
171 of 7.0 to 8.0 is considered to be optimal.
172 unique_words
174 Returns a hash of unique words. The words (in lower case) are held in
175 the hash keys while the number of occurrences are held in the hash
176 values.
177 report
179 print($text->report);
180 Produces a text based report containing all Fathom statistics for the
182 currently analysed text block or file. For example:
183 Number of characters : 813 Number of words : 135
185 Percent of complex words : 20.00 Average syllables per word : 1.7704
186 Number of sentences : 12 Average words per sentence : 11.2500
187 Number of text lines : 13 Number of blank lines : 8 Number
188 of paragraphs : 4
189 READABILITY INDICES
191 Fog : 12.5000 Flesch :
193 45.6429 Flesch-Kincaid : 9.6879
194 The return value is a string containing the report contents
196
198 Lingua::EN::Syllable,Lingua::EN::Sentence,B::Fathom
199
201 Count white space and punctuation characters
202 Allow user control over what strictly defines a word
203 Provide a density measure of white space to characters
204
206 The syllable count provided in Lingua::EN::Syllable is about 90%
207 accurate
208 Acronyms that contain vowels, like GPO, will be counted as words.
210 The fog index should exclude proper names
212
214 None known
215
217 Lingua::EN::Fathom was written by Kim Ryan <kimryan at cpan dot org>.
218
220 Copyright (c) 2016 Kim Ryan. All rights reserved.
221 This library is free software; you can redistribute it and/or modify it
223 under the same terms as Perl itself.
224perl v5.28.0 2016-09-15 Lingua::EN::Fathom(3)