octave_packages/m/help/lookfor.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  {Command} {} lookfor @var{str}
  21 ## @deftypefnx {Command} {} lookfor -all @var{str}
  22 ## @deftypefnx {Function File} {[@var{func}, @var{helpstring}] =} lookfor (@var{str})
  23 ## @deftypefnx {Function File} {[@var{func}, @var{helpstring}] =} lookfor ('-all', @var{str})
  24 ## Search for the string @var{str} in all functions found in the current
  25 ## function search path.  By default, @code{lookfor} searches for @var{str}
  26 ## in the first sentence of the help string of each function found.  The entire
  27 ## help text of each function can be searched if the '-all' argument is
  28 ## supplied.  All searches are case insensitive.
  29 ##
  30 ## Called with no output arguments, @code{lookfor} prints the list of
  31 ## matching functions to the terminal.  Otherwise, the output arguments
  32 ## @var{func} and @var{helpstring} define the matching functions and the
  33 ## first sentence of each of their help strings.
  34 ##
  35 ## The ability of @code{lookfor} to correctly identify the first
  36 ## sentence of the help text is dependent on the format of the
  37 ## function's help.  All Octave core functions are correctly
  38 ## formatted, but the same can not be guaranteed for external packages and
  39 ## user-supplied functions.  Therefore, the use of the '-all' argument may
  40 ## be necessary to find related functions that are not a part of Octave.
  41 ## @seealso{help, doc, which}
  42 ## @end deftypefn
  43
  44 function [out_fun, out_help_text] = lookfor (str, arg2)
  45
  46   if (strcmpi (str, "-all"))
  47     ## The difference between using '-all' and not, is which part of the caches
  48     ## we search.  The cache is organized such that the first column contains
  49     ## the function name, the second column contains the full help text, and
  50     ## the third column contains the first sentence of the help text.
  51     str = arg2;
  52     search_type = 2; # when using caches, search the second column
  53   else
  54     search_type = 3; # when using caches, search the third column
  55   endif
  56   str = lower (str);   # Compare is case insensitive
  57
  58   ## Search functions, operators, and keywords that come with Octave
  59   cache_file = doc_cache_file ();
  60   if (exist (cache_file, "file"))
  61     [fun, help_text] = search_cache (str, cache_file, search_type);
  62     had_core_cache = true;
  63   else
  64     fun = help_text = {};
  65     had_core_cache = false;
  66   endif
  67
  68   ## Search functions in new path dirs.
  69   orig_path = strsplit (__pathorig__ (), pathsep ());
  70
  71   ## ditto for path.
  72   new_path = strsplit (path (), pathsep ());
  73
  74   ## scratch out directories already covered by orig_path.
  75   if (had_core_cache)
  76     new_path = setdiff (new_path, orig_path);
  77   endif
  78
  79   for n = 1:numel (new_path)
  80     elt = new_path{n};
  81     cache_file = fullfile (elt, "doc-cache");
  82     if (exist (cache_file, "file"))
  83       ## We have a cache in the directory, then read it and search it!
  84       [funs, hts] = search_cache (str, cache_file, search_type);
  85       fun(end+1:end+length (funs)) = funs;
  86       help_text(end+1:end+length (hts)) = hts;
  87     else
  88     ## We don't have a cache. Search files
  89       funs_in_f = __list_functions__ (elt);
  90       for m = 1:length (funs_in_f)
  91         fn = funs_in_f{m};
  92
  93         ## Skip files that start with __
  94         if (length (fn) > 2 && strcmp (fn(1:2), "__"))
  95           continue;
  96         endif
  97
  98         ## Extract first sentence
  99         try
 100           warn_state = warning ();
 101           unwind_protect
 102             warning ("off");
 103             first_sentence = get_first_help_sentence (fn, 1024);
 104             status = 0;
 105           unwind_protect_cleanup
 106             warning (warn_state);
 107           end_unwind_protect
 108         catch
 109           status = 1;
 110         end_try_catch
 111
 112         if (search_type == 2) # search entire help text
 113           try
 114             warn_state = warning ();
 115             unwind_protect
 116               warning ("off");
 117               [text, fmt] = get_help_text (fn);
 118               status = 0;
 119             unwind_protect_cleanup
 120               warning (warn_state);
 121             end_unwind_protect
 122           catch
 123             status = 1;
 124           end_try_catch
 125
 126           ## Take action depending on help text fmt
 127           switch (lower (fmt))
 128             case "plain text"
 129               status = 0;
 130             case "texinfo"
 131               [text, status] = __makeinfo__ (text, "plain text");
 132             case "html"
 133               [text, status] = strip_html_tags (text);
 134             otherwise
 135               status = 1;
 136           endswitch
 137
 138         elseif (status == 0) # only search the first sentence of the help text
 139           text = first_sentence;
 140         endif
 141
 142         ## Search the help text, if we can
 143         if (status == 0 && ! isempty (strfind (lower (text), str)))
 144           fun(end+1) = fn;
 145           help_text(end+1) = first_sentence;
 146         endif
 147       endfor
 148     endif
 149   endfor
 150
 151   if (nargout == 0)
 152     ## Print the results (FIXME: it would be nice to break at word boundaries)
 153     indent = 20;
 154     term_width = (terminal_size ())(2);
 155     desc_width = term_width - indent - 2;
 156     indent_space = blanks (indent);
 157     for k = 1:length (fun)
 158       f = fun{k};
 159       f(end+1:indent-1) = " ";
 160       puts ([f " "]);
 161       lf = length (f);
 162       desc = strtrim (strrep (help_text{k}, "\n", " "));
 163       ldesc = length (desc);
 164       printf ("%s\n", desc(1:min (ldesc, desc_width - (lf - indent))));
 165       for start = (desc_width - (lf - indent) + 1):desc_width:ldesc
 166         stop = min (start + desc_width, ldesc);
 167         printf ("%s%s\n", indent_space, strtrim (desc (start:stop)));
 168       endfor
 169     endfor
 170
 171   else
 172     ## Return the results instead of displaying them
 173     out_fun = fun;
 174     out_help_text = help_text;
 175   endif
 176
 177 endfunction
 178
 179 function [funs, help_texts] = search_cache (str, cache_file, search_type)
 180   load (cache_file);
 181   if (! isempty (cache))
 182     t1 = strfind (lower (cache (1, :)), str);
 183     t2 = strfind (lower (cache (search_type, :)), str);
 184     cache_idx = find (! (cellfun ("isempty", t1) & cellfun ("isempty", t2)));
 185     funs = cache(1, cache_idx);
 186     help_texts = cache(3, cache_idx);
 187   else
 188     funs = help_texts = {};
 189   endif
 190 endfunction
 191