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