changeset 11565:21c3e1370b82

implement --list option for help function
author John W. Eaton <jwe@octave.org>
date Wed, 19 Jan 2011 05:05:07 -0500
parents 90f8d12f1964
children 8bb85ba7c9a6
files doc/interpreter/intro.txi scripts/ChangeLog scripts/help/help.m
diffstat 3 files changed, 56 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/intro.txi	Wed Jan 19 04:10:26 2011 -0500
+++ b/doc/interpreter/intro.txi	Wed Jan 19 05:05:07 2011 -0500
@@ -385,11 +385,11 @@
 
 In order to get good help you first need to know the name of the command
 that you want to use.  This name of the function may not always be
-obvious, but a good place to start is to just type @code{help}.
-This will show you all the operators, reserved words, functions,
-built-in variables, and function files.  An alternative is to search the
-documentation using the @code{lookfor} function.  This function is
-described in @ref{Getting Help}.
+obvious, but a good place to start is to just type @code{help --list}.
+This will show you all the operators, keywords, built-in functions,
+and loadable functions available in the current session of Octave.  An
+alternative is to search the documentation using the @code{lookfor}
+function.  This function is described in @ref{Getting Help}.
 
 Once you know the name of the function you wish to use, you can get more
 help on the function by simply including the name as an argument to help.
--- a/scripts/ChangeLog	Wed Jan 19 04:10:26 2011 -0500
+++ b/scripts/ChangeLog	Wed Jan 19 05:05:07 2011 -0500
@@ -1,3 +1,7 @@
+2011-01-19  John W. Eaton  <jwe@octave.org>
+
+	* help/help.m: New option --list.
+
 2011-01-19  John W. Eaton  <jwe@octave.org>
 
 	* io/strread.m: Avoid PCRE-ism in regexp.  Bug #32066.
--- a/scripts/help/help.m	Wed Jan 19 04:10:26 2011 -0500
+++ b/scripts/help/help.m	Wed Jan 19 05:05:07 2011 -0500
@@ -18,16 +18,21 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Command} {} help @var{name}
+## @deftypefn {Command} {} help @code{--list}
 ## Display the help text for @var{name}.
-## If invoked without any arguments, @code{help} displays instructions
+## If invoked without any arguments, @code{help} display instructions
 ## on how to access help from the command line.
-## 
+##
 ## For example, the command @kbd{help help} prints a short message
 ## describing the @code{help} command.
-## 
+##
+## Given the single argument @code{--list}, list all operators,
+## keywords, built-in functions, and loadable functions available
+## in the current session of Octave.
+##
 ## @deftypefnx {Function File} {@var{text} =} help (@var{name})
 ## Return the help text for the function, @var{name}.
-## 
+##
 ## The help command can give you information about operators, but not the
 ## comma and semicolons that are used as command separators.  To get help
 ## for those, you must type @kbd{help comma} or @kbd{help semicolon}.
@@ -56,6 +61,16 @@
 
   elseif (nargin == 1 && ischar (name))
 
+    if (strcmp (name, "--list"))
+      tmp = do_list_functions ();
+      if (nargout == 0)
+        printf ("%s", tmp);
+      else
+        retval = tmp;
+      endif
+      return;
+    endif
+
     ## Get help text
     [text, format] = get_help_text (name);
     
@@ -94,6 +109,34 @@
 
 endfunction
 
+function retval = do_list_functions ()
+
+  operators = sprintf ("*** operators:\n\n%s\n\n",
+                       list_in_columns (__operators__ ()));
+
+  keywords = sprintf ("*** keywords:\n\n%s\n\n",
+                      list_in_columns (__keywords__ ()));
+
+  builtins = sprintf ("*** builtins:\n\n%s\n\n",
+                      list_in_columns (__builtins__ ()));
+
+  dirs = strsplit (path, pathsep);
+  flist = "";
+  for i = 2:numel (dirs)
+    files = sort ({dir(fullfile (dirs{i}, "*.m")).name, ...
+                   dir(fullfile (dirs{i}, "*.oct")).name, ...
+                   dir(fullfile (dirs{i}, "*.mex")).name});
+
+    if (! isempty (files))
+      flist = sprintf ("%s*** functions in %s:\n\n%s\n\n",
+                       flist, dirs{i}, list_in_columns (files));
+    endif
+  endfor
+
+  retval = cstrcat (operators, keywords, builtins, flist);
+
+endfunction
+
 function do_contents (name)
 
   found = false;