%% help.sl

%% apropos function
define apropos ()
{
   variable n, cbuf, s;
   if (MINIBUFFER_ACTIVE) return;

   s = read_mini("apropos:", "", "");
   n = _apropos(s, 0xF);
   cbuf = whatbuf();
   pop2buf("*apropos*");
   erase_buffer();
   loop (n) 
     {
	insert(());
	newline();
     }
   buffer_format_in_columns();   
   bob();
   set_buffer_modified_flag(0);
   pop2buf(cbuf);
}

%!% Prototype: String expand_keystring (String key)
%!% This function takes a key string that is suitable for use in a 'setkey'
%!% definition and expands it to a human readable form.  
%!% For example, it expands ^X to the form "Ctrl-X", ^[ to "ESC", 
%!% ^[[A to "UP", etc...
%!% See also: setkey
define expand_keystring (key)
{
   variable n = strlen (key);
   variable str, i = 1, ch, key_string = "", the_key;
   
   while (i <= n)
     {
	ch = key[i - 1];
	++i;
	switch (ch)
	  {
	     (case '^' and (i <= n)) or (ch < 32) :   
	     % control char
	     %% common cases are '^[, ^[[?, ^[O?'
	  
	     if (ch < 32)
	       {
		  str = char (ch + '@') + substr (key, i, 2);
		  i--;
	       }
	     else str = substr (key, i, 3);
	     
	     if (int(str) == '[')
	       {
		  i += 3;
		  switch (str)
		    { case "[[A" : "UP"; }
		    { case "[[B" : "DOWN"; }
		    { case "[[C" : "RIGHT"; }
		    { case "[[D" : "LEFT"; }
		    { case "[OP" : "GOLD"; }
		    { case "[OA" : "UP"; }
		    { case "[OB" : "DOWN"; }
		    { case "[OC" : "RIGHT"; }
		    { case "[OD" : "LEFT"; }
		    { "ESC"; i -= 2; }
	       }
	     else
	       {
		  i++;
		  "Ctrl-" + char(int(str));
	       }
	  }
	  {
	     char (ch);
	  }
	the_key = ();
	
	if (strlen(key_string)) key_string += " ";
	key_string += the_key;
     }
   
   key_string;
}


%% show key
define showkey()
{
   variable f, type, the_type = "internal";
   flush("Show Key: ");
   f = get_key_function();        %% also, type is on stack (if defined)
   !if (strlen(f)) 
     {
	vmessage ("Key \"%s\" is undefined.",
		  expand_keystring (LASTKEY));
	return;
     }
   type = ();
   
   !if (type) the_type = "S-Lang";
   
   vmessage ("Key \"%s\" runs %s function %s.", expand_keystring(LASTKEY),
	     the_type, f);
}

define where_is ()
{
   variable n, cmd;
   if (MINIBUFFER_ACTIVE) return;
   
   cmd = read_with_completion ("Where is command:", "", "", 'F');
   !if (strlen (cmd)) return;
   n = which_key (cmd);
   !if (n) return message ("Not on any keys.");
   
   message (expand_keystring ());
   --n; loop (n) pop ();
}


define help_get_doc_string (f)
{
   variable file;
   variable n, str;
   
   n = 0;
   str = NULL;
   do
     {
	file = extract_element (Jed_Doc_Files, n, ',');
	if (file == NULL)
	  break;
	
	str = get_doc_string_from_file (file, f);
	n++;
     }
   while (str == NULL);
   
   return (file, str);
}

define help_for_function (f)
{
   variable cbuf = whatbuf ();
   variable tmp = " *jed-help*";
   variable help = "*function-help*";
   variable doc_str, file;
   
   pop2buf (help); set_readonly (0); erase_buffer ();
  
   if (is_defined (f) < 0)
     vinsert ("%s: Value: %s\n", f, string (eval ("." + f)));
   
   (file, doc_str) = help_get_doc_string (f);
   if (doc_str == NULL)
     {
	vinsert ("%s: Undocumented", f);
	!if (is_defined (f)) insert (" and unknown");
     }
   else
     vinsert ("%s[Obtained from file %s]", doc_str, file);

   insert ("\n-----------------------------------\n");
   
   bob ();
   pop2buf (cbuf);
}

define help_do_help_for_object (prompt, flags)
{
   variable n, objs;
   
   if (MINIBUFFER_ACTIVE) return;

#ifntrue
   n = _apropos ("", flags);
   
   objs = "";
   loop (n)
     {
	objs = () + "," + objs;
     }
#else
   objs = create_delimited_string (",", _apropos ("", flags));
#endif
   help_for_function (read_string_with_completion (prompt, "", objs));
}

   
define describe_function ()
{
   help_do_help_for_object ("Describe Function:", 0x3);
}

define describe_variable ()
{
   help_do_help_for_object ("Describe Variable:", 0xC);
}


define describe_mode ()
{
   variable flags, modstr;
   (modstr, flags) = what_mode ();
   
   modstr = extract_element (modstr, 0, ' ');
   !if (strlen (modstr)) modstr = "no";
   !if (is_defined (modstr))
     {
	modstr = strlow (modstr);
	!if (is_defined (modstr))
	  {
	     modstr += "_mode";
	     !if (is_defined (modstr))
	       error ("Mode is not defined: " +  modstr);
	  }
     }
   help_for_function (modstr);
}


define describe_bindings ()
{
   flush("Building bindings..");
   variable map = what_keymap ();
   variable buf = whatbuf ();
   variable cse = CASE_SEARCH;  CASE_SEARCH = 1;
   pop2buf("*KeyBindings*");
   erase_buffer ();
   dump_bindings (map);
   bob(); replace ("ESC [ A", "UP");
   bob(); replace ("ESC [ B", "DOWN");
   bob(); replace ("ESC [ C", "RIGHT");
   bob(); replace ("ESC [ D", "LEFT");
   bob(); replace ("ESC O P", "GOLD");
   bob();
   CASE_SEARCH = cse;
   set_buffer_modified_flag(0);
   pop2buf (buf);
   message ("done");
}