# HG changeset patch
# User jwe
# Date 1119042982 0
# Node ID db34dff199473f37bdc7383c45e9303a09688d11
# Parent  1b6a837fe24d663cc98a3a9d4888c0e8cacd5c6a
[project @ 2005-06-17 21:16:20 by jwe]

diff -r 1b6a837fe24d -r db34dff19947 scripts/ChangeLog
--- a/scripts/ChangeLog	Fri Jun 17 15:58:12 2005 +0000
+++ b/scripts/ChangeLog	Fri Jun 17 21:16:22 2005 +0000
@@ -1,3 +1,7 @@
+2005-06-17  Keith Goodman  <kwgoodman@gmail.com>
+
+	* miscellaneous/tic.m: Fix doc string.
+
 2005-06-15  John W. Eaton  <jwe@octave.org>
 
 	* polynomial/polyfit.m: Force return value to be a row vector.
diff -r 1b6a837fe24d -r db34dff19947 scripts/miscellaneous/tic.m
--- a/scripts/miscellaneous/tic.m	Fri Jun 17 15:58:12 2005 +0000
+++ b/scripts/miscellaneous/tic.m	Fri Jun 17 21:16:22 2005 +0000
@@ -32,6 +32,10 @@
 ## will set the variable @code{elapsed_time} to the number of seconds since
 ## the most recent call to the function @code{tic}.
 ##
+## Nested timing with @code{tic} and @code{toc} is not supported.
+## Therefore @code{toc} will always return the elapsed time from the most
+## recent call to @code{tic}.
+##
 ## If you are more interested in the CPU time that your process used, you
 ## should use the @code{cputime} function instead.  The @code{tic} and
 ## @code{toc} functions report the actual wall clock time that elapsed
diff -r 1b6a837fe24d -r db34dff19947 src/ChangeLog
--- a/src/ChangeLog	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/ChangeLog	Fri Jun 17 21:16:22 2005 +0000
@@ -1,5 +1,20 @@
 2005-06-17  John W. Eaton  <jwe@octave.org>
 
+	* help.cc (help_from_list, help_from_symbol_table, 
+	help_from_file): New arg, symbol_found.
+	(builtin_help): Use symbol_found arg to determine whether help
+	text is empty or symbol is not available.
+
+	* symtab.cc (symbol_record::print_info): Print more info.
+
+	* DLD-FUNCTIONS/dispatch.cc (Fdispatch_help): Delete.
+	(dispatch_record): Don't prepend "<>" to help text.
+	(Fdispatch): Don't setup dispatched help.
+
+	* help.cc (extract_help_from_dispatch): New function.
+	(help_from_symbol_table): Use it.
+	* defun.cc (print_usage): Use it.
+
 	* toplev.cc (octave_config_info): Include localapifcnfiledir and
 	localapioctfiledir in the list.
 
@@ -18,11 +33,9 @@
 	(symbol_out_of_date): Also check for symbol using full function
 	file name.
 
-	* symtab.h (symbol_record::symbol_def::visible): New data member.
-	(symbol_record::symbol_def::hide, symbol_record::symbol_def::show,
-	symbol_record::symbol_def::is_visible): New functions.
+	* symtab.h (symbol_record::visible): New data member.
 	(symbol_record::hide, symbol_record::show, symbol_record::is_visible):
-	New functions.
+	New functions. 
 
 	* symtab.h (symbol_record::maybe_delete_def): New private function.
 	* symtab.cc (symbol_record::clear, symbol_record::alias,
diff -r 1b6a837fe24d -r db34dff19947 src/DLD-FUNCTIONS/dispatch.cc
--- a/src/DLD-FUNCTIONS/dispatch.cc	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/DLD-FUNCTIONS/dispatch.cc	Fri Jun 17 21:16:22 2005 +0000
@@ -218,7 +218,7 @@
       // Move the builtin function out of the way and restore the
       // dispatch fuction.
       // XXX FIXME XXX what if builtin wants to protect itself?
-      symbol_record *found=fbi_sym_tab->lookup (base, 0);
+      symbol_record *found = fbi_sym_tab->lookup (base, 0);
       bool readonly = found->is_read_only ();
       found->unprotect ();
       fbi_sym_tab->rename (base, "builtin:" + base);
@@ -246,7 +246,6 @@
   return false;
 }
 
-
 octave_value_list
 octave_dispatch::do_multi_index_op (int nargout, const octave_value_list& args)
 {
@@ -331,51 +330,6 @@
   return retval;
 }
 
-DEFUN_DLD (dispatch_help, args, nargout,
-  "-*- texinfo -*-\n\
-@deftypefn {Loadable Function} {} dispatch_help (@var{name}, @dots{})\n\
-Delayed loading of help messages for dispatched functions.\n\
-@end deftypefn\n\
-@seealso{builtin, dispatch}")
-{
-  octave_value_list retval;
-
-  int nargin = args.length ();
-
-  for (int i = 0; i < nargin; i++)
-    {
-      if (args(i).is_string ())
-	{
-	  const std::string name (args(i).string_value ());
-
-	  if (error_state)
-	    return retval;
-
-	  symbol_record *sr = fbi_sym_tab->lookup (name, false);
-
-	  if (sr)
-	    {
-	      std::string help = sr->help ();
-
-	      if (help[0] == '<' && help[1] == '>'
-		  && sr->def().type_id () == octave_dispatch::static_type_id ())
-		{
-		  builtin (name);
-
-		  symbol_record *builtin_record
-		    = fbi_sym_tab->lookup ("builtin:" + name, 0);
-
-		  help.replace (0, 2, builtin_record->help ());
-
-		  sr->document (help);
-		}
-	    }
-	}
-    }
-
-  return feval ("builtin:help", args, nargout);
-}
-
 static void
 dispatch_record (const std::string &f, const std::string &n, 
 		 const std::string &t)
@@ -406,10 +360,10 @@
       else 
         fbi_sym_tab->rename (f, "builtin:" + f);
 
-      std::string basedoc ("<>"); 
-
-      if (! sr->help().empty ())
-	basedoc = sr->help ();
+      // It would be good to hide the builtin:XXX name, but since the
+      // new XXX name in the symbol table is set to BUILTIN_FUNCTION,
+      // things don't work quite the way we would like.
+      // sr->hide ();
 
       // Problem:  when a function is first called a new record
       // is created for it in the current symbol table, so calling
@@ -436,7 +390,7 @@
       // std::cout << "iscommand('"<<f<<"')=" << iscommand << std::endl;
       if (iscommand)
 	sr->mark_as_command();
-      sr->document (basedoc + "\n\n@noindent\nOverloaded function:\n");
+      sr->document ("\n\n@noindent\nOverloaded function:\n");
       sr->make_eternal (); // XXX FIXME XXX why??
       sr->mark_as_static ();
       sr->protect ();
@@ -520,8 +474,6 @@
       octave_dispatch::register_type ();
       register_type = false;
       fbi_sym_tab->lookup("dispatch")->mark_as_static ();
-      dispatch_record ("help", "dispatch_help", "string");
-      dispatch_record ("help", "dispatch_help", "sq_string");
     }
 
   dispatch_record (f, n, t);
diff -r 1b6a837fe24d -r db34dff19947 src/defun.cc
--- a/src/defun.cc	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/defun.cc	Fri Jun 17 21:16:22 2005 +0000
@@ -41,6 +41,9 @@
 #include "symtab.h"
 #include "variables.h"
 
+// XXX FIXME XXX -- this function could probably share some code with
+// the help functions.
+
 void
 print_usage (const std::string& nm, bool just_usage)
 {
@@ -56,6 +59,8 @@
 
 	  buf << "\n*** " << nm << ":\n\n";
 
+	  h = extract_help_from_dispatch (nm) + h;
+
 	  display_help_text (buf, h);
 
 	  buf << "\n";
diff -r 1b6a837fe24d -r db34dff19947 src/help.cc
--- a/src/help.cc	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/help.cc	Fri Jun 17 21:16:22 2005 +0000
@@ -610,7 +610,7 @@
 		}
 	      else
 		{
-		  message ("help", "sorry, `%s' is not indexed in the manual",
+		  message ("help", "`%s' is not indexed in the manual",
 			   argv[i].c_str ());
 		}
 	    }
@@ -719,35 +719,99 @@
 
 static bool
 help_from_list (std::ostream& os, const help_list *list,
-		const std::string& nm, int usage)
+		const std::string& nm, int usage, bool& symbol_found)
 {
+  bool retval = false;
+
   const char *name;
 
   while ((name = list->name) != 0)
     {
       if (strcmp (name, nm.c_str ()) == 0)
 	{
-	  if (usage)
-	    os << "\nusage: ";
-	  else
+	  symbol_found = true;
+
+	  std::string h = list->help;
+
+	  if (h.length () > 0)
 	    {
-	      os << "\n*** " << nm << ":\n\n";
+	      if (usage)
+		os << "\nusage: ";
+	      else
+		os << "\n*** " << nm << ":\n\n";
+
+	      display_help_text (os, h);
+
+	      os << "\n";
+
+	      retval = true;
 	    }
-
-	  display_help_text (os, list->help);
-
-	  os << "\n";
-
-	  return true;
+	  break;
 	}
       list++;
     }
 
-  return false;
+  return retval;;
+}
+
+std::string
+extract_help_from_dispatch (const std::string& nm)
+{
+  std::string retval;
+
+  symbol_record *builtin = fbi_sym_tab->lookup ("builtin:" + nm, 0);
+
+  if (builtin)
+    {
+      // Check that builtin is up to date.
+ 
+      // Don't try to fight octave's function name handling
+      // mechanism.  Instead, move dispatch record out of the way,
+      // and restore the builtin to its original name.
+      symbol_record *dispatch = fbi_sym_tab->lookup (nm, 0);
+
+      if (dispatch)
+	{
+	  dispatch->unprotect ();
+
+	  fbi_sym_tab->rename (nm, "dispatch:" + nm);
+	  fbi_sym_tab->rename ("builtin:" + nm, nm);
+
+	  // Check for updates to builtin function; ignore errors
+	  // that appear (they interfere with renaming), and remove
+	  // the updated name from the current symbol table.  XXX
+	  // FIXME XXX check that updating a function updates it in
+	  // all contexts --- it may be that it is updated only in the
+	  // current symbol table, and not the caller.  I believe this
+	  // won't be a problem because the caller will go through the
+	  // same logic and end up with the newer version.
+
+	  octave_function *f = is_valid_function (nm);
+
+	  if (f)
+	    retval = builtin->help ();
+
+	  curr_sym_tab->clear_function (nm);
+
+	  // Move the builtin function out of the way and restore the
+	  // dispatch fuction.  XXX FIXME XXX what if builtin wants to
+	  // protect itself?
+
+	  fbi_sym_tab->rename (nm, "builtin:" + nm);
+	  fbi_sym_tab->rename ("dispatch:" + nm, nm);
+
+	  dispatch->protect ();
+	}
+      else
+	error ("failed to find dispatch record for `builtin:%s'", nm.c_str ());
+    }
+
+  return retval;
 }
 
 static bool
-help_from_symbol_table (std::ostream& os, const std::string& nm)
+help_from_symbol_table (std::ostream& os, const std::string& nm,
+			bool& symbol_found)
 {
   bool retval = false;
 
@@ -755,12 +819,15 @@
 
   if (sym_rec && sym_rec->is_defined ())
     {
+      symbol_found = true;
+
       std::string h = sym_rec->help ();
 
       if (h.length () > 0)
 	{
 	  sym_rec->which (os);
 	  os << "\n";
+	  h = extract_help_from_dispatch (nm) + h;
 	  display_help_text (os, h);
 	  os << "\n";
 	  retval = true;
@@ -771,20 +838,25 @@
 }
 
 static bool
-help_from_file (std::ostream& os, const std::string& nm)
+help_from_file (std::ostream& os, const std::string& nm, bool& symbol_found)
 {
   bool retval = false;
 
-  std::string path = fcn_file_in_path (nm);
+  std::string file = fcn_file_in_path (nm);
 
-  std::string h = get_help_from_file (path);
+  if (file.length () > 0)
+    {
+      symbol_found = true;
+
+      std::string h = get_help_from_file (file);
 
-  if (! h.empty ())
-    {
-      os << nm << " is the file: " << path << "\n\n";
-      display_help_text (os, h);
-      os << "\n";
-      retval = true;
+      if (h.length () > 0)
+	{
+	  os << nm << " is the file: " << file << "\n\n";
+	  display_help_text (os, h);
+	  os << "\n";
+	  retval = true;
+	}
     }
 
   return retval;
@@ -798,20 +870,28 @@
 
   for (int i = 1; i < argc; i++)
     {
-      if (help_from_list (octave_stdout, op_help_list, argv[i], 0))
+      bool symbol_found = false;
+
+      if (help_from_list (octave_stdout, op_help_list, argv[i], 0,
+			  symbol_found))
 	continue;
 
-      if (help_from_list (octave_stdout, kw_help_list, argv[i], 0))
+      if (help_from_list (octave_stdout, kw_help_list, argv[i], 0,
+			  symbol_found))
 	continue;
 
-      if (help_from_symbol_table (octave_stdout, argv[i]))
+      if (help_from_symbol_table (octave_stdout, argv[i], symbol_found))
+	continue;
+
+      if (help_from_file (octave_stdout, argv[i], symbol_found))
 	continue;
 
-      if (help_from_file (octave_stdout, argv[i]))
-	continue;
-
-      octave_stdout << "\nhelp: sorry, `" << argv[i]
-		    << "' is not documented\n"; 
+      if (symbol_found)
+	octave_stdout << "\nhelp: `" << argv[i]
+		      << "' is not documented\n"; 
+      else
+	octave_stdout << "\nhelp: `" << argv[i]
+		      << "' not found\n"; 
     }
 
   additional_help_message (octave_stdout);
diff -r 1b6a837fe24d -r db34dff19947 src/help.h
--- a/src/help.h	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/help.h	Fri Jun 17 21:16:22 2005 +0000
@@ -31,6 +31,8 @@
 
 extern string_vector make_name_list (void);
 
+extern std::string extract_help_from_dispatch (const std::string&);
+
 extern void display_help_text (std::ostream&, const std::string&);
 
 extern void additional_help_message (std::ostream&);
diff -r 1b6a837fe24d -r db34dff19947 src/symtab.cc
--- a/src/symtab.cc	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/symtab.cc	Fri Jun 17 21:16:22 2005 +0000
@@ -662,6 +662,12 @@
 void
 symbol_record::print_info (std::ostream& os, const std::string& prefix) const
 {
+  os << prefix << "formal param:      " << formal_param << "\n"
+     << prefix << "linked to global:  " << linked_to_global << "\n"
+     << prefix << "tagged static:     " << tagged_static << "\n"
+     << prefix << "can hide function: " << can_hide_function << "\n"
+     << prefix << "visible:           " << visible << "\n";
+
   if (definition)
     definition->print_info (os, prefix);
   else
@@ -1154,7 +1160,7 @@
 
       while (ptr)
 	{
-	  if (true || ptr->is_visible ())
+	  if (ptr->is_visible ())
 	    {
 	      assert (count < n);
 
@@ -1167,7 +1173,7 @@
 	      if ((type & my_type) && (scope & my_scope) && (matches_patterns (my_name, pats)))
 		symbols(count++) = ptr;
 	    }
-	      
+
 	  ptr = ptr->next ();
 	}
     }
diff -r 1b6a837fe24d -r db34dff19947 src/symtab.h
--- a/src/symtab.h	Fri Jun 17 15:58:12 2005 +0000
+++ b/src/symtab.h	Fri Jun 17 21:16:22 2005 +0000
@@ -90,7 +90,7 @@
     symbol_def (const octave_value& val = octave_value (),
 		unsigned int sym_type = 0)
       : symbol_type (sym_type), eternal (0), read_only (0), help_string (),
-	definition (val), visible (true), count (1) { }
+	definition (val), count (1) { }
 
     ~symbol_def (void) { }
 
@@ -209,10 +209,6 @@
 
     void make_eternal (void) { eternal = 1; }
 
-    void hide (void) { visible = false; }
-    void show (void) { visible = true; }
-    bool is_visible (void) const { return visible; }
-
     octave_value& def (void) { return definition; }
 
     std::string help (void) const { return help_string; }
@@ -244,9 +240,6 @@
     // The value of this definition.  See ov.h and related files.
     octave_value definition;
 
-    // Should this symbol show up in listings?
-    bool visible;
-
     // Reference count.
     int count;
 
@@ -265,16 +258,18 @@
   typedef int (*change_function) (void);
 
   symbol_record (void)
-    : formal_param (0), linked_to_global (0), tagged_static (0),
-      can_hide_function (1), nm (), chg_fcn (0),
+    : formal_param (false), linked_to_global (false),
+      tagged_static (false), can_hide_function (true),
+      visible (true), nm (), chg_fcn (0),
       definition (new symbol_def ()), next_elem (0) { }
 
   // XXX FIXME XXX -- kluge alert!  We obviously need a better way of
   // handling allow_shadow!
 
   symbol_record (const std::string& n, symbol_record *nxt)
-    : formal_param (0), linked_to_global (0), tagged_static (0),
-      can_hide_function (n != "__end__"), nm (n), chg_fcn (0),
+    : formal_param (false), linked_to_global (false),
+      tagged_static (false), can_hide_function (n != "__end__"),
+      visible (true), nm (n), chg_fcn (0),
       definition (new symbol_def ()), next_elem (nxt) { }
 
   ~symbol_record (void)
@@ -356,9 +351,9 @@
 
   void make_eternal (void) { definition->make_eternal (); }
 
-  void hide (void) { definition->hide (); }
-  void show (void) { definition->show (); }
-  bool is_visible (void) const { return definition->is_visible  (); }
+  void hide (void) { visible = false; }
+  void show (void) { visible = true; }
+  bool is_visible (void) const { return visible; }
 
   void set_change_function (change_function f) { chg_fcn = f; }
 
@@ -444,6 +439,7 @@
   unsigned int linked_to_global : 1;
   unsigned int tagged_static : 1;
   unsigned int can_hide_function : 1;
+  unsigned int visible : 1;
 
   std::string nm;
   change_function chg_fcn;