octave_packages/m/help/get_first_help_sentence.m

   1 ## Copyright (C) 2009-2012 S�ren Hauberg
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name})
  21 ## @deftypefnx {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len})
  22 ## Return the first sentence of a function's help text.
  23 ##
  24 ## The first sentence is defined as the text after the function
  25 ## declaration until either the first period (".") or the first appearance of
  26 ## two consecutive newlines ("\n\n").  The text is truncated to a maximum
  27 ## length of @var{max_len}, which defaults to 80.
  28 ##
  29 ## The optional output argument @var{status} returns the status reported by
  30 ## @code{makeinfo}.  If only one output argument is requested, and @var{status}
  31 ## is non-zero, a warning is displayed.
  32 ##
  33 ## As an example, the first sentence of this help text is
  34 ##
  35 ## @example
  36 ## @group
  37 ## get_first_help_sentence ("get_first_help_sentence")
  38 ## @print{} ans = Return the first sentence of a function's help text.
  39 ## @end group
  40 ## @end example
  41 ## @end deftypefn
  42
  43 function [text, status] = get_first_help_sentence (name, max_len = 80)
  44   ## Check input
  45   if (nargin < 1 || nargin > 2)
  46     print_usage ();
  47   endif
  48
  49   if (!ischar (name))
  50     error ("get_first_help_sentence: NAME must be a string");
  51   endif
  52
  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");
  55   endif
  56
  57   ## First, we get the raw help text
  58   [help_text, format] = get_help_text (name);
  59
  60   ## Then, we take action depending on the format
  61   switch (lower (format))
  62     case "plain text"
  63       [text, status] = first_sentence_plain_text (help_text, max_len);
  64     case "texinfo"
  65       [text, status] = first_sentence_texinfo (help_text, max_len);
  66     case "html"
  67       [text, status] = first_sentence_html (help_text, max_len);
  68     case "not documented"
  69       error ("get_first_help_sentence: `%s' is not documented\n", name);
  70     case "not found"
  71       error ("get_first_help_sentence: `%s' not found\n", name);
  72     otherwise
  73       error ("get_first_help_sentence: internal error: unsupported help text format: '%s'\n", format);
  74   endswitch
  75
  76   if (nargout <= 1 && status != 0)
  77     warning ("get_first_help_sentence: couldn't run makeinfo on '%s'", name);
  78   endif
  79 endfunction
  80
  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)
  83   ## Extract first line by searching for a period or a double line-end.
  84   period_idx = find (help_text == '.', 1);
  85   line_end_idx = strfind (help_text, "\n\n");
  86   text = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)]));
  87   status = 0;
  88 endfunction
  89
  90 ## This function extracts the first sentence from a Texinfo help text.
  91 ## The function works by removing @def* from the texinfo text. After this, we
  92 ## render the text to plain text using makeinfo, and then extract the first line.
  93 function [text, status] = first_sentence_texinfo (help_text, max_len)
  94   ## Lines ending with "@\n" are continuation lines, so they should be concatenated
  95   ## with the following line.
  96   help_text = strrep (help_text, "@\n", " ");
  97
  98   ## Find, and remove, lines that start with @def. This should remove things
  99   ## such as @deftypefn, @deftypefnx, @defvar, etc.
 100   keep = true (size (help_text));
 101   def_idx = strfind (help_text, "@def");
 102   if (!isempty (def_idx))
 103     endl_idx = find (help_text == "\n");
 104     for k = 1:length (def_idx)
 105       endl = endl_idx (find (endl_idx > def_idx (k), 1));
 106       if (isempty (endl))
 107         keep (def_idx (k):end) = false;
 108       else
 109         keep (def_idx (k):endl) = false;
 110       endif
 111     endfor
 112
 113     ## Remove the @end ... that corresponds to the @def we removed above
 114     def1 = def_idx (1);
 115     space_idx = find (help_text == " ");
 116     space_idx = space_idx (find (space_idx > def1, 1));
 117     bracket_idx = find (help_text == "{" | help_text == "}");
 118     bracket_idx = bracket_idx (find (bracket_idx > def1, 1));
 119     if (isempty (space_idx) && isempty (bracket_idx))
 120       error ("get_first_help_sentence: couldn't parse texinfo");
 121     endif
 122     sep_idx = min (space_idx, bracket_idx);
 123     def_type = help_text (def1+1:sep_idx-1);
 124
 125     end_idx = strfind (help_text, sprintf ("@end %s", def_type));
 126     if (isempty (end_idx))
 127       error ("get_first_help_sentence: couldn't parse texinfo");
 128     endif
 129     endl = endl_idx (find (endl_idx > end_idx, 1));
 130     if (isempty (endl))
 131       keep (end_idx:end) = false;
 132     else
 133       keep (end_idx:endl) = false;
 134     endif
 135
 136     help_text = help_text (keep);
 137   endif
 138
 139   ## Run makeinfo to generate plain text
 140   [help_text, status] = __makeinfo__ (help_text, "plain text");
 141
 142   ## Extract first line with plain text method.
 143   text = first_sentence_plain_text (help_text, max_len);
 144 endfunction
 145
 146 ## This function extracts the first sentence from a html help text.
 147 ## The function simply removes the tags and treats the text as plain text.
 148 function [text, status] = first_sentence_html (help_text, max_len)
 149   ## Strip tags
 150   [help_text, status] = strip_html_tags (help_text);
 151
 152   ## Extract first line with plain text method.
 153   text = first_sentence_plain_text (help_text, max_len);
 154 endfunction
 155
 156 %!assert (strcmp (get_first_help_sentence('get_first_help_sentence'), "Return the first sentence of a function's help text."));
 157
 158 %% Test input validation
 159 %!error get_first_help_sentence ()
 160 %!error get_first_help_sentence (1, 2, 3)
 161 %!error get_first_help_sentence (1)
 162 %!error get_first_help_sentence ('ls', 'a')
 163 %!error get_first_help_sentence ('ls', 0)
 164 %!error get_first_help_sentence ('ls', 80.1)
 165