1Lingua::EN::Fathom(3) User Contributed Perl DocumentationLingua::EN::Fathom(3)
2
3
4

NAME

6       Lingua::EN::Fathom - Measure readability of English text
7

SYNOPSIS

9           use Lingua::EN::Fathom;
10
11           my $text = Lingua::EN::Fathom->new();
12
13           # Analyse contents of a text file
14           $text->analyse_file("sample.txt"); # Analyse contents of a text file
15
16           $accumulate = 1;
17           # Analyse contents of a text string
18           $text->analyse_block($text_string,$accumulate);
19
20           # 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
31          # comment needed
32           %words = $text->unique_words;
33           foreach $word ( sort keys %words )
34           {
35             print("$words{$word} :$word\n");
36           }
37
38           $fog     = $text->fog;
39           $flesch  = $text->flesch;
40           $kincaid = $text->kincaid;
41
42           print($text->report);
43

REQUIRES

45       Perl, version 5.001 or higher, Lingua::EN::Syllable
46

DESCRIPTION

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
52       Three common readability statistics are also derived, the Fog, Flesch
53       and Kincaid indices.
54
55       All of these properties can be accessed through individual methods, or
56       by generating a text report.
57
58       A hash of all unique words and the number of times they occur is
59       generated.
60

METHODS

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
68          my $text = Lingua::EN::Fathom->new();
69
70   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
78           $text->analyse_file("sample.txt");
79
80   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
88           $text->analyse_block($text_str);
89
90   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
94   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
100   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
105   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
110   num_text_lines
111       Returns the number of lines containing some text in the analysed text
112       file or block.
113
114   num_blank_lines
115       Returns the number of lines NOT containing any text in the analysed
116       text file or block.
117
118   num_paragraphs
119       Returns the number of paragraphs in the analysed text file or block.
120
121   syllables_per_word
122       Returns the average number of syllables per word in the analysed text
123       file or block.
124
125   words_per_sentence
126       Returns the average number of words per sentence in the analysed text
127       file or block.
128
129   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
136       For more information see:
137       <http://www.plainlanguage.com/Resources/readability.html>
138
139   fog
140       Returns the Fog index for the analysed text file or block.
141
142         ( words_per_sentence + percent_complex_words ) * 0.4
143
144       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
150          18 unreadable
151          14 difficult
152          12 ideal
153          10 acceptable
154           8 childish
155
156   flesch
157       Returns the Flesch reading ease score for the analysed text file or
158       block.
159
160          206.835 - (1.015 * words_per_sentence) - (84.6 * syllables_per_word)
161
162       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
166   kincaid
167       Returns the Flesch-Kincaid grade level score for the analysed text file
168       or block.
169
170          (11.8 * syllables_per_word) +  (0.39 * words_per_sentence) - 15.59;
171
172       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
176   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
181   report
182           print($text->report);
183
184       Produces a text based report containing all Fathom statistics for the
185       currently analysed text block or file. For example:
186
187       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
193       READABILITY INDICES
194
195       Fog                        : 12.5000 Flesch                     :
196       45.6429 Flesch-Kincaid             : 9.6879
197
198       The return value is a string containing the report contents
199

SEE ALSO

201       Lingua::EN::Syllable,Lingua::EN::Sentence,B::Fathom
202

POSSIBLE EXTENSIONS

204          Count white space and punctuation characters
205          Allow user control over what strictly defines a word
206

LIMITATIONS

208       The syllable count provided in Lingua::EN::Syllable is about 90%
209       accurate
210
211       Acronyms that contain vowels, like GPO, will be counted as words.
212
213       The fog index should exclude proper names
214

BUGS

216       None known
217

AUTHOR

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
224       This library is free software; you can redistribute it and/or modify it
225       under the same terms as Perl itself.
226
227
228
229perl v5.34.0                      2022-01-21             Lingua::EN::Fathom(3)
Impressum