/usr/share/doc/gnat-gps/html/Hooks.html

<html lang="en">
<head>
<title>Hooks - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Scripting-GPS.html#Scripting-GPS" title="Scripting GPS">
<link rel="prev" href="Python-FAQ.html#Python-FAQ" title="Python FAQ">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="Hooks"></a>
<p>
Previous:&nbsp;<a rel="previous" accesskey="p" href="Python-FAQ.html#Python-FAQ">Python FAQ</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Scripting-GPS.html#Scripting-GPS">Scripting GPS</a>
<hr>
</div>

<h4 class="subsection">16.8.8 Hooks</h4>

<p><a name="index-hooks-900"></a><!--  -->

<p class="noindent">A <b>hook</b> is a named set of commands to be executed on particular occasions
as a result of user actions in GPS.

   <p>GPS and its various modules define a number of standard hooks, which are
called for instance when a new project is loaded, when a file is edited, and
so on. You can define your own commands to be executed in such cases.

   <p><a name="index-hooks_002c-Hook_002elist-901"></a><a name="index-hooks_002c-Hook_002edescribe-902"></a>You can find out the list of hooks that GPS currently knows about by calling
the <b>Hook.list</b> function, which takes no argument, and returns a list of
hook names that you can use. More advanced description for each hook is
available through the <code>Help-&gt;Python Extensions</code>.

<pre class="smallexample">     GPS&gt; Hook.list
     project_changed
     open_file_action_hook
     preferences_changed
     [...]
     
     Python&gt; GPS.Hook.list()
</pre>
   <p><a name="index-hooks_002c-type-903"></a>The description of each hooks includes a pointer to the type of the hook, that
is what parameters the subprograms in this hook will receive. For instance:

   <p><a name="index-hooks_002c-Hook_002elist_005ftypes-904"></a>The list of all known hook types can be found through the <b>Hook.list_types</b>
command. This takes no argument and returns a list of all known types of hooks. 
As before, you can more information for each of these type through a call to
<b>Hook.describe_type</b>.

<!--  -->
<h5 class="subsubsection">16.8.8.1 Adding commands to hooks</h5>

<!--  -->
<p class="noindent">You can add your own command to existing hooks through a call to the
<b>Hook.add</b> command. Whenever the hook is executed by GPS or another script,
your command will also be executed, and will be given the parameters that
were specified when the hook is run. The first parameter is always the name
of the hook being executed.

   <p>This <b>Hook.add</b> applies to an instance of the hook class, and takes one
parameter, the command to be executed. This is a subprogram parameter (see <a href="Subprogram-parameters.html#Subprogram-parameters">Subprogram parameters</a>).

     <ul>
<li>GPS shell

     <p>The command can be any GPS action (see <a href="Defining-Actions.html#Defining-Actions">Defining Actions</a>). The arguments for
the hook will be passed to the action, and are available as $1, $2, <small class="dots">...</small>;
In the following example, the message "Just executed
the hook: project_changed" will be printed in the Shell console. Note that we
are defining the action to be executed inline, but this could in fact be
defined in a separate XML customization file for convenience.

     <pre class="smallexample">          GPS&gt; parse_xml """&lt;action name="my_action"&gt;&lt;shell&gt;echo "Just executed the hook"&lt;/shell&gt;&lt;/action_name&gt;"""
          GPS&gt; Hook project_changed
          GPS&gt; Hook.add %1 "my_action"
</pre>
     <li>Python

     <p>The command must be a subprogram to execute. The arguments for the
hook will be passed to this subprogram. In the following example, the
message "The hook project_changed was executed by GPS" will be displayed in the
Python console whenever the project changes.

     <pre class="smallexample">          def my_callback (name):
              print "The hook " + name + " was executed by GPS"
          GPS.Hook ("project_changed").add (my_callback)
</pre>
     </ul>

   <p>The example above shows the simplest type of hook, which doesn't take any
argument. However, most hooks receive several parameters. For instance, the
hook "file_edited" receives the file name as a parameter.

     <ul>
<li>GPS shell

     <p>The following code will print the name of the hook ("file_edited") and the
name of the file in the shell console every time a file is open by GPS.
     <pre class="smallexample">          GPS&gt; parse_xml """&lt;action name="my_action"&gt;&lt;shell&gt;echo name=$1 file=$2&lt;/shell&gt;&lt;/action&gt;"""
          GPS&gt; Hook "file_edited"
          GPS&gt; Hook.add %1 "my_action"
</pre>
     <li>Python

     <p>The following code prints the name of the file being edited by GPS in the
python console whenever a new editor is opened. The second argument is of type
GPS.File.

     <pre class="smallexample">          def my_file_callback (name, file):
              print "Editing " + file.name()
          GPS.Hook ("file_edited").add (my_file_callback)
</pre>
     </ul>

<!--  -->
<h5 class="subsubsection">16.8.8.2 Action hooks</h5>

<p><a name="index-hooks_002c-action_005fhooks-905"></a><a name="index-hooks_002c-open_005ffile_005faction_005fhook-906"></a><!--  -->

<p class="noindent">Some hooks have a special use in GPS. Their name always ends with
"_action_hook".

   <p>As opposed to the standard hooks described in the previous section, the
execution of the action hooks stops as soon as one of the subprograms returns
a True value ("1" or "true"). The subprograms associated with that hook are
executed one after the other. If any such subprogram knows how to act for that
hook, it should do the appropriate action and return "1".

   <p>Other action hooks expect a string as a return value instead of a boolean. The
execution will stop when a subprogram returns a non-empty string.

   <p>This mechanism is used extensively by GPS internally. For instance, whenever
a file needs to be opened in an editor, GPS executes the
"open_file_action_hook" hook to request its editing. Several modules are
connected to that hook.

   <p>One of the first modules to be executed is the external editor module. If the
user has chosen to use an external editor, this module will simply spawn
Emacs or the external editor that the user has selected, and return 1. This
immediately stops the execution of the "open_file_action_hook".

   <p>However, if the user doesn't want to use external editors, this module will
return 0. This will keep executing the hook, and in particular will execute the
source editor module, which will always act and open an editor internally in
GPS.

   <p>This is a very flexible mechanism. In your own script, you could choose to
have some special handling for files with a ".foo" extension for instance. If
the user wants to open such a file, you would spawn for instance an external
command (say "my_editor") on this file, instead of opening it in GPS.

   <p>This is done with a code similar to the following

<pre class="smallexample">     from os.path import *
     import os
     def my_foo_handler (name, file, line, column, \
                         column_end, enable_nav, new_file, reload):
         if splitext (file.name())[1] == ".foo":
             os.spawnv \
                (os.P_NOWAIT, "/usr/bin/emacs", ("emacs", file.name()))
             return 1   ## Prevent further execution of the hook
         return 0  ## Let other subprograms in the hook do their job
     
     GPS.Hook ("open_file_action_hook").add (my_foo_handler)
</pre>
   <!--  -->
<h5 class="subsubsection">16.8.8.3 Running hooks</h5>

<p><a name="index-hooks_002c-Hook_002erun-907"></a><!--  -->

<p class="noindent">Any module in GPS is responsible for running the hooks when appropriate. 
Most of the time, the subprograms exported by GPS to the scripting languages
will properly run the hook. But you might also need to run them in your own
scripts.

   <p>As usual, this will result in the execution of all the functions bound to
that hook, whether they are defined in Ada or in any of the scripting
languages.

   <p>This is done through the <b>Hook.run</b> command. This applies to an instance
of the Hook class, and a variable number of arguments
These must be in the right order and of the right type
for that specific type of hook.

   <p>If you are running an action hook, the execution will stop as usual as soon
as one of the subprograms return a True value.

   <p>The following example shows how to run a simple hook with no parameter, and
a more complex hook with several parameters. The latter will in fact request
the opening of an editor for the file in GPS, and thus has an immediately
visible effect on the interface. The file is opened at line 100. See the
description of the hook for more information on the other parameters.

<pre class="smallexample">     GPS.Hook ("project_changed").run()
     GPS.Hook ("open_file_action_hook").run \
                   (GPS.File ("test.adb"), 100, 1, 0, 1, 1, 1)
</pre>
   <!--  -->
<h5 class="subsubsection">16.8.8.4 Creating new hooks</h5>

<p><a name="index-hooks_002c-creating-908"></a><a name="index-hooks_002c-Hook_002eregister-909"></a><!--  -->

<p class="noindent">The list of hooks known to GPS is fully dynamic. GPS itself declares a
number of hooks, mostly for its internal use although of course you can
also connect to them.

   <p>But you can also create your own hooks to report events happening in your
own modules and programs. This way, any other script or GPS module can
react to these events.

   <p>Such hooks can either be of a type exported by GPS, which constraints the
list of parameters for the callbacks, but make such hooks more portable and
secure; or they can be of a general type, which allows basically any kind
of parameters. In the latter case, checks are done at runtime to ensure that
the subprogram that is called as a result of running the hook has the right
number of parameters. If this isn't the case, GPS will complain and display
error messages. Such general hooks will also not pass their parameters to
other scripting languages.

   <p>Creating new hooks is done through a call to <b>Hook.register</b>. This function
takes two arguments: the name of the hook you are creating,
and the type of the hook.

   <p>The name of the hook is left to you. Any character is allowed in that name,
although using only alphanumerical characters is recommended.

   <p>The type of the hook must be one of the following:

     <ul>
<li>"" (the empty string)

     <p>This indicates that the hook doesn't take any argument. None should be given
to <b>Hook.run</b>, and none should be
expected by the various commands connected to that hook, apart from
the hook name itself.

     <li>one of the values returned by <b>Hook.list_types</b>

     <p>This indicates that the hook is of one of the types exported by GPS itself. The
advantage of using such explicit types as opposed to "general" is that GPS
is able to make more tests for the validity of the parameters. Such hooks can
also be connected to from other scripting languages.

     <li>"general"

     <p>This indicates that the hook is of the general type that allows any number of
parameter, of any type. Other scripts will be able to connect to it, but will
not be executed when the hook is run if they do not expect the same number of
parameters that was given to <b>Hook.run</b>. Other scripts in other language will
only receive the hook name in parameter, not the full list of parameters.

   </ul>

   <p>A small trick worth noting: if the command bound to a hook doesn't have the
right number of parameters that this hook provide, the command will not be
executed and GPS will report an error. You can make sure that your command
will always be executed by either giving default values for its parameter, or
by using python's syntax to indicate a variable number of arguments.

   <p>This is especially useful if you are connecting to a "general" hook, since you
do not really know in advance how many parameters the call of <b>Hook.run</b> will
provide.

<pre class="smallexample">     ## This callback can be connected to any type of hook
     def trace (name, *args):
        print "hook=" + name
     
     ## This callback can be connected to hooks with one or two parameters
     def trace2 (name, arg1, arg2=100):
        print "hook=" + str (arg1) + str (arg2)
     
     Hook.register ("my_custom_hook", "general")
     Hook ("my_custom_hook").add (trace2)
     Hook ("my_custom_hook").run (1, 2) ## Prints 1 2
     Hook ("my_custom_hook").run (1)    ## Prints 1 100
</pre>
   <!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / Hooks.html
