octave_packages/m/help/help.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} {} help @var{name}
  21 ## @deftypefnx {Command} {} help @code{--list}
  22 ## Display the help text for @var{name}.   For example, the command
  23 ## @kbd{help help} prints a short message describing the @code{help}
  24 ## command.
  25 ##
  26 ## Given the single argument @code{--list}, list all operators,
  27 ## keywords, built-in functions, and loadable functions available
  28 ## in the current session of Octave.
  29 ##
  30 ## If invoked without any arguments, @code{help} display instructions
  31 ## on how to access help from the command line.
  32 ##
  33 ## The help command can give you information about operators, but not the
  34 ## comma and semicolons that are used as command separators.  To get help
  35 ## for those, you must type @kbd{help comma} or @kbd{help semicolon}.
  36 ## @seealso{doc, lookfor, which}
  37 ## @end deftypefn
  38
  39 function retval = help (name)
  40
  41   if (nargin == 0)
  42
  43     puts ("\n\
  44   For help with individual commands and functions type\n\
  45 \n\
  46     help NAME\n\
  47 \n\
  48   (replace NAME with the name of the command or function you would\n\
  49   like to learn more about).\n\
  50 \n\
  51   For a more detailed introduction to GNU Octave, please consult the\n\
  52   manual.  To read the manual from the prompt type\n\
  53 \n\
  54     doc\n\
  55 \n\
  56   GNU Octave is supported and developed by its user community.\n\
  57   For more information visit http://www.octave.org.\n\n");
  58
  59   elseif (nargin == 1 && ischar (name))
  60
  61     if (strcmp (name, "--list"))
  62       tmp = do_list_functions ();
  63       if (nargout == 0)
  64         printf ("%s", tmp);
  65       else
  66         retval = tmp;
  67       endif
  68       return;
  69     endif
  70
  71     ## Get help text
  72     [text, format] = get_help_text (name);
  73
  74     ## Take action depending on help text format
  75     switch (lower (format))
  76       case "plain text"
  77         status = 0;
  78       case "texinfo"
  79         [text, status] = __makeinfo__ (text, "plain text");
  80       case "html"
  81         [text, status] = strip_html_tags (text);
  82       case "not documented"
  83         error ("help: `%s' is not documented\n", name);
  84       case "not found"
  85         do_contents (name);
  86         return;
  87       otherwise
  88         error ("help: internal error: unsupported help text format: '%s'\n", format);
  89     endswitch
  90
  91     ## Print text
  92     if (status != 0)
  93       warning ("help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...\n");
  94     endif
  95
  96     if (nargout == 0)
  97       which (name);
  98       printf ("\n%s\n%s", text, __additional_help_message__ ());
  99     else
 100       retval = text;
 101     endif
 102
 103   else
 104     error ("help: invalid input\n");
 105   endif
 106
 107 endfunction
 108
 109 function retval = do_list_functions ()
 110
 111   operators = sprintf ("*** operators:\n\n%s\n\n",
 112                        list_in_columns (__operators__ ()));
 113
 114   keywords = sprintf ("*** keywords:\n\n%s\n\n",
 115                       list_in_columns (__keywords__ ()));
 116
 117   builtins = sprintf ("*** builtins:\n\n%s\n\n",
 118                       list_in_columns (__builtins__ ()));
 119
 120   dirs = strsplit (path, pathsep);
 121   flist = "";
 122   for i = 2:numel (dirs)
 123     files = sort ({dir(fullfile (dirs{i}, "*.m")).name, ...
 124                    dir(fullfile (dirs{i}, "*.oct")).name, ...
 125                    dir(fullfile (dirs{i}, "*.mex")).name});
 126
 127     if (! isempty (files))
 128       flist = sprintf ("%s*** functions in %s:\n\n%s\n\n",
 129                        flist, dirs{i}, list_in_columns (files));
 130     endif
 131   endfor
 132
 133   retval = cstrcat (operators, keywords, builtins, flist);
 134
 135 endfunction
 136
 137 function do_contents (name)
 138
 139   found = false;
 140
 141   dlist = find_dir_in_path (name, "all");
 142
 143   for i = 1:numel (dlist)
 144     fname = make_absolute_filename (fullfile (dlist{i}, "Contents.m"));
 145
 146     [text, format] = get_help_text_from_file (fname);
 147
 148     ## Take action depending on help text format
 149     switch (lower (format))
 150       case "plain text"
 151         status = 0;
 152       case "texinfo"
 153         [text, status] = __makeinfo__ (text, "plain text");
 154       case "html"
 155         [text, status] = strip_html_tags (text);
 156     endswitch
 157
 158     if (! isempty (text))
 159       found = true;
 160       ## Print text.
 161       if (status != 0)
 162         warning ("help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...\n");
 163       endif
 164       printf ("%s:\n\n%s\n", fname, text);
 165     endif
 166
 167   endfor
 168
 169   if (found)
 170     puts (__additional_help_message__ ());
 171   else
 172     msg = feval (missing_function_hook, name);
 173
 174     if (isempty (msg))
 175       msg = sprintf ("`%s' not found", name);
 176     endif
 177
 178     error ("help: %s\n", msg);
 179   endif
 180
 181 endfunction
 182
 183
 184 %!assert (! isempty (findstr (help ("ls"), "List directory contents")))
 185 %!error <invalid input> help (42)