Mercurial > hg > octave-lyh

comparison scripts/help/get_first_help_sentence.m @ 14765:1f1777cab828

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary. Use Octave code format conventions for script. * get_first_help_sentence.m: Use '\.\s' regexp to find possible sentence boundary. Use Octave code format conventions for script.
author Rik <octave@nomad.inbox5.com>
date Wed, 13 Jun 2012 12:08:25 -0700
parents 461d268b10eb
children 5d3a684236b0
comparison
equal deleted inserted replaced
14764:461d268b10eb 14765:1f1777cab828
48 48
49 if (!ischar (name)) 49 if (!ischar (name))
50 error ("get_first_help_sentence: NAME must be a string"); 50 error ("get_first_help_sentence: NAME must be a string");
51 endif 51 endif
52 52
53 if (!isnumeric (max_len) || max_len <= 0 || max_len != fix (max_len)) 53 if (! isnumeric (max_len) || max_len <= 0 || max_len != fix (max_len))
54 error ("get_first_help_sentence: MAX_LEN must be positive integer"); 54 error ("get_first_help_sentence: MAX_LEN must be positive integer");
55 endif 55 endif
56 56
57 ## First, we get the raw help text 57 ## First, we get the raw help text
58 [help_text, format] = get_help_text (name); 58 [help_text, format] = get_help_text (name);
78 endif 78 endif
79 endfunction 79 endfunction
80 80
81 ## This function extracts the first sentence from a plain text help text 81 ## This function extracts the first sentence from a plain text help text
82 function [text, status] = first_sentence_plain_text (help_text, max_len) 82 function [text, status] = first_sentence_plain_text (help_text, max_len)
83 ## Extract first line by searching for a period (followed by a non-word 83 ## Extract first line by searching for a period followed by a space class
84 ## character to support periods in numbers or words)... 84 ## character (to support periods in numbers or words) ...
85 period_idx = regexp (help_text, '\.\W', "once"); 85 period_idx = regexp (help_text, '\.\s', "once");
86 ## ... or a double line-end (we subtract 1 because we are not interested on 86 ## ... or a double end-of-line (we subtract 1 because we are not interested
87 ## capturing the first newline) 87 ## in capturing the first newline).
88 line_end_idx = regexp (help_text, "\n\n", "once") -1; 88 line_end_idx = regexp (help_text, "\n\n", "once") - 1;
89 text = help_text (1:min ([period_idx; line_end_idx; max_len; length(help_text)])); 89 text = help_text (1:min ([period_idx; line_end_idx; max_len; length(help_text)]));
90 status = 0; 90 status = 0;
91 endfunction 91 endfunction
92 92
93 ## This function extracts the first sentence from a Texinfo help text. 93 ## This function extracts the first sentence from a Texinfo help text.
94 ## The function works by removing @def* from the texinfo text. After this, we 94 ## The function works by removing @def* from the texinfo text. After this, we
95 ## render the text to plain text using makeinfo, and then extract the first line. 95 ## render the text to plain text using makeinfo, and then extract the first line.
96 function [text, status] = first_sentence_texinfo (help_text, max_len) 96 function [text, status] = first_sentence_texinfo (help_text, max_len)
97 ## Lines ending with "@\n" are continuation lines, so they should be concatenated 97 ## Lines ending with "@\n" are continuation lines, so they should be
98 ## with the following line. 98 ## concatenated with the following line.
99 help_text = strrep (help_text, "@\n", " "); 99 help_text = strrep (help_text, "@\n", " ");
100 100
101 ## Find, and remove, lines that start with @def. This should remove things 101 ## Find, and remove, lines that start with @def. This should remove things
102 ## such as @deftypefn, @deftypefnx, @defvar, etc. 102 ## such as @deftypefn, @deftypefnx, @defvar, etc.
103 keep = true (size (help_text)); 103 keep = true (size (help_text));
104 def_idx = strfind (help_text, "@def"); 104 def_idx = strfind (help_text, "@def");
105 if (!isempty (def_idx)) 105 if (! isempty (def_idx))
106 endl_idx = find (help_text == "\n"); 106 endl_idx = find (help_text == "\n");
107 for k = 1:length (def_idx) 107 for k = 1:length (def_idx)
108 endl = endl_idx (find (endl_idx > def_idx (k), 1)); 108 endl = endl_idx (find (endl_idx > def_idx(k), 1));
109 if (isempty (endl)) 109 if (isempty (endl))
110 keep (def_idx (k):end) = false; 110 keep (def_idx(k) : end) = false;
111 else 111 else
112 keep (def_idx (k):endl) = false; 112 keep (def_idx(k) : endl) = false;
113 endif 113 endif
114 endfor 114 endfor
115 115
116 ## Remove the @end ... that corresponds to the @def we removed above 116 ## Remove the @end ... that corresponds to the @def we removed above
117 def1 = def_idx (1); 117 def1 = def_idx(1);
118 space_idx = find (help_text == " "); 118 space_idx = find (help_text == " ");
119 space_idx = space_idx (find (space_idx > def1, 1)); 119 space_idx = space_idx (find (space_idx > def1, 1));
120 bracket_idx = find (help_text == "{" | help_text == "}"); 120 bracket_idx = find (help_text == "{" | help_text == "}");
121 bracket_idx = bracket_idx (find (bracket_idx > def1, 1)); 121 bracket_idx = bracket_idx (find (bracket_idx > def1, 1));
122 if (isempty (space_idx) && isempty (bracket_idx)) 122 if (isempty (space_idx) && isempty (bracket_idx))
123 error ("get_first_help_sentence: couldn't parse texinfo"); 123 error ("get_first_help_sentence: couldn't parse texinfo");
124 endif 124 endif
125 sep_idx = min (space_idx, bracket_idx); 125 sep_idx = min (space_idx, bracket_idx);
126 def_type = help_text (def1+1:sep_idx-1); 126 def_type = help_text(def1+1:sep_idx-1);
127 127
128 end_idx = strfind (help_text, sprintf ("@end %s", def_type)); 128 end_idx = strfind (help_text, sprintf ("@end %s", def_type));
129 if (isempty (end_idx)) 129 if (isempty (end_idx))
130 error ("get_first_help_sentence: couldn't parse texinfo"); 130 error ("get_first_help_sentence: couldn't parse texinfo");
131 endif 131 endif
132 endl = endl_idx (find (endl_idx > end_idx, 1)); 132 endl = endl_idx(find (endl_idx > end_idx, 1));
133 if (isempty (endl)) 133 if (isempty (endl))
134 keep (end_idx:end) = false; 134 keep(end_idx:end) = false;
135 else 135 else
136 keep (end_idx:endl) = false; 136 keep(end_idx:endl) = false;
137 endif 137 endif
138 138
139 help_text = help_text (keep); 139 help_text = help_text(keep);
140 endif 140 endif
141 141
142 ## Run makeinfo to generate plain text 142 ## Run makeinfo to generate plain text
143 [help_text, status] = __makeinfo__ (help_text, "plain text"); 143 [help_text, status] = __makeinfo__ (help_text, "plain text");
144 144
160 %!assert (get_first_help_sentence ('get_first_help_sentence'), "Return the first sentence of a function's help text.") 160 %!assert (get_first_help_sentence ('get_first_help_sentence'), "Return the first sentence of a function's help text.")
161 161
162 %% Test input validation 162 %% Test input validation
163 %!error get_first_help_sentence () 163 %!error get_first_help_sentence ()
164 %!error get_first_help_sentence (1, 2, 3) 164 %!error get_first_help_sentence (1, 2, 3)
165 %!error get_first_help_sentence (1) 165 %!error <NAME must be a string> get_first_help_sentence (1)
166 %!error get_first_help_sentence ('ls', 'a') 166 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", "a")
167 %!error get_first_help_sentence ('ls', 0) 167 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 0)
168 %!error get_first_help_sentence ('ls', 80.1) 168 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 80.1)
169 169