home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / jed098-4.zip / JED / DOC / HOOKS.TXT < prev    next >
Text File  |  1997-02-01  |  11KB  |  318 lines
  1. This file documents the various hooks for extending JED.
  2.  
  3. A `hook' is simply a user defined S-Lang function that may be used to extend
  4. the editor or to modify how it behaves under certain circumstances.  There
  5. are two kinds of hooks that vary according to whether the hook is called
  6. ``internally'' from the editor by the underlying C code or whether the hook
  7. is called from another S-Lang routine.  The hooks may be subdivided further
  8. according to their scope.  They may apply to all buffers (globally), only
  9. buffers sharing the same mode (modal), or to a single buffer (local).
  10.  
  11. Global Hooks.
  12.  
  13.    The global hooks affect all buffers.  They are:
  14.  
  15.      1. `command_line_hook': This hook is called from within the editor to
  16.     parse the command line arguments.  It is defined in the file
  17.     `site.sl' and cannot be customized by the user.  However, the it may
  18.     be customized by the system manager.  In addition to parsing the
  19.     command line arguments the default value of this hook also loads the
  20.     user's personal initialization file.
  21.      
  22.      2. `jed_startup_hook':  Although this function is defined in `site.sl',
  23.     it can be changed by a user because it is called after the user
  24.     initialization file is loaded.  This hook is called just prior to
  25.     the main editing loop of the editor.  It also calls the hook
  26.     `startup_hook' which may be defined by the user as a convenient way
  27.     to customize `jed_startup_hook'.  See `exit_hook' for an example of
  28.     how this may be exploited.
  29.     
  30.      3. `exit_hook':  This hook is called when the intrinsic function
  31.     `exit_jed' is called.  Although it has no default definition does
  32.     not mean that it is not useful.  For example, one could use:
  33.     
  34.     define exit_hook()
  35.     {
  36.        variable ch;
  37.        if (BATCH) exit_jed();
  38.        
  39.        flush("Really Exit? ");
  40.        ch = getkey();
  41.        if ((ch == 'Y') || (ch == 'y')) exit_jed ();
  42.        error ("Aborted!");
  43.         }
  44.  
  45.        to confirm the exit.  Note also that although `exit_jed' calls this
  46.        function, `exit_hook' will not be called again if it int turn calls
  47.        `exit_jed'.
  48.        
  49.        Also, for MSDOS it might be desirable for the editor to exit in the
  50.        same directory that it started.  This will work:
  51.        
  52.           define exit_hook()
  53.       {
  54.          variable dir;
  55.          if (bufferp("*scratch*"))
  56.            {
  57.               sw2buf("*scratch*");
  58.           (,dir,,) = getbuf_info();
  59.           change_default_dir(dir); pop();
  60.            }
  61.          call( "exit_jed" );
  62.       }
  63.  
  64.        Like many hooks, if an error is generated by the hook, the function
  65.        that called it will fail and the operation will be aborted.
  66.        
  67.        Finally, `exit_hook' and `startup_hook' may be used together to
  68.        implement a way of saving the state of the editor.  A minimal
  69.        implementation might be:
  70.        
  71.            variable Jed_State_File = dircat (getenv ("HOME"), ".jedstate");
  72.  
  73.            define exit_hook ()
  74.        {
  75.          variable file = buffer_filename ();
  76.          variable cmd;
  77.          
  78.          if (strlen (file))
  79.            {
  80.               % This is mainly for MSDOS to fix the backslash character
  81.           % used for path names.
  82.               file = str_quote_string (file, "\\", '\\');
  83.           
  84.           cmd = Sprintf ("() = find_file (\"%s\");", file, 1);
  85.           cmd = Sprintf ("%s\ngoto_line (%d); goto_column (%d);",
  86.                           cmd, whatline (), what_column (), 3);
  87.  
  88.           () = write_string_to_file (cmd, Jed_State_File); 
  89.            }
  90.          exit_jed ();
  91.        }
  92.        
  93.        define startup_hook ()
  94.        {
  95.           if (1 == file_status (Jed_State_File))
  96.             {
  97.           () = evalfile (Jed_State_File);
  98.           () = delete_file (Jed_State_File);
  99.             }
  100.        }
  101.        
  102.        
  103.         
  104.     4. `suspend_hook': This hook has no default value and is called just
  105.        before suspending the editor.  One might use it as a simple way of
  106.        prohibiting suspension, e.g.,
  107.        
  108.            define suspend_hook ()
  109.        {
  110.           error ("Suspending not allowed.");
  111.        }
  112.  
  113.     5. `resume_hook': It is called immediately after JED resumes after being
  114.        suspended.  This hook is predefined only on VMS systems.  This does
  115.        not mean that it cannot be used on other systems as well.  For
  116.        example, here is a silly use
  117.  
  118.            define resume_hook ()
  119.        {
  120.           message ("Welcome back!");
  121.        }
  122.        
  123.        but I am sure that you will think of something more clever.
  124.        
  125.     6. `mode_hook':  Immediately after JED loads a file into a buffer, it
  126.        calls `mode_hook' to set the mode of the buffer.  The default value
  127.        is defined in `site.sl'.  This hook is called with with the file name
  128.        extension of the file as its only parameter.  This function sets the
  129.        mode of the buffer based on the value of the file name extension.
  130.        
  131.        There are several ways to customize this hook.  The easiest is to
  132.        simply call the function `add_mode_for_extension' with the mode that
  133.        is to be associated with a particular extension.  For example,
  134.        suppose that you edit files with names like `main.c++'.  To have
  135.        `c_mode' associated with files of this type, simply call:
  136.        
  137.           add_mode_for_extension ("c", "c++");
  138.       
  139.        The important point to realize is that the first parameter is the
  140.        name of the mode but it should not include the `_mode' part of the
  141.        mode name.
  142.        
  143.        The other way to customize mode_hook is through the function pointer
  144.        `mode_hook_pointer' which the user can define to set the mode.  If
  145.        the function pointed to by `mode_hook_pointer' returns non-zero,
  146.        `mode_hook' will return to the calling routine.  Specifically, the
  147.        default value of `mode_hook' looks like:
  148.  
  149.            define mode_hook (ext)
  150.        {
  151.           if (mode_hook_pointer (ext)) return;
  152.           .
  153.           .
  154.        }
  155.        
  156.        One could simple point `mode_hook_pointer' to something like:
  157.        
  158.            define set_no_mode (ext)
  159.        {
  160.           return 1;
  161.        }
  162.        mode_hook_pointer = &set_no_mode;
  163.        
  164.        Typically, one would do something useful like:
  165.        
  166.           define my_mode_hook (ext)
  167.       {
  168.          if (strcmp ("pas", ext)) return 0;
  169.          my_pascal_mode ();
  170.          return 1;
  171.       }
  172.       mode_hook_pointer = &my_mode_hook;
  173.       
  174.        Here `my_pascal_mode' is a hypothetical pascal mode.
  175.        
  176.        As a final example, consider the case where one would like to set the
  177.        mode based on the filename and NOT the extension.  For example, the
  178.        Elm mailer user files of the form `snd.XXX' and one would like to use
  179.        text mode on such files.  Again, the solution is to use the
  180.        `mode_hook_pointer':
  181.        
  182.           define my_mode_hook (ext)
  183.       {
  184.          variable file;
  185.          (file,,,) = getbuf_info ();
  186.          if (0 != strncmp (file, "snd.", 4)) return 0;
  187.          text_mode ();
  188.          return 1;
  189.       }
  190.       mode_hook_pointer = &my_mode_hook;
  191.       
  192.        Finally, the global variable `Default_Mode' may be pointed to a
  193.        function to set the mode if a suitable mode was not obtained from the
  194.        extension.  By default, it has the value:
  195.        
  196.            Default_Mode = &text_mode;
  197.        
  198.  
  199.       
  200.     7. `find_file_hook':  This hook is called after a file is read into the
  201.        editor via the internal function `find_file'.  It is passed the full
  202.        filename of the file read into the buffer.  The supplied default for
  203.        this function simply looks for an autosave file and warns the user 
  204.        if it should be used instead.  It might also be used to preprocess
  205.        the buffer before the user starts to edit it.
  206.        
  207.           *** Note: This hook will most like be changed such that it is
  208.                 called beore the file is read in.
  209.  
  210.     8. `format_paragraph_hook': This hook is called after a paragraph is
  211.        formatted but only if the a prefix argument was given prior to the
  212.        execution of the internal function `format_paragraph'.  That is, the
  213.        default binding of `format_paragraph' is `ESC q'.  Pressing `ESC 1'
  214.        immediately before pressing `ESC q' will format the paragraph and
  215.        then call `format_paragraph_hook'.  The default definition for this
  216.        hook left and right justifies the paragraph.
  217.  
  218.     9. `is_paragraph_separator': This hook is called by the editor to locate
  219.        paragraph delimeters.  If defined, it applies globally to all buffers
  220.        except those which have a local definition (see the `par_sep' hook).
  221.        The default value is coded in C and basically reduces to:
  222.        
  223.        define is_paragraph_separator ()
  224.        {
  225.          bol();
  226.      if (looking_at("\\") or looking_at("%")) return (1);
  227.          skip_white();
  228.      return (eolp());
  229.        }
  230.  
  231.        which is useful for TeX mode.  The hook must simply return a non-zero
  232.        value if the current line is a paragraph delimeter or zero if it is
  233.        not.
  234.  
  235.  
  236. Mode Hooks:
  237.  
  238.   These are hooks that get called when the editor enters a particular
  239.   mode.  Usually, one just wants to defined keys.  For this purpose, use the
  240.   `local_setkey' function.
  241.   
  242.   1. `tex_mode_hook':  This hook is called when JED starts its TeX mode.
  243.       Use it to bind certain functions that either have no binding or have
  244.       one that you do not like, e.g.,
  245.       
  246.          define tex_mode_hook ()
  247.      {
  248.         local_unsetkey ("^C");
  249.         local_setkey ("latex_do_environment", "^C^E");
  250.         local_setkey (" \\alpha", "^Ca");
  251.         local_setkey (" \\Alpha", "^CA");
  252.         local_setkey (" \\Beta",  "^CB");
  253.         local_setkey (" \\beta",  "^Cb");
  254.         % etc...
  255.      }
  256.       
  257.       Notice that in this hook, I have simply set keys `Ctrl-C a', etc... to
  258.       insert `\alpha', etc...
  259.       
  260.   2. c_mode_hook
  261.   3. fortran_hook
  262.   4. text_mode_hook
  263.   5. mail_hook
  264.   
  265.        A useful hook here is to defined Ctrl-C Ctrl-C to send the message al
  266.        la emacs:
  267.        
  268.            define mail_hook ()
  269.        {
  270.           local_unsetkey ("^C");
  271.           local_setkey ("send", "^C^C");
  272.        }
  273.  
  274.   6. slang_mode_hook
  275.   7. dired_mode_hook
  276.   8. fortran_hook
  277.   
  278. Local hooks:
  279.   
  280.    These hooks apply to individual buffers.  They must be ``declared'' to
  281.    the buffer using the intrinsic function `set_buffer_hook'.
  282.    
  283.       1. `par_sep': function used to determine where paragraph boundaries
  284.          are.  See the hook `is_paragraph_separator' for more information.
  285.      
  286.       2. `indent_hook': function called after a line is indented by the
  287.          function `indent_line'.
  288.      
  289.       3. `wrap_hook': function called after a line is wrapped.  For example,
  290.          in writing this document, I want the lines following the numbers to
  291.      be offset some.  So I wrote:
  292.      
  293.            define text_mode_wrap_hook ()
  294.            {
  295.               variable p;
  296.               push_spot ();
  297.           go_up(1); bol (); skip_white ();
  298.           p = POINT;
  299.           skip_chars ("0-9"); 
  300.           if ((p != POINT) and looking_at (". "))
  301.             {
  302.                go_down(1); bol (); skip_white ();
  303.                p = what_column ();
  304.                bol (); trim ();
  305.                whitespace (p + 3);
  306.             }
  307.           pop_spot ();
  308.            }
  309.            
  310.      In fact, I always use this in text_mode so I put in in my
  311.      `text_mode_hook':
  312.      
  313.           define text_mode_hook ()
  314.           {
  315.              set_buffer_hook ("wrap_hook", "text_mode_wrap_hook");
  316.           }
  317.  
  318.