gnat-gps-common 5.0-16 / usr / share / gps / shell_commands.xml

<?xml version="1.0" ?>

<!--  This file contains the documentation of all the shell commands that
      are exported by GPS.
      We avoid hard-coded descriptions, so that it is easier to translate the
      GPS help, and to check the spelling in the documentation.
      User can also add their own knowledge database

      To insert explicit '<' characters, you need to either follow them with a
      space or a comma ',', or double them as  &lt;&lt;
      Same for '>' character
  -->

<docs>
  <shell_doc name="GPS">
     <description>This package groups all the classes and functions exported by the GNAT Programming System.

These functions are made available through various programming languages (Python and the GPS shell at the moment). The documentation in this package is mostly oriented towards Python, but it can also be used as a reference for the GPS shell.

&lt;b&gt;Functions description&lt;/b&gt;

For all functions, the list of parameters is given. The first parameter will often be called "self", and refers to the instance of the class to which the method applies. In Python, the parameter is generally put before the method's name,
as in:</description>
     <example lang="python">
	self.method (arg1, arg2)
     </example>
     <description>Although it could also be called as in:</description>
     <example lang="python">
	method (self, arg1, arg2)
     </example>
     <description>For all other parameters, their name and type are specified. An additional default value is given when the parameter is optional. If no default value is specified, the parameter is mandatory and should always be specified. The name of the parameter is relevant if you chose to use Python's named parameters feature, as
in:</description>
     <example lang="python">
	self.method (arg1="value1", arg2="value2")
     </example>
     <description>which makes the call slightly more readable. The method above would be defined with three parameters in this documentation (resp. "self", "arg1" and "arg2").

Some examples are also provides for several functions, to help clarify the use of the function.

&lt;b&gt;User data in instances&lt;/b&gt;

A very useful feature of python is that all class instances can be associated with any number of user data fields. For example, if you create an instance of
the class GPS.EditorBuffer, you can associate two fields "field1" and "field2" to it (the names and number are purely for demonstration purposes, and you can use your own), as in:</description>
     <example lang="python">
	ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
	ed.field1 = "value1"
	ed.field2 = 2
     </example>
     <description>GPS takes great care for most classes of always returning the same python instance for a given GUI object. For instance, if you were to get another instance of GPS.EditorBuffer for the same file as above, you would in fact receive the same Python instance, and thus the two fields are available to you, as in:</description>
     <example lang="python">
	ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
	# ed.field1 is still "value1"
     </example>
     <description>This is a very convenient way to store your own data associated with the various objects exported by GPS. These data will cease to exist when the GPS object itself is destroyed (for instance when the editor is closed in the example above).

&lt;b&gt;Hooks&lt;/b&gt;

In a lot of cases, you will need to connect to specific hooks exported by GPS to be aware of events happening in GPS (loading of a file, closing a file,...). These hooks and their use are described in the GPS manual. </description>
  </shell_doc>

  <!--#################################################################
      ### Hooks
      #################################################################-->

  <shell_doc name="@hooks_list@">
     <description>GPS defines a number of hooks which are called when specific events occur in GPS. Using the hooks is fully described in the GPS user manual.</description>
     <example lang="python">
Here is a small example, where the function on_gps_started is called
when the GPS window is fully visible to the user:
     import GPS
     def on_gps_started (hook):
        pass
     GPS.Hook ("gps_started").add (on_gps_started)
</example>
     <description>The list of parameters for the hooks is described for each hook below. The first parameter is always the name of the hook, so that the same function can be used for multiple hooks if necessary</description>
     <description>There are two categories of hooks: the standard hooks and the action hooks. The former return nothing, the latter return a boolean indicating whether your callback was able to perform the requested action. They are used to override some of GPS's internal behavior</description>
  </shell_doc>

  <shell_doc name="@hook@ bookmark_added">
     <param name="hook">A string, the name of the hook</param>
     <param name="bookmark_name">A string, the name of the bookmark that has been added</param>
     <description>Hook called when a new bookmark has been created by the user</description>
  </shell_doc>

  <shell_doc name="@hook@ bookmark_removed">
     <param name="hook">A string, the name of the hook</param>
     <param name="bookmark_name">A string, the name of the bookmark that has been removed</param>
     <description>Hook called when a new bookmark has been removed by the user</description>
  </shell_doc>

  <shell_doc name="@hook@ build_server_connected_hook">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when GPS connects to the build server in remote mode</description>
  </shell_doc>

  <shell_doc name="@hook@ preferences_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the value of some of the preferences changes. Modules should refresh themselves dynamically</description>
  </shell_doc>

  <shell_doc name="@hook@ contextual_menu_open">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called just before a contextual menu is created. It is called before any of the filters is evaluated, and can be used to precomputed data shared by multiple filters to speed up the computation. Use GPS.contextual_context() to get the context of the contextual menu and store precomputed data in it.</description>
     <see_also name="contextual_menu_close hook" />
  </shell_doc>

  <shell_doc name="@hook@ contextual_menu_close">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called just before a contextual menu is destroyed. At this time, the value returned by GPS.contextual_context() is still the one used in the hook contextual_menu_open, and therefore you can still reference the data you stored in the context. This hook is called even if no action was selected by the user. However, it is always called before the action is executed, since the menu itself is closed first.</description>
     <see_also name="contextual_menu_open hook" />
  </shell_doc>

  <shell_doc name="@hook@ search_reset">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the current search pattern is reset or changed by the user, or when the current search is no longer possible because the setup of GPS has changed.</description>
  </shell_doc>

  <shell_doc name="@hook@ search_functions_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the list of registered search functions changes.</description>
  </shell_doc>

  <shell_doc name="@hook@ search_regexps_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when a new regexp has been added to the list of predefined search patterns</description>
  </shell_doc>

  <shell_doc name="@hook@ variable_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when one of the scenario variables has been renamed, removed or when one of its possible values has changed.</description>
  </shell_doc>

  <shell_doc name="@hook@ clipboard_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the contents of the clipboard has changed, either because the user has done a Copy or Cut operation, or because he called Paste Previous which changes the current entry in the multi-level clipboard.</description>
  </shell_doc>

  <shell_doc name="@hook@ project_view_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the project view has been changed, for instance because one of the environment variables has changed. This means that the list of directories, files or switches might now be different. In the callbacks for this hook, you can safely query the new attribute values.</description>
  </shell_doc>

  <shell_doc name="@hook@ project_changing">
    <param name="hook">A string, the name of the hook</param>
    <param name="file">An instance of GPS.File</param>
    <description>Hook called just before a new project is loaded.</description>
  </shell_doc>

  <shell_doc name="@hook@ project_changed">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when the project has changed. A new project has been loaded, and all previous settings and caches are now obsolete. In the callbacks for this hook, the attribute values have not been computed from the project yet, and will only return the default values. Connect to the project_view_changed hook instead to query the actual values</description>
     <see_also name="@hook@ project_view_changed" />
  </shell_doc>

  <shell_doc name="@hook@ project_saved">
     <param name="hook">A string, the name of the hook</param>
     <param name="project">An instance of GPS.Project</param>
     <description>Hook called when a project is saved to disk. It is called for each project in the hierarchy</description>
  </shell_doc>

  <shell_doc name="@hook@ project_editor">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called before the Project Editor is opened. This allows a custom module to perform specific actions before the actual creation of this dialog.</description>
  </shell_doc>

  <shell_doc name="@hook@ context_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="context">An instance of GPS.Context</param>
     <description>Hook called when the current context changes in GPS, ie a new file is selected, or a new entity, or a new window,...</description>
  </shell_doc>

  <shell_doc name="@hook@ source_lines_revealed">
     <param name="hook">A string, the name of the hook</param>
     <param name="context">An instance of GPS.Context</param>
     <description>Hook called when a range of line becomes visible on the screen</description>
  </shell_doc>

  <shell_doc name="@hook@ file_edited">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called when a file editor has been opened for a file that wasn't already opened before. Do not confuse with the hook open_file_action, which is used to request the opening of a file.</description>
     <see_also name="open_file_action hook" />
  </shell_doc>

  <shell_doc name="@hook@ file_closed">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called just before the last editor for a file is closed. You can still use EditorBuffer.get() and current_view() to access the last editor for file.</description>
  </shell_doc>

  <shell_doc name="@hook@ before_file_saved">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called right before a file is saved</description>
  </shell_doc>

  <shell_doc name="@hook@ file_saved">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called whenever a file has been saved</description>
  </shell_doc>

  <shell_doc name="@hook@ buffer_edited">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called after the user has stopped modifying the contents of an editor</description>
  </shell_doc>

  <shell_doc name="@hook@ file_changed_detected">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <return>A boolean</return>
     <description>Hook called whenever GPS detects that an opened file changed on the disk. You can connect to this hook if you want to change the default behavior, which is asking if the user wants to reload the file. Your function should return 1 if the action is handled by the function, and return 0 if the default behavior is desired.</description>
     <example lang="python">
import GPS

def on_file_changed (hook, file):
    # automatically reload the file without prompting the user
    ed = GPS.EditorBuffer.get (file, force = 1)
    return 1

# install a handler on "file_changed_detected" hook
GPS.Hook ("file_changed_detected").add (on_file_changed)
     </example>
  </shell_doc>

  <shell_doc name="@hook@ file_changed_on_disk">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called when some external action has changed the contents of a file on the disk, such as a VCS operation. The parameter might be a directory instead of a file, indicating that any file in that directory might have changed</description>
  </shell_doc>

  <shell_doc name="@hook@ file_deleted">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called whenever GPS detects that a file was deleted on the disk. The parameter might be a directory instead of a file, indicating that any file within that directory has been deleted.</description>
  </shell_doc>

  <shell_doc name="@hook@ file_renamed">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="renamed">An instance of GPS.File</param>
     <description>Hook called whenever a GPS action renamed a file on the disk. The file parameter indicates the initial location of the file, while the renamed parameter indicates the new location. The parameters might be directories instead of files, indicating that the directory has been renamed, and thus any file within that directory have their path changed.</description>
  </shell_doc>

  <shell_doc name="@hook@ compilation_starting">
     <param name="hook">A string, the name of the hook</param>
     <param name="category">A string, the location/highlighting category that contains the compilation output.</param>
     <param name="quiet">A boolean, if True then the GUI should advertise the compilation, otherwise nothing should be reported to the user, unless there is an error.</param>
     <param name="shadow">A boolean, indicates whether the build launched was a Shadow builds, ie a "secondary" build launched automatically by GPS after a "real" build.
 For instance, when the multiple toolchains mode is activated, the builds generating cross-references are Shadow builds.</param>
     <return>A boolean</return>
     <description>Hook called when a compile operation is about to start.
Among the various tasks that GPS connects to this hook are: check whether unsaved editors should be saved (asking the user), and stop the background task that parses all xref info. If quiet is True, then no visible modification should be done in the MDI, like raising consoles, clearing their content,..., since the compilation should happen in background mode.
Funtions connected to this hook should return False if the compilation should not occur for some reason, True if it is OK to start the compilation. Typically, the reason to reject a compilation would be because the user has explicitly cancelled it through a graphical dialog, or because running a background compilation is not suitable at this time.</description>
     <example lang="python">
         # The following code adds a confirmation dialog to all
         # compilation commands.
         def on_compilation_started (hook, category, quiet, shadow):
            if not quiet:
               return MDI.yes_no_dialog ("Confirm compilation ?")
            else:
               return True
         Hook ("compilation_starting").add (on_compilation_started)
     </example>
     <example lang="python">
         # If you create a script to execute your own build script, you
         # should always do the following as part of your script. This
         # ensures a better integration in GPS (saving unsaved editors,
         # reloading xref information automatically in the end, raising
         # the GPS console, parsing error messages for automatically
         # fixable errors,...)

         if not Hook ("compilation_starting").run_until_failure \
            ("Builder results", False, False):
            return

         # ... spawn your command

         Hook ("compilation_finished").run ("Builder results")
     </example>
  </shell_doc>

  <shell_doc name="@hook@ compilation_finished">
     <param name="hook">A string, the name of the hook</param>
     <param name="category">A string, the location/highlighting category that contains the compilation output.</param>
     <param name="target_name">A string, name of the executed build target.</param>
     <param name="mode_name">A string, name of the executed build mode.</param>
     <param name="status">An integer, exit status of the execuded program.</param>
     <description>Hook called when a compile operation has finished.
Among the various tasks that GPS connects to this hook are the automatic reparsing of all xref information, and the activation of the automatic-error fixes</description>
  </shell_doc>

  <shell_doc name="@hook@ stop_macro_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <description>You should run this hook to request that the macro currently being replayed be stopped. No more events should be processed as part of this macro</description>
  </shell_doc>

  <shell_doc name="@hook@ open_file_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="line">An integer</param>
     <param name="column">An integer</param>
     <param name="column_end">An integer</param>
     <param name="enable_navigation">A boolean</param>
     <param name="new_file">A boolean</param>
     <param name="force_reload">A boolean</param>
     <param name="focus" default="False">A boolean</param>
     <return>A boolean</return>
     <description>This hook is called when GPS needs to open a file. You can connect to this hook if you want to have your own editor open, instead of the internal editor of GPS. Your function should return 1 if it did open the file, 0 if the next function connected to this hook should be called.
The file should be opened directly at line and column. If column_end is not 0, the given range should be highlighted if possible. The enable_navigation parameter is set to True if the new location should be added to the history list, so that the user can navigate forward and backward across previous locations. new_file is set to True if a new file should be created when file is not found. If set to False, nothing should be done. force_reload is set to true if the file should be reloaded from the disk, discarding any change the user might have done. focus is set to true if the open editor should be given the keyboard focus</description>
     <example lang="python">
    GPS.Hook ('open_file_action_hook').run (
              GPS.File ("gps-kernel.ads"),
              322, # line
              5,   # column
              9,   # column_end
              1,   # enable_navigation
              1,   # new_file
              0)   # force_reload
     </example>
     <see_also name="file_edited hook" />
  </shell_doc>

  <shell_doc name="@hook@ before_exit_action_hook" >
     <param name="hook">A string, the name of the hook</param>
     <return>A boolean</return>
     <description>This hook is called when GPS is about to exit. If it returns 0, this exit will be prevented (it is recommended that you display a dialog to explain why, in such a case)</description>
  </shell_doc>

  <shell_doc name="@hook@ file_line_action_hook" >
     <param name="hook">A string, the name of the hook</param>
     <param name="identifier">A string</param>
     <param name="file">An instance of GPS.File</param>
     <param name="every_line">A boolean</param>
     <param name="normalize">A boolean</param>
     <return>A boolean</return>
     <description>Hook called to request the display of new information on the side of the editors. It isn't expected that you connect to this hook, but you might want to run it yourself to ask GPS to display some information on the side of its editors</description>
  </shell_doc>

  <shell_doc name="@hook@ location_action_hook" >
     <param name="hook">A string, the name of the hook</param>
     <param name="identifier">A string</param>
     <param name="category">A string</param>
     <param name="file">An instance of GPS.File</param>
     <param name="line">An integer</param>
     <param name="column">An integer</param>
     <param name="message">A string</param>
     <return>A boolean</return>
     <description>Hook called to request the display of new information on the side of the location window</description>
  </shell_doc>

  <shell_doc name="@hook@ html_action_hook" >
     <param name="hook">A string, the name of the hook</param>
     <param name="url_or_file">A string</param>
     <param name="enable_navigation">A boolean</param>
     <param name="anchor">A string</param>
     <return>A boolean</return>
     <description>Hook called to request the display of HTML files. It is generally useful if you want to open an HTML file, and let GPS handle it in the usual manner</description>
  </shell_doc>

  <shell_doc name="@hook@ diff_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <param name="vcs_file">An instance of GPS.File</param>
     <param name="orig_file">An instance of GPS.File</param>
     <param name="ref_file">An instance of GPS.File</param>
     <param name="diff_file">An instance of GPS.File</param>
     <param name="title">Buffer title</param>
     <return>A boolean</return>
     <description>Hook called to request the display of the comparison window</description>
  </shell_doc>

  <shell_doc name="@hook@ file_status_changed_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="status">A string, the new status for the file. This is the status has displyed into the GPS status line. The value is either Unmodified, Modified or Saved.</param>
     <return>A boolean</return>
     <description>Hook called when a file status has changed</description>
  </shell_doc>

  <shell_doc name="@hook@ location_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="line">An integer</param>
     <param name="column">An integer</param>
     <description>Hook called when the location in the current editor has changed, and the cursor has stopped moving.</description>
  </shell_doc>

  <shell_doc name="@hook@ word_added">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <description>Hook called when a word has been added in the editor</description>
     <see_also>@hook@ character_added</see_also>
  </shell_doc>

  <shell_doc name="@hook@ character_added">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="character">A character</param>
     <description>Hook called when a character is going to be added in the editor. It is also called when a character is going to be removed, in which case the last parameter is 8 (control-h)</description>
     <see_also>@hook@ after_character_added</see_also>
     <see_also>@hook@ word_added</see_also>
  </shell_doc>

  <shell_doc name="@hook@ after_character_added">
     <param name="hook">A string, the name of the hook</param>
     <param name="file">An instance of GPS.File</param>
     <param name="character">A character</param>
     <description>Hook called when a character has been added in the editor. This hook is also called for the backspace key.</description>
     <see_also>@hook@ character_added</see_also>
     <see_also>@hook@ word_added</see_also>
  </shell_doc>

  <shell_doc name="@hook@ gps_started">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when GPS is fully loaded, and its window is visible to the user.
It isn't recommended to do any direct graphical action before this hook has been called, so it is recommended that in most cases your start scripts connect to this hook.</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_started">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Hook called when a new debugger has been started</description>
     <see_also>@hook@ debugger_state_changed</see_also>
  </shell_doc>

  <shell_doc name="@hook@ debugger_terminated">
     <obsolescent />
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Hook called when the debugger session has been terminated. It is now recommended that you connect to the debugger_state_changed hook and test whether the new state is "none".</description>
     <see_also>@hook@ debugger_state_changed</see_also>
  </shell_doc>

  <shell_doc name="@hook@ debugger_breakpoints_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Hook called when the list of breakpoints has been refreshed. This might occur whether or not the list has changed, but is a good time to refresh any view that might depend on an up-to-date list</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_state_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <param name="new_state">A string</param>
     <description>Indicates a change in the status of the debugger: new_state can be one of "none" (the debugger is now terminated), "idle" (the debugger is now waiting for user input) or "busy" (the debugger is now processing a command, and the process is running). As opposed to debugger_process_stopped, this hook is called when the command is just starting its executing (hence the debugger is busy while this hook is called, unless the process immediately stopped).
This hook is in fact emitted also when internal commands are sent to the debugger, and thus much more often than if it was just reacting to user input. It is therefore recommended that the callback does the minimal amount of work, possibly doing the rest of the work in an idle callback to be executed when GPS is no longer busy.
If the new state is "busy", you cannot send additional commands to the debugger.
When the state is either "busy" or "idle", GPS.Debugger.command will return the command that is about to be executed or the command that was just executed and just completed.</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_process_stopped">
     <obsolescent />
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Called when the debugger ran and has stopped, for instance when hitting a breakpoint, or after a next command. If you need to know when the debugger just started processing a command, you can connect to the debugger_state_changed hook instead. Conceptually, you could connect to debugger_state_changed at all times instead of debugger_process_stopped and check when the state is now "idle"</description>
     <see_also>@hook@ debugger_state_changed</see_also>
  </shell_doc>

  <shell_doc name="@hook@ debugger_process_terminated">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Called when the program being debugged has terminated</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_context_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Called when the debugger context has changed, for instance after the user has switched the current thread, has selected a new frame,...</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_executable_changed">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <description>Called when the file being debugged has changed</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_command_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <param name="command">A string, the command the user wants to execute</param>
     <return>A boolean</return>
     <description>This hook is emitted when the user types a command in the debugger console, or emits the console through the GPS.Debugger API. It gives you a chance to override the behavior for the command, or even define your own commands. Note that you must ensure that any debugger command you execute this way does finish with a prompt. The function should return the output of your custom command</description>
     <example lang="python">
## The following example implements a new gdb command, "hello". When the
## user types this command in the console, we end up executing "print A"
## instead. This can be used for instance to implement convenient
## macros

def debugger_commands (hook, debugger, command):
   if command == "hello":
      return 'A=' + debugger.send ("print A", False)
   else:
      return ""

GPS.Hook ("debugger_command_action_hook").add (debugger_commands)
     </example>
   </shell_doc>

  <shell_doc name="@hook@ marker_added_to_history">
     <param name="hook">A string, the name of the hook</param>
     <description>Hook called when a new marker is added to the history list of previous locations, where the user can navigate back and forward</description>
  </shell_doc>

  <shell_doc name="@hook@ debugger_question_action_hook">
     <param name="hook">A string, the name of the hook</param>
     <param name="debugger">An instance of GPS.Debugger</param>
     <param name="question">A string</param>
     <return>A string</return>
     <description>Action hook called just before displaying an interactive dialog, when the debugger is asking a question to the user. This hook can be used to disable the dialog (and send the rreply directly to the debugger instead). It should return a non-empty string to pass to the debugger if the dialog should not be displayed. You cannot send commands to the debugger when inside this hook, since the debugger is blocked waiting for an answer</description>
     <example lang="python">
         def gps_question (hook, debugger, str):
            return "1"   ## Always choose choice 1
         GPS.Hook ("debugger_question_action_hook").add (gps_question)
         debug=GPS.Debugger.get()
         deubg.send ("print &amp;foo")
     </example>
  </shell_doc>

  <shell_doc name="@hook@ rsync_action_hook">
    <description>For internal use only</description>
  </shell_doc>

  <shell_doc name="@hook@ server_config_hook">
    <param name="hook">A string, the name of the hook</param>
    <param name="server_type">A string, the server operations category. Can take the values "BUILD_SERVER", "EXECUTION_SERVER" or "DEBUG_SERVER"</param>
    <param name="nickname">A string, the server's nickname</param>
    <description>Hook called when a server is assigned to a server operations category.</description>
  </shell_doc>

  <shell_doc name="@hook@ server_list_hook">
    <param name="hook">A string, the name of the hook</param>
    <description>Hook called when the list of configured servers changed.</description>
  </shell_doc>

  <shell_doc name="@hook@ commit_done_hook">
    <description>Hook called when a commit has been done.</description>
  </shell_doc>

  <shell_doc name="@hook@ activity_checked_hook">
    <description>Hook called when an activity has been checked, this is the last step done after the activity has been committed. It is at this point that the activity closed status is updated.</description>
  </shell_doc>

  <shell_doc name="@hook@ status_parsed_hook">
    <description>Hook called when the last file status has been parsed after the corresponding VCS action.</description>
  </shell_doc>

  <shell_doc name="@hook@ log_parsed_hook">
    <description>Hook called when the last file log has been parsed after the corresponding VCS action.</description>
  </shell_doc>

  <shell_doc name="@hook@ annotation_parsed_hook">
    <description>Hook called when the last file annotation has been parsed after the corresponding VCS action.</description>
  </shell_doc>

  <shell_doc name="@hook@ revision_parsed_hook">
    <description>Hook called when the last file revision has been parsed after the corresponding VCS action.</description>
  </shell_doc>

  <shell_doc name="@hook@ compute_build_targets">
     <param name="hook">A string, the name of the hook</param>
     <param name="name">A string, the target type</param>
     <return>A string</return>
     <description>Hook called whenever GPS needs to compute a list of subtargets for a given build target. The handler should check whether name is a known build target, and if so, return a list of tuples, where each tuple corresponds to one target and contains a display name (used in the menus, for instance) and the name of the target. If name is not known, it should return an empty list.</description>
     <example lang="python">
         def compute_targets (hook, name):
            if name == "my_target":
              return [(display_name_1, target_1),
                      (display_name_2, target_2)]
            return ""
         GPS.Hook ("compute_build_targets").add (compute_targets)
     </example>
  </shell_doc>

  <!--#################################################################
    ####   Top level functions
    ###################################################################-->

  <shell_doc name="GPS.__run_hook__">
      <description>Internal function used for the support of hooks</description>
  </shell_doc>

  <shell_doc name="GPS.exit">
      <param name="force" default="False">A boolean</param>
      <param name="status" default="0">An integer</param>
      <description>Exit GPS, asking for confirmation if any file is currently modified and unsaved. If force is True, no check is done.
Status is the exit status to return to the calling shell. 0 will generally mean success on all architectures.</description>
  </shell_doc>

  <shell_doc name="GPS.get_system_dir">
     <return>The install directory for GPS</return>
     <description>Return the installation directory for GPS.
This directory always ends with a directory separator</description>
     <example lang="python">
        html = GPS.get_system_dir() + "share/doc/gps/html/gps.html"
        will compute the location of GPS's documentation
     </example>
     <see_also name="GPS.get_home_dir()" />
  </shell_doc>

  <shell_doc name="GPS.get_tmp_dir">
     <return>The install directory for GPS</return>
     <description>Return the directory where gps creates temporary files.
This directory always ends with a directory separator</description>
  </shell_doc>

  <shell_doc name="GPS.get_home_dir">
     <return>The user's GPS directory</return>
     <description>Return the directory that contains the user-specific files.
This directory always ends with a directory separator</description>
     <example lang="python">
        log = GPS.get_home_dir() + "log"
        will compute the name of the log file generated by GPS
     </example>
     <see_also name="GPS.get_system_dir()" />
  </shell_doc>

  <shell_doc name="GPS.freeze_xref">
     <description>Forces GPS to use the cross-reference information it already has in memory. GPS will no longer check on the disk whether more recent information is available. This can provide a significant speedup in complex scripts or scripts that need to analyze the cross-reference information for lots of files. In such cases, the script should generally call GPS.Project.update_xref to first load all the required information in memory.
You need to explicitly call GPS.thaw_xref to go back to the default GPS behavior. Note the use of the "finally" exception handling in the following example, which ensures that even if there is some unexpected exception, the script always restores properly the default behavior.</description>
     <example lang="python">
try:
   GPS.Project.root().update_xref (recursive=True)
   GPS.freeze_xref()
   ... complex computation
finally:
   GPS.thaw_xref()
     </example>
     <see_also name="GPS.Project.update_xref()"/>
     <see_also name="GPS.thaw_xref()"/>
  </shell_doc>

  <shell_doc name="GPS.thaw_xref">
     <description>See GPS.freeze_xref for more information</description>
     <see_also name="GPS.freeze_xref()"/>
  </shell_doc>

  <shell_doc name="GPS.last_command">
     <return>A string</return>
     <description>This function returns the name of the last action executed by GPS. This name is not ultra-precise: it will be accurate only when the action is executed through a key binding. Otherwise, an empty string is returned. However, the intent here is for a command to be able to check whether it is called multiple times in a row. For this, this command will return the command set by GPS.set_last_command() if it was set.</description>
     <example lang="python">
         def kill_line ():
            """Emulates Emacs behavior: when called multiple times, the cut line must be
               appended to the previously cut one."""
            ## The name of the command below is unknown to GPS. This is just a
            ## string we use in this implementation to detect multiple consecutive
            ## calls to this function. Note that this works whether the function is
            ## called from the same key binding or not, and from the same GPS action
            ## or not
            append = GPS.last_command() == "my-kill-line":
            GPS.set_last_command ("my-kill-line")
     </example>
     <see_also name="GPS.set_last_command" />
  </shell_doc>

  <shell_doc name="GPS.set_last_command">
      <param name="command">A string</param>
      <description>This function overrides the name of the last command executed by GPS. This new name will be the one returned by GPS.last_command() until the user performs a different action. Thus, multiple calls of the same action in a row will always return the value of the command parameter. See the example in GPS.last_command()</description>
       <see_also name="GPS.last_command" />
  </shell_doc>

  <shell_doc name="GPS.lookup_actions_from_key">
       <param name="key">A string</param>
       <return>A list of strings</return>
       <description>Given a key binding, for instance "control-x control-b", this function returns the list of actions that could be executed. Not all actions would be executed, though, since only the ones for which the filter matches are executed. The name of the actions is always in lower cases.</description>
       <see_also name="GPS.lookup_actions" />
  </shell_doc>

  <shell_doc name="GPS.lookup_actions">
       <return>A list of strings</return>
       <description>This command returns the list of all known GPS actions. This doesn't include menu names. All actions are lower-cased, but the order in the list is not significant.</description>
     <see_also name="GPS.lookup_actions_from_key" />
  </shell_doc>

  <shell_doc name="GPS.repeat_next">
     <param name="count">An integer</param>
     <description>This action will execute the next one &lt;count&gt; times.</description>
  </shell_doc>

  <shell_doc name="GPS.insmod">
     <param name="shared_lib">Library containing the code of the module</param>
     <param name="module">Name of the module</param>
     <description>Dynamically register a new module, reading its code from shared_lib.
The library must define the following two symbols:
  - _init: This is called by GPS to initialize the library itself
  - __register_module: This is called to do the actual module registration, and
                       should call the Register_Module function in the GPS
                       source code

This is work in progress, and not fully supported on all systems.
     </description>
     <see_also name="GPS.lsmod()" />
  </shell_doc>

  <shell_doc name="GPS.lsmod">
     <return>List of strings</return>
     <description>Return the list of modules that are currently registered in
GPS. Each facility in GPS is provided in a separate module, so that users
can choose whether to activate specific modules or not. Some modules can also
be dynamically loaded</description>
     <see_also name="GPS.insmod()" />
  </shell_doc>

  <shell_doc name="GPS.extract_method">
      <param name="file">A string</param>
      <param name="line_start">An integer</param>
      <param name="line_end">An integer</param>
      <param name="method_name" default="New_Method">A string</param>
      <description>Extract the code from line_start to line_end in the specified file into a new subprogram with the given name. All needed local variables are declared properly in this new subprogram, and it is given parameters if needed</description>
  </shell_doc>

  <shell_doc name="GPS.exec_in_console">
     <param>A string</param>
     <description>This function is specific to python. It executes the string given in argument in the context of the GPS Python console. If you use the standard python's exec() function instead, the latter will only modify the current context, which generally will have no impact on the GPS console itself.</description>
     <example lang="python">
     ### Import a new module transparently in the console, so that users can
     ### immediately use it
     GPS.exec_in_console ("import time")
     </example>
  </shell_doc>

  <shell_doc name="GPS.supported_languages">
     <return>List of strings</return>
     <description>Return the list of languages for which GPS has special handling. Any file can be open in GPS, but some extensions are recognized specially by GPS to provide syntax highlighting, cross-references, or other special handling. See the GPS documentation on how to add support for new languages in GPS.

The returned list is sorted alphabetically, and the name of the language has been normalized (start with an upper case, and use lowercases for the rest except after an underscore character)</description>
     <example lang="python">
        GPS.supported_languages()[0]
        will return the name of the first supported language
     </example>
  </shell_doc>

  <shell_doc name="GPS.debug_memory_usage">
     <param name="size">An integer</param>
     <description>Dumps on stdout the size biggest memory allocators in GPS. This is really meant as a debug function for GPS developers</description>
  </shell_doc>

  <shell_doc name="GPS.execute_action">
     <param name="action">Name of the action to execute</param>
     <param name="...">Any number of string parameters</param>
     <description>Execute one of the actions defined in GPS. Such actions are
either predefined by GPS or defined by the users through customization files.
See the GPS documentation for more information on how to create new actions.
GPS will wait until the command completes to return the control to the caller,
whether you execute a shell command, or an external process.

The action's name can start with a '/', and be a full menu path. As a result,
the menu itself will be executed, just as if the user had pressed it.

The extra arguments must be strings, and are passed to the action, which can
use them through $1, $2,...

The list of existing actions can be found through the Edit->Actions menu.

The action will not be executed if the current context is not appropriate for
this action.
</description>
     <example lang="python">
        GPS.execute_action (action="Split vertically")
        will split the current window vertically
     </example>
     <see_also name="GPS.execute_asynchronous_action" />
  </shell_doc>

  <shell_doc name="GPS.execute_asynchronous_action">
     <param name="action">Name of the action to execute</param>
     <param name="...">Any number of string parameters</param>
     <description>This command is similar to GPS.execute_action. However, commands that execute external applications or menus are executed asynchronously: GPS.execute_asynchronous_action will immediately return, although the external application might not have completed its execution</description>
     <see_also name="GPS.execute_action" />
  </shell_doc>

  <shell_doc name="GPS.parse_xml">
     <param name="xml">The XML string to parse</param>
     <description>Load an XML customization string. This string should contain one or more toplevel tags similar to what is normally found in custom files, such as &lt;key&gt;, &lt;alias&gt;, &lt;action&gt;,..

Optionally you can also pass the full contents of an XML file, starting from the &lt;?xml?&gt; header.</description>
     <example lang="python">
        GPS.parse_xml \
          ("""&lt;action name="A"&gt;&lt;shell&gt;my_action&lt;/shell&gt;&lt;/action&gt; \
              &lt;menu action="A"&gt;&lt;title&gt;/Edit/A&lt;/title&gt;&lt;/menu&gt;""")
        Adds a new menu in GPS, which executes the command my_action
     </example>
  </shell_doc>

  <shell_doc name="GPS.set_busy">
     <description>Activate the "busy" state in GPS by animating the GPS icon. This command can be called recursively, and GPS.unset_busy should be called a corresponding number of time to stop the animation.</description>
     <see_also>GPS.unset_busy()</see_also>
     <see_also>GPS.get_busy()</see_also>
  </shell_doc>

  <shell_doc name="GPS.unset_busy">
     <description>Reset the "busy" state</description>
     <see_also>GPS.set_busy()</see_also>
     <see_also>GPS.get_busy()</see_also>
  </shell_doc>

  <shell_doc name="GPS.get_busy">
     <description>Return the "busy" state</description>
     <see_also>GPS.set_busy()</see_also>
     <see_also>GPS.unset_busy()</see_also>
  </shell_doc>

  <shell_doc name="GPS.save_persistent_properties">
     <description>Forces an immediate save of the persistent properties that GPS maintains for files and projects (for instance the text encoding, the programming language, the debugger breakpoints,...).
You do not have to call this subprogram explicitly in general, since this is done automatically by GPS on exit.</description>
  </shell_doc>

  <shell_doc name="GPS.current_context">
     <return>An instance of GPS.FileContext, GPS.AreaContext,...</return>
     <description>Returns the current context in GPS. This is the currently selected file, line, column, project,... depending on what window is currently active. From one call of this function to the next, a different instance is returned, and therefore you shouldn't store your own data in the instance, since you will not be able to recover it later on</description>
     <see_also name="GPS.Editor.get_line()"/>
     <see_also name="GPS.Editor.*: Most of these functions apply to the current editor" />
     <see_also name="GPS.MDI.current(): Access the current window" />
     <see_also name="GPS.contextual_context()" />
  </shell_doc>

  <shell_doc name="GPS.contextual_context">
     <return>An instance of GPS.FileContext, GPS.AreaContext,...</return>
     <description>Returns the context at the time the contextual menu was open.
This function will only return a valid context while the menu is open, or while an action executed from that menu is executed. You can store your own data in the returned instance, so that for instance you can precompute some internal data in the filters for the contextual actions (see &lt;filter&gt; in the XML files), and reuse that precomputed data when the menu is executed.
See also the documentation for "contextual_menu_open" hook.</description>
     <see_also name="GPS.current_context" />
     <example lang="python">
Here is an example that shows how to precompute some data when we
decide whether a menu entry should be displayed in a contextual menu,
and reuse that data when the action executed through the menu is reused.

import GPS

def on_contextual_open (name):
   context = GPS.contextual_context ()
   context.private = 10
   GPS.Console().write ("creating data " + `context.private` + '\n')

def on_contextual_close (name):
   context = GPS.contextual_context ()
   GPS.Console().write ("destroying data " + `context.private` + '\n')

def my_own_filter ():
   context = GPS.contextual_context()
   context.private=context.private + 1
   GPS.Console().write ("context.private=" + `context.private` + '\n')
   return 1

def my_own_action ():
   context = GPS.contextual_context()
   GPS.Console().write ("my_own_action " + `context.private` + '\n')

GPS.parse_xml("""
   &lt;action name="myaction%gt;"
      &lt;filter shell_lang="python"
              shell_cmd="contextual.my_own_filter()" /&gt;
      &lt;shell lang="python">contextual.my_own_action()&lt;/shell&gt;
   &lt;/action&gt;

   &lt;contextual action="myaction"&gt;
      &lt;Title&gt;Foo1&lt;/Title&gt;
   &lt;/contextual&gt;
   &lt;contextual action="myaction"&gt;
      &lt;Title&gt;Foo2&lt;/Title&gt;
   &lt;/contextual&gt;
 """)

GPS.Hook ("contextual_menu_open").add (on_contextual_open)
GPS.Hook ("contextual_menu_close").add (on_contextual_close)
     </example>
     <example lang="python">
The following example does almost the same thing as the above, but
without relying on the hooks to initialize the value. We set the value
in the context the first time we need it, instead of every time the menu
is open.

import GPS
def my_own_filter2 ():
   try:
      context = GPS.contextual_context()
      context.private2 = context.private2 + 1
   except AttributeError:
      context.private2 = 1
   GPS.Console().write ("context.private2=" + `context.private2` + '\n')
   return 1

def my_own_action2 ():
   context = GPS.contextual_context()
   GPS.Console().write ("my_own_action, private2=" + `context.private2` + '\n')

GPS.parse_xml ("""
   &lt;action name="myaction2"&gt;
      &lt;filter shell_lang="python"
              shell_cmd="contextual.my_own_filter2()" /&gt;
      &lt;shell lang="python">contextual.my_own_action2()&lt;/shell&gt;
   &lt;/action&gt;
   &lt;contextual action="myaction2"&gt;
      &lt;Title&gt;Bar1&lt;/Title&gt;
   &lt;/contextual&gt;
   &lt;contextual action="myaction2"&gt;
      &lt;Title&gt;Bar2&lt;/Title&gt;
   &lt;/contextual&gt;
""")
     </example>
  </shell_doc>

  <shell_doc name="GPS.compute_xref">
      <description>Update the cross-reference information stored in GPS. This needs to be called after major changes to the sources only, since GPS itself is able to work with partially up-to-date information</description>
  </shell_doc>

  <shell_doc name="GPS.compute_xref_bg">
      <description>Update in the background cross-reference information stored in GPS.</description>
      <see_also name="GPS.compute_xref()"/>
  </shell_doc>

  <shell_doc name="GPS.get_build_output">
      <param name="target_name">(optional) a string</param>
      <param name="shadow">(optional) a Boolean, indicating whether we want the output of shadow builds</param>
      <param name="background">(optional) a Boolean, indicating whether we want the output of background builds</param>
      <return>A string, the output of the latest build for the corresponding target.</return>
      <description>Return the result of the last compilation command</description>
      <see_also name="GPS.File.make()"/>
      <see_also name="GPS.File.compile()"/>
  </shell_doc>

  <shell_doc name="GPS.macro_play">
      <param name="speed" default="1.0">A string</param>
      <description>Play current set of events</description>
  </shell_doc>

  <shell_doc name="GPS.macro_record">
      <description>Start recording set of events</description>
  </shell_doc>

  <shell_doc name="GPS.macro_load">
      <param name="file">A string</param>
      <description>Load file containing a set of recorded events</description>
  </shell_doc>

  <shell_doc name="GPS.add_location_command">
      <param name="command">A string</param>
      <description>Add a command to the navigation buttons in the toolbar. When the user presses the back button, this command will be executed, and should put GPS in a previous state. This is for instance used while navigating in the HTML browsers to handle the back button</description>
  </shell_doc>

  <shell_doc name="GPS.visual_diff">
     <param name="file1">A string</param>
     <param name="file2">A string</param>
     <param name="file3" default="">A string</param>
     <description>Open a Visual Diff between file1, file2 and file3</description>
  </shell_doc>

  <shell_doc name="GPS.pwd">
     <return>A string</return>
     <description>Print name of current/working directory</description>
     <example lang="python">
        This command will have the same return value as the standard Python
        command os.getcwd(). The current directory can also be changed through
        a call to os.chdir("dir").
     </example>
  </shell_doc>

  <shell_doc name="GPS.dump_file">
     <param name="text">A string</param>
     <param name="filename">A string</param>
     <description>Writes text to filename on the disk. This is mostly intended for poor shells like the GPS shell which do not have better solutions. In python, it is recommended to use python's own mechanisms</description>
  </shell_doc>

  <shell_doc name="GPS.base_name">
     <param name="filename">A string</param>
     <description>Returns the base name for the given full path name</description>
  </shell_doc>

  <shell_doc name="GPS.dir_name">
     <param name="filename">A string</param>
     <description>Returns the directory name for the given full path name</description>
  </shell_doc>

  <shell_doc name="GPS.cd">
     <param name="dir">A string</param>
     <description>Change the current directory to dir</description>
  </shell_doc>

  <shell_doc name="GPS.delete">
     <param name="name">A string</param>
     <description>Delete file/directory name from the file system</description>
  </shell_doc>

  <shell_doc name="GPS.dir">
     <param name="pattern" default="">A string</param>
     <return>A list of strings</return>
     <description>list files following pattern (all files by default)</description>
  </shell_doc>

  <shell_doc name="GPS.ls">
     <param name="pattern" default="">A string</param>
     <return>A list of strings</return>
     <description>list files following pattern (all files by default)</description>
  </shell_doc>

  <shell_doc name="GPS.dump">
     <param name="string">A string</param>
     <param name="add_lf" default="False">A boolean</param>
     <return>A string, the name of the output file</return>
     <description>Dump string to a temporary file. Return the name of the file. If add_lf is TRUE, append a line feed at end of file</description>
  </shell_doc>

  <shell_doc name="GPS.dump_xref_db">
     <description>Dump in the file $HOME/.gps/db_dump the current contents of the cross-references database. This is intended for debugging purposes only</description>
  </shell_doc>

  <shell_doc name="GPS.reset_xref_db">
     <description>Reset the internal cross-reference database that GPS is using for most of its navigation facilities. You shouldn't have to call that yourself, since in general GPS should know by itself when it is necessary to refresh its database. However, this might be used as a workaround if you think you have troubles with the cross-reference information which isn't accurate.</description>
  </shell_doc>

  <shell_doc name="GPS.set_build_mode">
     <param name="mode" default="">Name of the mode to set</param>
     <description>Set the current build mode. If specified mode is not a registered mode, do nothing.</description>
  </shell_doc>

  <shell_doc name="GPS.get_build_mode">
     <description>Return the name of the current build mode. Return an empty string if no mode is registered.</description>
  </shell_doc>

  <shell_doc name="GPS.is_server_local">
     <param name="server">The server. Possible values are "Build_Server", "Debug_Server", "Execution_Server" and "Tools_Server".</param>
     <return>A boolean</return>
     <description>Tell if the specified server is the local machine.</description>
  </shell_doc>

  <shell_doc name="GPS.version">
     <return>A string</return>
     <description>Return GPS version as a string.</description>
  </shell_doc>

  <!--#################################################################
    ####   GPS shell commands
    ###################################################################-->

  <shell_doc name="GPS.help">
     <param name="command" default="">A string</param>
     <return>A string</return>
     <description>Return the description of the command given in parameter, or the list of all commands exported by GPS. GPS.help is specific to the GPS shell</description>
  </shell_doc>

  <shell_doc name="GPS.echo">
     <param name="...">Any number of parameters</param>
     <description>Display a line of text. This command is specific to the GPS shell.</description>
  </shell_doc>

  <shell_doc name="GPS.echo_error">
     <param name="...">Any number of parameters</param>
     <description>Display a line of text. This command is specific to the GPS shell. It is designed to be used to output error messages. This command raises the shell windows.</description>
  </shell_doc>

  <shell_doc name="GPS.load">
     <param name="filename">A string</param>
     <description>Load and execute a script file. This command is specific to the GPS shell.</description>
  </shell_doc>

  <shell_doc name="GPS.clear_cache">
      <description>Free the internal cache used for return values. This function needs to be called explicitly, or previously returned value are never freed. After calling this function, you can no longer use %1, %2,... to refer to previously returned values.</description>
  </shell_doc>

  <!--#################################################################
    ####   File class
    ###################################################################-->

  <shell_doc name="GPS.File">
      <description>Represents a source file of your application</description>
      <see_also name="GPS.File.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.File.__str__">
      <param name="self">The instance of GPS.File</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.File.__repr__">
      <param name="self">The instance of GPS.File</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.File.__hash__">
      <param name="self">The instance of GPS.File</param>
      <return>An integer</return>
      <description>Return a hash value suitable for storing self in a dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.File.__cmp__">
      <param name="self">The instance of GPS.File</param>
      <param name="file">An instance of GPS.File</param>
      <return>An integer</return>
      <description>Compare two instances of GPS.File, and return -1, 0 or 1 depending on their relative sort order</description>
  </shell_doc>

  <shell_doc name="GPS.File.__init__">
      <param name="self">The instance being constructed</param>
      <param name="name">Name of the file associated with this instance</param>
      <param name="local" default="false">A boolean</param>
      <description>Initializes a new instance of the class File. This doesn't need to be called explicitly, since GPS will call it automatically when you create such an instance. If name is a base file name (no directory is specified), then GPS will attempt to search for this file in the list of source directories of the project. If a directory is specified, or the base file name wasn't found in the source directories, then the file name is considered as relative to the current directory. If local is "true" the specified file name is to be considered as
local to the current directory.</description>
      <example lang="python">
         file=GPS.File("/tmp/work")
         print file.name()
      </example>
      <see_also name="GPS.File.name" />
  </shell_doc>

  <shell_doc name="GPS.File.name">
      <param name="self">The instance whose name you want to get</param>
      <param name="remote_server" default="GPS_Server">A string. Possible values are "GPS_Server" (or empty string), "Build_Server", "Debug_Server", "Execution_Server" and "Tools_Server".</param>
      <return>A string, the name of the file</return>
      <description>Return the name of the file associated with self. This is an absolute file name, including directories from the root of the filesystem.
      If remote_server is set, then the function returns the equivalent path on the specified server. GPS_Server (default) is always the local machine.</description>
  </shell_doc>

  <shell_doc name="GPS.File.language">
     <param name="self">The instance of GPS.File</param>
     <return>A string</return>
     <description>Return the name of the language this file is written in. This is based on the file extension and the naming scheme defined in the project files or the XML files. The empty string is returned when the language is unknown</description>
  </shell_doc>

  <shell_doc name="GPS.File.other_file">
      <param name="self">The instance to which the operation applies</param>
      <return>An instance of GPS.File</return>
      <description>Return the name of the other file semantically associated with this one. In Ada this is the spec or body of the same package depending on the type of this file. In C, this will generally be the .c or .h file with the same base name.</description>
      <example lang="python">
         GPS.File ("tokens.ads").other_file().name()
         will print "/full/path/to/tokens.adb" in the context of the project
         file used for the GPS tutorial.
      </example>
  </shell_doc>

  <shell_doc name="GPS.File.directory">
      <param name="self">The instance of GPS.File</param>
      <return>A string</return>
      <description>Return the directory in which the file is found</description>
      <example lang="python">
         ## Sorting files by TN is easily done with a loop like
         dirs={}
         for s in GPS.Project.root().sources():
           if dirs.has_key (s.directory()):
              dirs[s.directory()].append (s)
           else:
              dirs[s.directory()] = [s]
      </example>
  </shell_doc>

  <shell_doc name="GPS.File.project">
      <param name="self">The instance of File to which the operation applies</param>
      <param name="default_to_root" default="true">A boolean</param>
      <return>An instance of GPS.Project</return>
      <description>Return the project to which file belongs. If file is not one of the souces of the project, the returned value depends on default_to_none: if false, None is returned. Otherwise, the root project is returned.</description>
      <example lang="python">
         GPS.File ("tokens.ads").project().name()
         will print "/full/path/to/sdc.gpr" in the context of the project file
         used for the GPS tutorial
      </example>
  </shell_doc>

  <shell_doc name="GPS.File.uses">
      <param name="self">The instance of GPS.File</param>
      <description>Display in the dependency browser the list of files that file_name depends on.</description>
      <see_also name="GPS.File.used_by()"/>
  </shell_doc>

  <shell_doc name="GPS.File.used_by">
      <param name="self">The instance of GPS.File</param>
      <description>Display in the dependency browser the list of files that depends on file_name. This command might take some time to execute since GPS needs to parse the cross-reference information for multiple source files</description>
      <see_also name="GPS.File.uses()" />
  </shell_doc>

  <shell_doc name="GPS.File.imports">
      <param name="self">The instance of GPS.File</param>
      <param name="include_implicit" default="False">A boolean</param>
      <param name="include_system" default="True">A boolean</param>
      <return>A list of files</return>
      <description>Return the the list of files that self depends on. If include_implicit is true, then implicit dependencies are also returned. If include_system is true, then system files from the compiler runtime are also returned.</description>
      <see_also name="GPS.File.imported_by()"/>
  </shell_doc>

  <shell_doc name="GPS.File.imported_by">
      <param name="self">The instance of GPS.File</param>
      <param name="include_implicit" default="False">A boolean</param>
      <param name="include_system" default="True">A boolean</param>
      <return>A list of files</return>
      <description>Return the list of files that depends on file_name. This command might take some time to execute since GPS needs to parse the cross-reference information for multiple source files. If include_implicit is true, then implicit dependencies are also returned. If include_system is true, then system files from the compiler runtime are also returned.</description>
      <see_also name="GPS.File.imports()" />
  </shell_doc>

  <shell_doc name="GPS.File.compile">
      <param name="self">The instance of GPS.File</param>
      <param name="extra_args" default="">A string</param>
      <description>Compile current file. This call will return only once the compilation is completed. Additional arguments can be added to the command line.</description>
      <example lang="python">
          GPS.File ("a.adb").compile()
      </example>
      <see_also name="GPS.File.make()"/>
  </shell_doc>

  <shell_doc name="GPS.File.check_syntax">
      <param name="self">The instance of GPS.File</param>
      <description>Check the syntax for current file. This call will return only once the check is completed</description>
      <see_also name="GPS.File.shadow_check_syntax()"/>
      <see_also name="GPS.File.shadow_check_semantic()"/>
      <see_also name="GPS.File.check_semantic()"/>
  </shell_doc>

  <shell_doc name="GPS.File.shadow_check_syntax">
      <param name="self">The instance of GPS.File</param>
      <description>Check the syntax for current file. The current file will not be saved, but a temporary extending project will be created, and deleted when the compilation ends. This call will launch a background process and return immediately</description>
      <see_also name="GPS.File.check_syntax()"/>
      <see_also name="GPS.File.check_semantic()"/>
      <see_also name="GPS.File.shadow_check_semantic()"/>
  </shell_doc>

  <shell_doc name="GPS.File.check_semantic">
      <param name="self">The instance of GPS.File</param>
      <description>Check the semantic for current file. This call will return only once the check is completed</description>
      <see_also name="GPS.File.shadow_check_semantic()"/>
      <see_also name="GPS.File.check_syntax()"/>
      <see_also name="GPS.File.shadow_check_syntax()"/>
  </shell_doc>

  <shell_doc name="GPS.File.shadow_check_semantic">
      <param name="self">The instance of GPS.File</param>
      <description>Check the semantic for current file. The current file will not be saved, but a temporary extending project will be created, and deleted when the compilation ends. This call will launch a background process and return immediately</description>
      <see_also name="GPS.File.check_semantic()"/>
      <see_also name="GPS.File.check_syntax()"/>
      <see_also name="GPS.File.shadow_check_syntax()"/>
  </shell_doc>

  <shell_doc name="GPS.File.make">
      <param name="self">The instance of GPS.File</param>
      <param name="extra_args" default="">A string</param>
      <description>Compile and link the file and all its dependencies. This call will return only once the compilation is completed. Additional arguments can be added to the command line.</description>
      <see_also name="GPS.File.compile()"/>
  </shell_doc>

  <shell_doc name="GPS.File.search">
      <param name="self">The instance of GPS.File</param>
      <param name="pattern">A string</param>
      <param name="case_sensitive" default="False">A boolean</param>
      <param name="regexp" default="False">A boolean</param>
      <param name="scope" default="whole">One of ("whole", "comments", "strings", "code")</param>
      <return>List of GPS.FileLocation instances</return>
      <description>Return the list of matches for pattern in the file. Default values are False for case_sensitive and regexp. Scope is a string, and should be any of 'whole', 'comments', 'strings', 'code'. The latter will match only for text outside of comments</description>
      <see_also name="GPS.EditorLocation.search" />
      <see_also name="GPS.File.search_next" />
  </shell_doc>

  <shell_doc name="GPS.File.search_next">
      <param name="self">The instance of GPS.File</param>
      <param name="pattern">A string</param>
      <param name="case_sensitive" default="False">A boolean</param>
      <param name="regexp" default="False">A boolean</param>
      <return>An instance of GPS.FileLocation</return>
      <description>Return the next match for pattern in the file. Default values are False for case_sensitive and regexp. Scope is a string, and should be any of 'whole', 'comments', 'strings', 'code'. The latter will match only for text outside of comments</description>
      <see_also name="GPS.File.search_next" />
  </shell_doc>

  <shell_doc name="GPS.File.entities">
      <param name="self">The instance of GPS.File</param>
      <param name="local" default="true">A boolean</param>
      <return>A list of GPS.Entity</return>
      <description>Return the list of entities that are either referenced (if local is false) or declared (if local is true) in self.</description>
  </shell_doc>

  <shell_doc name="GPS.File.set_property">
     <param name="self">The instance of GPS.File</param>
     <param name="name">A string</param>
     <param name="value">A string</param>
     <param name="persistent" default="False">A boolean</param>
     <description>Associates a string property with the file. This property is retrievable during the whole GPS session, or across GPS sessions if persistent is set to True.
This is different than setting instance properties through Python's standard mechanism in that there is no garantee that the same instance of GPS.File will be created for each physical file on the disk, and therefore you would not be able to associate a property with the physical file itself</description>
     <see_also name="GPS.File.get_property" />
     <see_also name="GPS.Project.set_property" />
  </shell_doc>

  <shell_doc name="GPS.File.get_property">
     <param name="self">The instance of GPS.File</param>
     <param name="name">A string</param>
     <return>A string</return>
     <description>Return the value of the property associated with the file. This property might have been set in a previous GPS session if it is persistent. An exception is raised if no such property already exists for the file</description>
     <see_also name="GPS.File.set_property" />
  </shell_doc>

  <shell_doc name="GPS.File.remove_property">
     <param name="self">The instance of GPS.File</param>
     <param name="name">A string</param>
     <description>Removes a property associated with a file</description>
     <see_also name="GPS.File.set_property" />
  </shell_doc>

  <shell_doc name="GPS.File.generate_doc">
     <param name="self">The instance of GPS.File</param>
     <description>Generate the documentation of the file, and display it with the default browser</description>
     <see_also name="GPS.Project.generate_doc"/>
  </shell_doc>

  <!--#################################################################
    ####   Entity class
    ###################################################################-->

  <shell_doc name="GPS.Entity">
      <description>Represents an entity from the source, based on the location of its declaration</description>
      <see_also name="GPS.Entity.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Entity.__str__">
      <param name="self">The instance of GPS.Entity</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.__repr__">
      <param name="self">The instance of GPS.Entity</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.__hash__">
      <param name="self">The instance of GPS.Entity</param>
      <return>An integer</return>
      <description>Return a hash value suitable for storing self in a dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.__cmp__">
      <param name="self">The instance of GPS.Entity</param>
      <param name="file">An instance of GPS.Entity</param>
      <return>An integer</return>
      <description>Compare two instances of GPS.Entity, and return -1, 0 or 1 depending on their relative sort order</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.__init__">
      <param name="self">The instance of GPS.Entity we are building</param>
      <param name="name">A string, the name of the entity</param>
      <param name="file" default="None">An instance of GPS.File, in which the entity is referenced</param>
      <param name="line" default="1">An integer, the line at which the entity is referenced</param>
      <param name="column" default="1">An integer, the column at which the entity is referenced</param>
      <description>Initializes a new instance of the Entity class, from any reference to the entity. The file parameter should only be omitted for a predefined entity of the language. This will only work for languages for which a cross-reference engine has been defined</description>
      <example lang="python">
          GPS.Entity ("foo", GPS.File ("a.adb"), 10, 23).declaration().file().name()
          will return the full path name of the file in which the entity "foo",
          referenced in a.adb at line 10, column 23, is defined.
      </example>
  </shell_doc>

  <shell_doc name="GPS.Entity.rename">
      <param name="self">The instance of GPS.Entity</param>
      <param name="name">A string</param>
      <param name="include_overriding" default="true">A boolean</param>
      <param name="make_writable" default="false">A boolean</param>
      <param name="auto_save" default="false">A boolean</param>
      <description>Rename the entity every where in the application. The source files should have been compiled first, since this operation relies on the cross-reference information which have been generated by the compiler. If include_overriding is true, then subprograms that override or are overridden by self are also renamed. Likewise, if self is a parameter to a subprogram then parameters with the same name in overriding or overridden subprograms are also renamed.
If some renaming should be performed in a read-only file, the behavior depends on the make_writable parameter: if true, the file is made writable and the renaming is performed; if false, no renaming is performed in that file, and a dialog is displayed asking whether you want to do the other renamings.
The files will be saved automatically if auto_save is true, otherwise they are left edited.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.name">
      <param name="self">The instance of GPS.Entity</param>
      <return>A string, the name of the entity</return>
      <description>Return the name of the entity. The casing of the name has been normalized to lower-cases for case-insensitive languages</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.full_name">
      <param name="self">The instance of GPS.Entity</param>
      <return>A string, the full name of the entity</return>
      <description>Return the full name of the entity that it to say the name of the entity prefixed with its callers and parent packages names. The casing of the name has been normalized to lower-cases for case-insensitive languages</description>
  </shell_doc>

<shell_doc name="GPS.Entity.declaration">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.FileLocation, where the entity is declared</return>
      <description>Return the location of the declaration for the entity. The file's name is is "&lt;predefined&gt;" for predefined entities</description>
      <example lang="python">
          entity=GPS.Entity  ("integer")
          if entity.declaration().file().name() == "&lt;predefined&gt;":
             print "This is a predefined entity"
      </example>
  </shell_doc>

  <shell_doc name="GPS.Entity.end_of_scope">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.FileLocation</return>
      <description>Return the location at which the end of the entity is found.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.body">
      <param name="self">The instance of GPS.Entity</param>
      <param name="nth" default="1">An integer</param>
      <return>An instance of GPS.FileLocation</return>
      <description>Return the location at which the implementation of the entity is found. For Ada subprograms and packages, this corresponds to the body of the entity. For Ada private types, this is the location of the full declaration for the type. For entities which do not have a notion of body, this returns the location of the declaration for the entity.
Some entities have several bodies. This is for instance the case of a separate subprogram in Ada, where the first body just indicates the subprogram is separate, and the second body provides the actual implementation. The nth parameter gives access to the other bodies. An exception is raised when there are not at least nth bodies.</description>
      <example lang="python">
           entity = GPS.Entity ("bar", GPS.File ("a.adb"), 10, 23)
           body = entity.body()
           print "The subprogram bar's implementation is found at " \
              + body.file.name() + ':' + body.line() + ':' + body.column()
      </example>
  </shell_doc>

  <shell_doc name="GPS.Entity.attributes">
      <param name="self">The instance of GPS.Entity</param>
      <return>A htable</return>
      <description>Return various boolean attributes of the entity: is the entity global, static, static for a class, protected,...</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.category">
      <param name="self">The instance of GPS.Entity</param>
      <return>A string</return>
      <description>Return the category of a given entity. Possible values include: label, literal, object, subprogram, package/namespace, type, unknown.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.find_all_refs">
      <param name="self">The instance of GPS.Entity</param>
      <param name="include_implicit" default="False">A boolean</param>
      <description>Display in the location window all the references to the entity. If include_implicit is true, then implicit uses of the entity will also be referenced, for instance when the entity appears as an implicit parameter to a generic instantiation in Ada</description>
      <see_also name="GPS.Entity.references()"/>
  </shell_doc>

  <shell_doc name="GPS.Entity.derived_types">
      <param name="self">The instance of GPS.Entity</param>
      <return>List of GPS.Entity</return>
      <description>Return a list of all the entities that are derived from self. For object-oriented languages, this includes types that extend self. In Ada, this also includes subtypes of self.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.type">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.Entity</return>
      <description>Return the type of the entity. For a variable, it is its type</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.pointed_type">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.Entity</return>
      <description>Return the type pointed to by entity. If self is not a pointer (or an Ada access type), None is returned. This function also applies to variables, and returns the same information as their type would</description>
      <example lang="python">
         ## Given the following Ada code:
         ##    type Int is new Integer;
         ##    type Ptr is access Int;
         ##    P : Ptr;
         ## the following requests would apply:

         f = GPS.File ("file.adb")
         GPS.Entity ("P", f).type()           # Ptr
         GPS.Entity ("P", f).pointed_type()   # Int
         GPS.Entity ("Ptr", f).pointed_type() # Int
       </example>
  </shell_doc>

  <shell_doc name="GPS.Entity.references">
      <param name="self">The instance of GPS.Entity</param>
      <param name="include_implicit" default="False">A boolean</param>
      <param name="synchronous" default="True">A boolean</param>
      <param name="show_kind"   default="False">A boolean</param>
      <param name="in_file"     default="None">An instance of GPS.File</param>
      <param name="kind_in"     default="">A string</param>
      <return>List of GPS.FileLocation, htable or GPS.Command</return>
      <description>List all references to the entity in the project sources. If include_implicit is true, then implicit uses of the entity will also
be referenced, for instance when the entity appears as an implicit parameter
to a generic instantiation in Ada. If synchronous is True, then the result will be directly returned, otherwise a command will be returned and its result will be accessible with get_result(). The result, then, is either a list of locations (if show_kind is False), or a htable indexed by location, and whose value is a string indicating the kind of the reference (declaration, body, label, end-of-spec,...).
The parameter in_file can be used to limit the search to references in a particular file. This is a lot faster.
The parameter kind_in is a list of comma-separated list of reference kinds (as would be returned when show_kind is True). Only such references are returned, as opposed to all references.
</description>
      <example lang="python">
         for r in GPS.Entity ("GPS", GPS.File("gps.adb")).references():
             print "One reference in " + r.file().name()
      </example>
      <see_also name="GPS.Entity.find_all_refs()"/>
  </shell_doc>

  <shell_doc name="GPS.Entity.primitive_of">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.Entity or None</return>
      <description>Return the type for which self is a primitive operation (or a method, in other languages than Ada)</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.methods">
      <param name="self">The instance of GPS.Entity</param>
      <param name="include_inherited" default="false">A boolean</param>
      <return>A list of instances of GPS.Entity</return>
      <description>Return the list of primitive operations (aka methods) for self. This list is not sorted</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.documentation">
      <param name="self">The instance of GPS.Entity</param>
      <param name="extended" default="false">A boolean</param>
      <return>A string</return>
      <description>Return the documentation for the entity. This is the comment block found just before or just after the declaration of the entity (if any such block exists). This is also the documentation string displayed in the tooltips when you leave the mouse cursor over an entity for a while. If extended is true, then the returned documentation will include formatting and full entity description.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.calls">
      <param name="self">The instance of GPS.Entity</param>
      <param name="dispatching_calls" default="false">A boolean</param>
      <return>A dictionary, see below</return>
      <description>Display the list of entities called by the entity. The returned value is a dictionary whose keys are instances of Entity called by this entity, and whose value is a list of FileLocation instances where the entity is referenced.
If dispatching_calls is true, then calls done through dispatching will result in multiple entities being listed (ie all the possible subprograms that are called at that location)</description>
      <param name="dispatching_calls" default="false">A boolean</param>
      <see_also name="GPS.Entity.is_called_by()"/>
  </shell_doc>

  <shell_doc name="GPS.Entity.called_by">
      <param name="self">The instance of GPS.Entity</param>
      <param name="dispatching_calls" default="false">A boolean</param>
      <return>A dictionary, see below</return>
      <description>Display the list of entities that call the entity. The returned value is a dictionary whose keys are instances of Entity calling this entity, and whose value is a list of FileLocation instances where the entity is referenced. This command might take a while to execute, since GPS needs to get the cross-reference information for lots of source files.
If dispatching_calls is true, then calls to self that might occur through dispatching are also listed.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.called_by_browser">
      <param name="self">The instance of GPS.Entity</param>
      <description>Open the call graph browser to show what entities call self</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.show">
      <param name="self">The instance of GPS.Entity</param>
      <description>Display in the type browser the informations known about the entity: list of fields for records, list of primitive subprograms or methods, list of parameters, ...</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.discriminants">
      <param name="self">The instance of GPS.Entity</param>
      <return>List of instances of GPS.Entity</return>
      <description>Return the list of discriminants for entity. This is a list of entities, empty if the type has no discriminant or if this notion doesn't apply to that language</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.fields">
      <param name="self">The instance of GPS.Entity</param>
      <return>List of instances of GPS.Entity</return>
      <description>Return the list of fields for entity. This is a list of entities. This applies to Ada record and tagged types, or C structs for instance.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.parameters">
      <param name="self">The instance of GPS.Entity</param>
      <return>List of instances of GPS.Entity</return>
      <description>Return the list of parameters for entity. This is a list of entities. This applies to subprograms.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.return_type">
      <param name="self">The instance of GPS.Entity</param>
      <return>An instance of GPS.Entity</return>
      <description>Return the return type for entity. This applies to subprograms.</description>
  </shell_doc>

  <shell_doc name="GPS.Entity.name_parameters">
      <param name="self">The instance of GPS.Entity</param>
      <param name="location">An instance of GPS.FileLocation</param>
      <description>Refactor the code at the location, to add named parameters. This only work if the language has support for such parameters, namely Ada for the time being</description>
      <example lang="python">
         GPS.Entity ("foo", GPS.File ("decl.ads")).rename_parameters \
            (GPS.FileLocation (GPS.File ("file.adb"), 23, 34))
      </example>
  </shell_doc>

  <shell_doc name="GPS.ReferencesCommand">
      <description>This is the type of the commands returned by the references extractor.</description>
      <see_also name="GPS.Command" />
      <see_also name="GPS.Entity.references" />
  </shell_doc>

  <shell_doc name="GPS.ReferencesCommand.get_result">
      <param name="self">The instance of GPS.ReferencesCommand</param>
      <return>A list of strings</return>
      <description>Returns the references that have been found so far by the command.</description>
      <see_also name="GPS.Entity.references()" />
  </shell_doc>

  <!--#################################################################
    ####   FileLocation class
    ###################################################################-->

  <shell_doc name="GPS.FileLocation">
      <description>Represents a location in a file</description>
      <see_also name="GPS.FileLocation.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.FileLocation.__str__">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.__repr__">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.__hash__">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>An integer</return>
      <description>Return a hash value suitable for storing self in a dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.__cmp__">
      <param name="self">The instance of GPS.FileLocation</param>
      <param name="file">An instance of GPS.FileLocation</param>
      <return>An integer</return>
      <description>Compare two instances of GPS.FileLocation, and return -1, 0 or 1 depending on their relative sort order</description>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.__init__">
      <param name="self">The instance we are building</param>
      <param name="filename">An instance of GPS.File</param>
      <param name="line">An integer</param>
      <param name="column">An integer</param>
      <description>Initializes a new instance of GPS.FileLocation.</description>
      <example lang="python">
          location = GPS.FileLocation (GPS.File ("a.adb"), 1, 2)
      </example>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.line">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>An integer, the line of the location</return>
      <description>Return the line of the location</description>
      <see_also>GPS.FileLocation.file()</see_also>
      <see_also>GPS.FileLocation.column()</see_also>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.column">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>An integer, the column of the location</return>
      <description>Return the column of the location</description>
      <see_also>GPS.FileLocation.file()</see_also>
      <see_also>GPS.FileLocation.line()</see_also>
  </shell_doc>

  <shell_doc name="GPS.FileLocation.file">
      <param name="self">The instance of GPS.FileLocation</param>
      <return>An instance of GPS.File, the file of the location</return>
      <description>Return the file of the location</description>
      <see_also>GPS.FileLocation.line()</see_also>
      <see_also>GPS.FileLocation.column()</see_also>
  </shell_doc>

  <!--#################################################################
    ####   Project class
    ###################################################################-->

  <shell_doc name="GPS.Project">
      <description>Represents a project file. See also the GPS documentation on how to create new project attributes.

Related hooks:
   "project_view_changed": Called whenever the project is recomputed, ie one
      of its attributes was changed by the user, the environment variables are
      changed,...
      Then is a good time to test the list of languages
      (GPS.Project.languages()) that the project supports, and do
      language-specific customizations

   "project_changed": A new project was loaded. The hook above will be called
      after this one
</description>
      <see_also name="GPS.Project.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Project.__str__">
      <param name="self">The instance of GPS.Project</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.Project.__repr__">
      <param name="self">The instance of GPS.Project</param>
      <return>A string</return>
      <description>Return a string suitable for the display of self on screen. This is called implicitly by GPS and Python</description>
  </shell_doc>

  <shell_doc name="GPS.Project.__hash__">
      <param name="self">The instance of GPS.Project</param>
      <return>An integer</return>
      <description>Return a hash value suitable for storing self in a dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.Project.__cmp__">
      <param name="self">The instance of GPS.Project</param>
      <param name="file">An instance of GPS.Project</param>
      <return>An integer</return>
      <description>Compare two instances of GPS.Project, and return -1, 0 or 1 depending on their relative sort order</description>
  </shell_doc>

  <shell_doc name="GPS.Project.__init__">
      <param name="self">The instance of GPS.Project that we are building</param>
      <param name="name">The project name</param>
      <description>Initializes an instance of GPS.Project. The project must be currently loaded in GPS</description>
      <see_also name="GPS.Project.name"/>
  </shell_doc>

  <shell_doc name="GPS.Project.root">
      <return>An instance of GPS.Project</return>
      <description>Return the root project currently loaded in GPS</description>
      <example lang="python">
           print "Current project is " + \
                 GPS.Project.root().name()
      </example>
  </shell_doc>

  <shell_doc name="GPS.Project.update_xref">
     <param name="self">The instance of GPS.Project</param>
     <param name="recursive" default="False">A boolean</param>
     <description>Updates the cross-reference information in memory for all files of the project. This doesn't regenerate that information, just read all the .ali files found in the object directory of the project (and all imported projects if recursive is True). This should generally be called before calling GPS.freeze_xref, for efficiency.</description>
  </shell_doc>

  <shell_doc name="GPS.Project.is_modified">
     <param name="self">The instance of GPS.Project</param>
     <param name="recursive" default="False">A boolean</param>
     <return>A boolean</return>
     <description>Return True if the project has been modified but not saved yet. If recursive is true, then the return value takes into account all projects imported by self</description>
  </shell_doc>

  <shell_doc name="GPS.Project.dependencies">
      <param name="self">The instance of GPS.Project</param>
      <param name="recursive" default="False">A boolean</param>
      <return>A list of GPS.Project instances</return>
      <description>Return the list of projects on which self depends (either directly if recursive is False, or including indirect dependencies if recursive is True).</description>
  </shell_doc>

  <shell_doc name="GPS.Project.recompute">
       <description>Recompute the contents of a project, including the list of source files that are automatically loaded from the source directories. The project file is not reloaded from the disk, and this should only be used if you have created new source files outside of GPS for instance</description>
       <example lang="python">
            GPS.Project.recompute()
       </example>
  </shell_doc>

  <shell_doc name="GPS.Project.load">
       <param name="filename">A string, the full path to a project file</param>
       <param name="force" default="False">A boolean</param>
       <return>An instance of GPS.Project</return>
       <description>Load a new project, which replaces the current root project, and return a handle to it. All imported projects are also loaded at the same time. If the project is not found, a default project is loaded.
If force is True, then the user will not be asked whether to save the current project, whether it was modified or not</description>
  </shell_doc>

  <shell_doc name="GPS.Project.name">
       <param name="self">An instance of GPS.Project</param>
       <return>A string, the name of the project</return>
       <description>Return the name of the project. This doesn't include directory information, see self.file().name() if you wish to access that information</description>
  </shell_doc>

  <shell_doc name="GPS.Project.rename">
       <param name="self">An instance of GPS.Project</param>
       <param name="name">A string</param>
       <param name="path" default="&lt;current path&gt;">A string</param>
       <description>Rename and move a project file (the project will only be put in the new directory when it is saved, but will not be removed from its original directory). You must call GPS.Project.recompute() sometime after changing the name.</description>
  </shell_doc>

  <shell_doc name="GPS.Project.file">
       <param name="self">An instance of GPS.Project</param>
       <return>An instance of GPS.File</return>
       <description>Return the project file</description>
  </shell_doc>

  <shell_doc name="GPS.Project.properties_editor">
       <param name="self">An instance of GPS.Project</param>
       <description>Launch a graphical properties editor for the project</description>
  </shell_doc>

  <shell_doc name="GPS.Project.ancestor_deps">
       <param name="self">An instance of GPS.Project</param>
       <return>A list of instances of GPS.Project</return>
       <description>Return the list of projects that might contain sources that depend on the project's sources. When doing extensive searches it isn't worth checking other projects. Project itself is included in the list.
This is also the list of projects that import self.</description>
       <example lang="python">
           for p in GPS.Project("kernel").ancestor_deps(): print p.name()
           will print the name of all the projects that import kernel.gpr
       </example>
  </shell_doc>

  <shell_doc name="GPS.Project.get_attribute_as_string">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package" default="">A string, the name of the attribute's package</param>
       <param name="index" default="">A string, the name of the index for the specific value of this attribute</param>
       <return>A string, the value of this attribute</return>
       <description>Fetch the value of the attribute in the project.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.
If the attribute value is stored as a list, the result string is a concatenation of all the elements of the list. This function always returns the value of the attribute in the currently selected scenario.
When the attribute is not explicitely overridden in the project, the default value is returned. This default value is the one described in an XML file (see the GPS documentation for more information). This default value is not necessarily valid, and could for instance be a string starting with a parenthesis, as explained in the GPS documentation.</description>
       <example lang="python">
           If the project file contains the following text:
               project Default is
                 for Exec_Dir use "exec/";
                 package Compiler is
                    for Switches ("file.adb") use ("-c", "-g");
                 end Compiler;
               end Default;

            Then the following commands;
                a = GPS.Project ("default").get_attribute_as_string ("exec_dir")
                b = GPS.Project ("default").get_attribute_as_string ("switches", package="compiler", index="file.adb")

            will set the variables to
                a = "exec/"
                b = "-c -g"
       </example>
       <see_also name="GPS.Project.scenario_variables()"/>
       <see_also name="GPS.Project.get_attribute_as_list()"/>
       <see_also name="GPS.Project.get_tool_switches_as_string()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.get_attribute_as_list">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package" default="">A string, the name of the attribute's package</param>
       <param name="index" default="">A string, the name of the index for the specific value of this attribute</param>
       <return>A list of strings</return>
       <description>Fetch the value of the attribute in the project.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.
If the attribute value is stored as a simple string, a list with a single element is returned. This function always returns the value of the attribute in the currently selected scenario.</description>
       <example lang="python">
           If the project file contains the following text:
               project Default is
                 for Exec_Dir use "exec/";
                 package Compiler is
                    for Switches ("file.adb") use ("-c", "-g");
                 end Compiler;
               end Default;

            Then the following commands;
                a = GPS.Project ("default").get_attribute_as_list ("exec_dir")
                b = GPS.Project ("default").get_attribute_as_list ("switches", package="compiler", index="file.adb")

            will set the variables to
                a = ("exec/")
                b = ("-c", "-g")
       </example>
       <see_also name="GPS.Project.scenario_variables()"/>
       <see_also name="GPS.Project.get_attribute_as_string()"/>
       <see_also name="GPS.Project.get_tool_switches_as_list()"/>
  </shell_doc>

  <shell_doc name = "GPS.Project.set_attribute_as_string">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package">A string, the name of the attribute's package</param>
       <param name="index">A string, the name of the index for the specific value of this attribute</param>
       <param name="value">A string, the name of the value to set</param>
       <description>Sets the value of an attribute. The attribute has to be stored as a single value.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.</description>
       <see_also name="GPS.Project.add_attribute_values()"/>
       <see_also name="GPS.Project.remove_attribute_values()"/>
       <see_also name="GPS.Project.clear_attribute_values()"/>
  </shell_doc>

  <shell_doc name = "GPS.Project.add_attribute_values">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package">A string, the name of the attribute's package</param>
       <param name="index">A string, the name of the index for the specific value of this attribute</param>
       <param name="value">A string, the name of the first value to add</param>
       <description> Add some values to an attribute. You can add as much as many values you need at the end of the param list.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.</description>
       <example lang="python">
	       GPS.Project.root().add_attribute_values ("Default_Switches", "Compiler", "ada", "-gnatwa", "-gnatwe");
       </example>
       <see_also name="GPS.Project.set_attribute_as_string()"/>
       <see_also name="GPS.Project.remove_attribute_values()"/>
       <see_also name="GPS.Project.clear_attribute_values()"/>
  </shell_doc>

  <shell_doc name = "GPS.Project.remove_attribute_values">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package">A string, the name of the attribute's package</param>
       <param name="index">A string, the name of the index for the specific value of this attribute</param>
       <param name="value">A string, the name of the first value to remove</param>
       <description> Removes some specific values from an attribute. You can set as much as many values you need at the end of the param list.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.</description>
       <example lang="python">
	       GPS.Project.root().remove_attribute_values ("Default_Switches", "Compiler", "ada", "-gnatwa", "-gnatwe");
       </example>
       <see_also name="GPS.Project.set_attribute_as_string()"/>
       <see_also name="GPS.Project.add_attribute_values()"/>
       <see_also name="GPS.Project.clear_attribute_values()"/>
  </shell_doc>

  <shell_doc name = "GPS.Project.clear_attribute_values">
       <param name="self">An instance of GPS.Project</param>
       <param name="attribute">A string, the name of the attribute</param>
       <param name="package">A string, the name of the attribute's package</param>
       <param name="index">A string, the name of the index for the specific value of this attribute</param>
       <description> Clear the values list of an attribute.
If the package is not specified, the attribute at the toplevel of the project is queried.
The index only needs to be specified if it applies to that attribute.</description>
  </shell_doc>

  <shell_doc name="GPS.Project.scenario_variables_values">
       <return>A hash table of strings</return>
       <description>Return a hash table where keys are the various scenario variables defined in the current project and values the different values that this variable can get.</description>
  </shell_doc>

  <shell_doc name="GPS.Project.get_tool_switches_as_list">
       <param name="self">An instance of GPS.Project</param>
       <param name="tool">The name of the tool whose switches you want to get</param>
       <return>A list of strings</return>
       <description>Same as get_attribute_as_list, but specialized for the switches of a specific tool. Tools are defined through XML customization files, see the GPS documentation for more information</description>
       <example lang="python">
           If GPS has loaded a customization file that contains the following
           tags:
               &lt;?xml version="1.0" ?&gt;
               &lt;toolexample&gt;
                  &lt;tool name="Find"&gt;
                     &lt;switches&gt;
                        &lt;check label="Follow links" switch="-follow" /&gt;
                     &lt;/switches&gt;
                  &lt;/tool&gt;
               &lt;/toolexample&gt;

           The user will as a result be able to edit the switches for Find in
           the standard Project Properties editor.

           Then the python command
               GPS.Project ("default").get_tool_switches_as_list ("Find")
           will return the list of switches that were set by the user in the
           Project Properties editor.
       </example>
       <see_also name="GPS.Project.get_attribute_as_list()"/>
       <see_also name="GPS.Project.get_tool_switches_as_string()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.get_tool_switches_as_string">
       <param name="self">An instance of GPS.Project</param>
       <param name="tool">The name of the tool whose switches you want to get</param>
       <return>A string</return>
       <description>Same as GPS.Project.get_attribute_as_string, but specialized for a specific tool.</description>
       <see_also name="GPS.Project.get_tool_switches_as_list()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.scenario_variables">
     <return>hash table associating variable names and values</return>
     <description>Return the list of scenario variables for the current project hierarchy, and their current value. These variables are visible at the top of the Project View in the GPS window. The initial value for these variables is set from the environment variables' value when GPS is started. However, changing the value of the environment variable later on doesn't change the value of the scenario variable.</description>
     <example lang="python">
        GPS.Project.scenario_variables()["foo"]
        returns the current value for the variable foo
     </example>
     <see_also name="GPS.Project.set_scenario_variable()" />
  </shell_doc>

  <shell_doc name="GPS.Project.set_scenario_variable">
      <param name="name">A string</param>
      <param name="value">A string</param>
      <description>Change the value of a scenario variable. You need to call GPS.Project.recompute() to activate this change (so that multiple changes to the project can be grouped</description>
      <see_also name="GPS.Project.scenario_variables()" />
  </shell_doc>

  <shell_doc name="GPS.Project.scenario_variables_cmd_line">
     <param name="prefix" default="">String to print before each variable in the output</param>
     <return>a string</return>
     <description>Return a concatenation of VARIABLE=VALUE, each preceded by the given prefix. This string will generally be used when calling external tools, for instance make or GNAT</description>
     <example lang="python">
        The following GPS action can be defined in an XML file, and will launch
        the make command with the appropriate setup for the environment
        variables:
           &lt;action name="launch make"&gt; \
             &lt;shell lang="python"&gt;GPS.scenario_variables_cmd_line()&lt;/shell&gt;  \
             &lt;external&gt;make %1&lt;/external&gt; \
           &lt;/action&gt;
     </example>
  </shell_doc>

  <shell_doc name="GPS.Project.add_main_unit">
      <param name="self">The instance of GPS.Project</param>
      <param name="...">Any number of arguments, at least one</param>
      <description>Add some main units to the current project, and for the current scenario. The project is not saved automatically</description>
  </shell_doc>

  <shell_doc name="GPS.Project.remove_dependency">
      <param name="self">The instance of GPS.Project</param>
      <param name="imported">An instance of GPS.Project</param>
      <description>Remove a dependency between two projects. You must call GPS.Project.recompute() once you are done doing all the modifications on the projects</description>
      <see_also name="GPS.Project.add_dependency()" />
  </shell_doc>

  <shell_doc name="GPS.Project.add_dependency">
      <param name="self">The instance of GPS.Project</param>
      <param name="path">The path to another project to depend on</param>
      <description>This commands adds a new dependency from self to the project file pointed to by path. This is the equivalent of putting a with clause in self, and means that the source files in self can depend on source files from the imported project</description>
      <see_also name="GPS.Project.remove_dependency()" />
  </shell_doc>

  <shell_doc name="GPS.Project.add_predefined_paths">
       <param name="sources" default="">A list of directories separated by the appropriate separator (':' or ';' depending on the system</param>
       <param name="objects" default="">As above</param>
       <description>Add some predefined directories to the source path or the objects path. These will be searched when GPS needs to open a file by its base name, in particular from the File->Open From Project dialog.
The new paths are added in front, so that they have priorities over previously defined paths.</description>
       <example lang="python">
           GPS.Project.add_predefined_paths (os.pathsep.join (sys.path))
       </example>
  </shell_doc>

  <shell_doc name="GPS.Project.sources">
      <param name="self">The instance of GPS.Project</param>
      <param name="recursive" default="false">A boolean</param>
      <return>A list of instances of GPS.File</return>
      <description>Return the list of source files for this project. If recursive is true, then all sources from imported projects are also returned. Otherwise, only the direct sources are returned. The basenames of the returned files are always unique: not two files with the same basenames are returned, and the one returned is the first one see while traversing the project hierarchy</description>
  </shell_doc>

  <shell_doc name="GPS.Project.source_dirs">
      <param name="self">The instance of GPS.Project</param>
      <param name="recursive" default="false">A boolean</param>
      <return>A list of strings</return>
      <description>Return the list of source directories for this project. If Recursive is True, the source directories of imported projects is also returned. There might be duplicate directories in the returned list</description>
      <see_also name="GPS.Project.add_source_dir()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.languages">
      <param name="self">The instance of GPS.Project</param>
      <param name="recursive" default="false">A boolean</param>
      <return>A list of strings</return>
      <description>Return the list of languages that are used for the sources of the project (and its subprojects if recursive is True). This can be used to detect whether some specific action in a module should be activated or not. Language names are always lowercase</description>
      <example lang="python">
          The following example adds a new menu only if the current project
          supports C. This is refreshed every time the project is changed by
          the user.

          import GPS
          c_menu=None

          def project_recomputed (hook_name):
            global c_menu
            try:
               ## Check whether python is supported
               GPS.Project.root().languages (recursive=True).index ("c")
               if c_menu == None:
                  c_menu = GPS.Menu.create ("/C support")
            except:
               if c_menu:
                  c_menu.destroy()
                  c_menu = None

          GPS.Hook ("project_view_changed").add (project_recomputed)
      </example>
  </shell_doc>

  <shell_doc name="GPS.Project.object_dirs">
      <param name="self">The instance of GPS.Project</param>
      <param name="recursive" default="false">A boolean</param>
      <return>A list of strings</return>
      <description>Return the list of object directories for this project. If Recursive is True, the source directories of imported projects is also returned. There might be duplicate directories in the returned list</description>
  </shell_doc>

  <shell_doc name="GPS.Project.add_source_dir">
      <param name="self">The instance of GPS.Project</param>
      <param name="directory">A string</param>
      <description>Add a new source directory to the project. The new directory is added in front of the source path. You should call recompute() after calling this method, to recompute the list of source files. The directory is added for the current value of the scenario variables only. Note that if the current source directory for the project is not specified explicitly in the .gpr file), it will be overriden by the new directory you are adding. If the directory is already part of the source directories for the project, it is not added a second time.</description>
      <see_also name="GPS.Project.source_dirs()"/>
      <see_also name="GPS.Project.remove_source_dir()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.remove_source_dir">
      <param name="self">The instance of GPS.Project</param>
      <param name="directory">A string</param>
      <description>Remove a source directory from the project. You should call recompute() after calling this method, to recompute the list of source files. The directory is added for the current value of the scenario variables only</description>
      <see_also name="GPS.Project.add_source_dir()"/>
  </shell_doc>

  <shell_doc name="GPS.Project.search">
      <param name="self">The instance of GPS.Project</param>
      <param name="pattern">A string</param>
      <param name="case_sensitive" default="False">A boolean</param>
      <param name="regexp" default="False">A boolean</param>
      <param name="scope" default="whole">One of ("whole", "comments", "strings", "code")</param>
      <param name="recursive" default="True">A boolean</param>
      <return>A list of GPS.FileLocation instances</return>
      <description>Return the list of matches for pattern in all the files belonging to the project (and its imported projects if recursive is true (default). Scope is a string, and should be any of 'whole', 'comments', 'strings', 'code'. The latter will match only for text outside of comments</description>
  </shell_doc>

  <shell_doc name="GPS.Project.set_property">
     <param name="self">The instance of GPS.Project</param>
     <param name="name">A string</param>
     <param name="value">A string</param>
     <param name="persistent" default="False">A boolean</param>
     <description>Associates a string property with the project. This property is retrievable during the whole GPS session, or across GPS sessions if persistent is set to True.
This is different than setting instance properties through Python's standard mechanism in that there is no garantee that the same instance of GPS.Project will be created for each physical project on the disk, and therefore you would not be able to associate a property with the physical project itself</description>
     <see_also name="GPS.Project.get_property" />
     <see_also name="GPS.Project.remove_property" />
     <see_also name="GPS.File.set_property" />
  </shell_doc>

  <shell_doc name="GPS.Project.get_property">
     <param name="self">The instance of GPS.Project</param>
     <param name="name">A string</param>
     <return>A string</return>
     <description>Return the value of the property associated with the project. This property might have been set in a previous GPS session if it is persistent. An exception is raised if no such property already exists for the project</description>
     <see_also name="GPS.Project.set_property" />
  </shell_doc>

  <shell_doc name="GPS.Project.remove_property">
     <param name="self">The instance of GPS.Project</param>
     <param name="name">A string</param>
     <description>Removes a property associated with a project</description>
     <see_also name="GPS.Project.set_property" />
  </shell_doc>

  <shell_doc name="GPS.Project.generate_doc">
     <param name="self">The instance of GPS.Project</param>
     <param name="recursive" default="False">A boolean</param>
     <description>Generate the documentation of the project and its subprojects if recursive is True, and display it with the default browser</description>
     <see_also name="GPS.File.generate_doc"/>
  </shell_doc>

  <shell_doc name="GPS.Project.get_executable_name">
     <param name="self">The instance of GPS.Project</param>
     <param name="main">GPS.File</param>
     <return>A string</return>
     <description>Return the name of the executable, either read from the project or computed from main</description>
  </shell_doc>

  <!--#################################################################
    ####  Editor class
    ###################################################################-->

  <shell_doc name="GPS.Editor">
      <description>Interface to all editor-related commands</description>
      <obsolescent />
  </shell_doc>

  <shell_doc name="GPS.Editor.edit">
      <obsolescent />
      <param name="filename">A string</param>
      <param name="line" default="1">An integer</param>
      <param name="column" default="1">An integer</param>
      <param name="length" default="0">An integer</param>
      <param name="force" default="false">A boolean</param>
      <param name="position" default="5">An integer</param>
      <description>Open a file editor for file_name. Length is the number of characters to select after the cursor. If line and column are set to 0, then the location of the cursor is not changed if the file is already opened in an editor. If force is set to true, a reload is forced in case the file is already open. Position indicates the MDI position to open the child in (5 for default, 1 for bottom).

The filename can be a network file name, with the following general format:
   protocol://username@host:port/full/path
where protocol is one of the recognized protocols (http, ftp,.. see the GPS documentation), and the username and port are optional.
</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.create_mark">
      <obsolescent />
      <param name="filename">A string</param>
      <param name="line" default="1">An integer</param>
      <param name="column" default="1">An integer</param>
      <param name="length" default="0">An integer</param>
      <return>A string</return>
      <description>Create a mark for file_name, at position given by line and column. Length corresponds to the text length to highlight after the mark. The identifier of the mark is returned. Use the command goto_mark to jump to this mark</description>
      <see_also name="GPS.Editor.goto_mark()"/>
      <see_also name="GPS.Editor.delete_mark()"/>
  </shell_doc>

  <shell_doc name="GPS.Editor.highlight">
      <obsolescent />
      <param name="file">A string</param>
      <param name="category">A string</param>
      <param name="line" default="0">An integer</param>
      <description>Marks a line as belonging to a highlighting category. If line is not specified, mark all lines in file.</description>
      <see_also name="GPS.Editor.unhighlight()"/>
  </shell_doc>

  <shell_doc name="GPS.Editor.add_blank_lines">
      <obsolescent />
      <param name="file">A string</param>
      <param name="start_line">An integer</param>
      <param name="number_of_lines">An integer</param>
      <param name="category" default="">A string</param>
      <description>Adds number_of_lines non-editable lines to the buffer editing file, starting at line start_line. If category is specified, use it for highlighting. Create a mark at beginning of block and return its ID</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.remove_blank_lines">
      <obsolescent />
      <param name="mark">A string</param>
      <param name="number" default="0">An integer</param>
      <description>Remove blank lines located at mark. If number is specified, remove only the number first lines</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_fold">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line" default="">An integer</param>
      <description>Fold the block around line. If line is not specified, fold all blocks in the file.</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_unfold">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line" default="">An integer</param>
      <description>Unfold the block around line. If line is not specified, unfold all blocks in the file.</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.unhighlight">
      <obsolescent />
      <param name="file">A string</param>
      <param name="category">A string</param>
      <param name="line" default="0">An integer</param>
      <description>Unmarks the line for the specified category. If line is not specified, unmark all lines in file</description>
      <see_also name="GPS.Editor.highlight()"/>
  </shell_doc>

  <shell_doc name="GPS.Editor.highlight_range">
      <obsolescent />
      <param name="file">A string</param>
      <param name="category">A string</param>
      <param name="line" default="0">An integer</param>
      <param name="start_column" default="0">An integer</param>
      <param name="end_column" default="-1">An integer</param>
      <description>Highlights a portion of a line in a file with the given category</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.unhighlight_range">
      <obsolescent />
      <param name="file">A string</param>
      <param name="category">A string</param>
      <param name="line" default="0">An integer</param>
      <param name="start_column" default="0">An integer</param>
      <param name="end_column" default="-1">An integer</param>
      <description>Remove highlights for a portion of a line in a file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.register_highlighting">
      <obsolescent />
      <param name="category">A string</param>
      <param name="color">A string</param>
      <param name="speedbar" default="False">A boolean</param>
      <description>Create a new highlighting category with the given color. The format for color is "#RRGGBB". If speedbar is true, then a mark will be inserted in the speedbar to the left of the editor to give a fast overview to the user of where the highlighted lines are.</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.set_background_color">
      <obsolescent />
      <param name="file">A string</param>
      <param name="color">A string</param>
      <description>Set the background color for the editors for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.goto_mark">
      <obsolescent />
      <param name="identifier">A string</param>
      <description>Jump to the location of the mark corresponding to identifier</description>
      <see_also name="GPS.Editor.create_mark"/>
  </shell_doc>

  <shell_doc name="GPS.Editor.delete_mark">
      <obsolescent />
      <param name="identifier">A string</param>
      <description>Delete the mark corresponding to identifier</description>
      <see_also name="GPS.Editor.create_mark"/>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_chars">
      <obsolescent />
      <param name="filename">A string</param>
      <param name="line" default="0">An integer</param>
      <param name="column" default="1">An integer</param>
      <param name="before" default="-1">An integer</param>
      <param name="after" default="-1">An integer</param>
      <return>A string</return>
      <description>Get the characters around a certain position. Returns string between "before" characters before the mark and "after" characters after the position. If "before" or "after" is omitted, the bounds will be at the beginning and/or the end of the line.
If the line and column are not specified, then the current selection is returned, or the empty string if there is no selection</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_line">
      <obsolescent />
      <param name="mark">An identifier</param>
      <return>An integer</return>
      <description>Returns the current line of mark</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_column">
      <obsolescent />
      <param name="mark">An identifier</param>
      <return>An integer</return>
      <description>Returns the current column of mark</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_file">
      <obsolescent />
      <param name="mark">An identifier</param>
      <return>A file</return>
      <description>Returns the current file of mark</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_last_line">
      <obsolescent />
      <param name="file">A string</param>
      <return>An integer</return>
      <description>Returns the number of the last line in file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_get_start">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>An integer</return>
      <description>Returns ending line number for block enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_get_end">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>An integer</return>
      <description>Returns ending line number for block enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_get_name">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>A string</return>
      <description>Returns name for block enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_get_type">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>A string</return>
      <description>Returns type for block enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.block_get_level">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>An integer</return>
      <description>Returns nested level for block enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.subprogram_name">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <return>A string</return>
      <description>Returns the name of the subprogram enclosing line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.cursor_get_line">
      <obsolescent />
      <param name="file">A string</param>
      <return>An integer</return>
      <description>Returns current cursor line number</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.cursor_get_column">
      <obsolescent />
      <param name="file">A string</param>
      <return>An integer</return>
      <description>Returns current cursor column number</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.cursor_set_position">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <param name="column" default="1">An integer</param>
      <description>Set cursor to position line/column in buffer file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.cursor_center">
      <obsolescent />
      <param name="file">A string</param>
      <description>Scroll the view to center cursor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.get_buffer">
      <obsolescent />
      <param name="file">A string</param>
      <description>Returns the text contained in the current buffer for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.save_buffer">
      <obsolescent />
      <param name="file">A string</param>
      <param name="to_file" default="">A string</param>
      <description>Saves the text contained in the current buffer for file. If to_file is specified, the file will be saved as to_file, and the buffer status will not be modified</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.replace_text">
      <obsolescent />
      <param name="file">A string</param>
      <param name="line">An integer</param>
      <param name="column">An integer</param>
      <param name="text">A string</param>
      <param name="before" default="-1">An integer</param>
      <param name="after" defalt="-1">An integer</param>
      <description>Replace the characters around a certain position. "before" characters before (line, column), and up to "after" characters after are removed, and the new text is inserted instead. If "before" or "after" is omitted, the bounds will be at the beginning and/or the end of the line</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.indent">
      <obsolescent />
      <param name="current_line_only" default="False">A boolean</param>
      <description>Indent the selection (or the current line if requested) in current editor. Do nothing if the current GPS window is not an editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.indent_buffer">
      <obsolescent />
      <description>Indent the current editor. Do nothing if the current GPS window is not an editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.refill">
      <obsolescent />
      <description>Refill selected (or current) editor lines. Do nothing if the current GPS window is not an editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.cut">
      <obsolescent />
      <description>Cut the selection in the current editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.copy">
      <obsolescent />
      <description>Copy the selection in the current editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.paste">
      <obsolescent />
      <description>Paste the selection in the current editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.select_all">
      <obsolescent />
      <description>Select the whole editor contents</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.select_text">
      <obsolescent />
      <param name="first_line">An integer</param>
      <param name="last_line">An integer</param>
      <param name="start_column" default="1">An integer</param>
      <param name="end_column" default="0">An integer</param>
      <description>Select a block in the current editor</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.insert_text">
      <obsolescent />
      <param name="text">A string</param>
      <description>Insert a text in the current editor at the cursor position</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.undo">
      <obsolescent />
      <param name="file">A string</param>
      <description>Undo the last edition command for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.redo">
      <obsolescent />
      <param name="file">A string</param>
      <description>Redo the last undone edition command for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.close">
      <obsolescent />
      <param name="file">A string</param>
      <description>Close all file editors for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.set_title">
      <obsolescent />
      <param name="file">A string</param>
      <param name="title">A string</param>
      <param name="filename">A string</param>
      <description>Change the title of the buffer containing the given file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.set_writable">
      <obsolescent />
      <param name="file">A string</param>
      <param name="writable">A boolean</param>
      <description>Change the Writable status for the editors for file</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.save">
      <obsolescent />
      <param name="interactive" default="True">A boolean</param>
      <param name="all" default="True">A boolean</param>
      <description>Save current or all files. If interactive is true, then prompt before each save. If all is true, then all files are saved</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.set_synchronized_scrolling">
      <obsolescent />
       <param name="file1">A string</param>
       <param name="file2">A string</param>
       <param name="file3" default="">A string</param>
       <description>Synchronize the scrolling between multiple editors</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.add_case_exception">
      <obsolescent />
       <param name="name">A string</param>
       <description>Add name into the case exception dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.remove_case_exception">
      <obsolescent />
       <param name="name">A string</param>
       <description>Remove name from the case exception dictionary</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.print_line_info">
       <param name="file">A string</param>
       <param name="line">An integer</param>
       <description>Print the contents of the items attached to the side of a line. This is used mainly for debugging and testing purposes.</description>
  </shell_doc>

  <shell_doc name="GPS.Editor.mark_current_location">
      <description>Push the location in the current editor in the history of locations.
      This should be called before jumping to a new location on a user's
      request, so that he can easily choose to go back to the previous
     location.</description>
  </shell_doc>

  <!--#################################################################
    ####  VCS class
    ###################################################################-->

  <shell_doc name="GPS.VCS">
     <description>General interface to version control systems</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.supported_systems">
      <return>List of strings</return>
      <description>Show the list of supported VCS systems</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.set_reference">
      <param name="file">A string</param>
      <param name="reference">A string</param>
      <description>Record a reference file (the file on which a diff buffer is based for example) for a given file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.get_status">
      <param name="file">A string</param>
      <description>Query the status for file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.update">
      <param name="file">A string</param>
      <description>Update file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.commit">
      <param name="file">A string</param>
      <description>Commit file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.diff_head">
      <param name="file">A string</param>
      <description>Show differences between local file and the head revision</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.diff_working">
      <param name="file">A string</param>
      <description>Show differences between local file and the working revision</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.annotate">
      <param name="file">A string</param>
      <description>Display the annotations for file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.remove_annotations">
      <param name="file">A string</param>
      <description>Remove the annotations for file</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.log">
      <param name="file">A string</param>
      <param name="revision">A string</param>
      <description>Get the revision changelog for file. If revision is specified, query the changelog for this specific revision, otherwise query the entire changelog</description>
  </shell_doc>
`
  <shell_doc name="GPS.VCS.annotations_parse">
      <param name="vcs_identifier">A string</param>
      <param name="file">A string</param>
      <param name="output">A string</param>
      <description>Parses the output of the annotations command (cvs annotate for instance), and add the corresponding information to the left of the editor</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.status_parse">
      <param name="vcs_identifier">A string</param>
      <param name="string">A string</param>
      <param name="clear_logs">A boolean</param>
      <param name="local">A boolean</param>
      <param name="dir" default="">A string</param>
      <description>Parses a string for VCS status. This command uses the parsers defined in the XML description node for the VCS corresponding to vcs_identifier.
   - When local is FALSE, the parser defined by the node status_parser is used.
   - When local is TRUE, the parser defined by the node local_status_parser is used.
 If clear_logs is TRUE, the revision logs editors are closed for files that have the VCS status "up-to-date".
 Parameter dir indicates the directory in which the files matched in string are located.</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.update_parse">
      <param name="vcs_identifier">A string</param>
      <param name="string">A string</param>
      <param name="dir" default="">A string</param>
      <description>Parses a string for VCS status. This command uses the parsers defined in the XML description node for the VCS corresponding to vcs_identifier.
 Parameter dir indicates the directory in which the files matched in string are located.</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.log_parse">
      <param name="vcs_identifier">A string</param>
      <param name="file">A string</param>
      <param name="string">A string</param>
      <description>Parses string to find log entries for file. This command uses the parser in the XML description node for the VCS corresponding to vcs_identifier.</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.revision_parse">
      <param name="vcs_identifier">A string</param>
      <param name="file">A string</param>
      <param name="string">A string</param>
      <description>Parses string to find revisions tags and branches information for file. This command uses the parser in the XML description node for the VCS corresponding to vcs_identifier.</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.repository_dir">
      <param name="tag_name" default="">A string</param>
      <description>Returns the repository root directory, or if tag_name is specified the repository directory for the given tag or branch.</description>
  </shell_doc>

  <shell_doc name="GPS.VCS.repository_path">
      <param name="file">A string</param>
      <param name="tag_name" default="">A string</param>
      <description>Returns the trunk repository path for file or if tag_name is specified the repository path on the given tag or branch path.</description>
  </shell_doc>

  <!--#################################################################
    ####  Activities class
    ###################################################################-->

  <shell_doc name="GPS.Activities">
     <description>General interface to version control activities systems</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.__init__">
      <param name="self">The instance being constructed</param>
      <param name="name">Activity's name to be given to this instance</param>
      <return>An instance of GPS.Activities</return>
      <description>Creates a new activity and returns its instance</description>
      <example lang="python">
         a=GPS.Activities("Fix loading order")
         print a.id()
      </example>
  </shell_doc>

  <shell_doc name="GPS.Activities.list">
      <return>A list of all activities's id defined</return>
      <description>Returns the list of all activities's id</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.get">
      <param name="id">The unique activity's id</param>
      <return>An instance of GPS.Activities</return>
      <description>Returns the activity given its id</description>
      <see_also name="GPS.Activities.list()"/>
  </shell_doc>

  <shell_doc name="GPS.Activities.from_file">
      <param name="file">An instance of GPS.File</param>
      <return>An instance of GPS.Activities</return>
      <description>Returns the activity containing the given file</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.name">
      <param name="self">The instance of GPS.Activities</param>
      <return>A string</return>
      <description>Returns the activity's name</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.id">
      <param name="self">The instance of GPS.Activities</param>
      <return>A string</return>
      <description>Returns the activity's unique id</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.has_log">
      <param name="self">The instance of GPS.Activities</param>
      <return>A boolean</return>
      <description>Returns true if the activity has a log present</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.log_file">
      <param name="self">The instance of GPS.Activities</param>
      <return>A file</return>
      <description>Returns the activity's log file</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.log">
      <param name="self">The instance of GPS.Activities</param>
      <return>A string</return>
      <description>Returns the activity's log content</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.is_closed">
      <param name="self">The instance of GPS.Activities</param>
      <return>A boolean</return>
      <description>Returns true if the activity is closed</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.set_closed">
      <param name="self">The instance of GPS.Activities</param>
      <param name="status">A boolean</param>
      <description>Set the activity's closed status</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.group_commit">
      <param name="self">The instance of GPS.Activities</param>
      <return>A boolean</return>
      <description>Returns true if the activity will be commit atomically</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.toggle_group_commit">
      <param name="self">The instance of GPS.Activities</param>
      <description>Change the activity's group commit status</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.files">
      <param name="self">The instance of GPS.Activities</param>
      <return>A list of files</return>
      <description>Returns the activity's files list</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.add_file">
      <param name="self">The instance of GPS.Activities</param>
      <param name="file">An instance of GPS.File</param>
      <description>Adds the file into the activity</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.remove_file">
      <param name="self">The instance of GPS.Activities</param>
      <param name="file">An instance of GPS.File</param>
      <description>Removes the file into the activity</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.vcs">
      <param name="self">The instance of GPS.Activities</param>
      <return>A string</return>
      <description>Returns the activity's VCS name</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.commit">
      <param name="self">The instance of GPS.Activities</param>
      <description>Commit the activity</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.diff">
      <param name="self">The instance of GPS.Activities</param>
      <description>Diff all activity's files</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.query_status">
      <param name="self">The instance of GPS.Activities</param>
      <description>Query status of all activity's files</description>
  </shell_doc>

  <shell_doc name="GPS.Activities.update">
      <param name="self">The instance of GPS.Activities</param>
      <description>Update all activity's files</description>
  </shell_doc>

  <!--#################################################################
    ####  Revision class
    ###################################################################-->

  <shell_doc name="GPS.Revision">
      <description>General interface to the revision browser</description>
  </shell_doc>

  <shell_doc name="GPS.Revision.add_log">
      <param name="file">A string</param>
      <param name="revision">A string</param>
      <param name="author">A string</param>
      <param name="date">A string</param>
      <param name="log">A string</param>
      <description>Add a new log entry into the revision browser</description>
  </shell_doc>

  <shell_doc name="GPS.Revision.add_link">
      <param name="file">A string</param>
      <param name="revision_1">A string</param>
      <param name="revision_2">A string</param>
      <description>Create a link between revision_1 and revision_2 for the given file</description>
  </shell_doc>

  <shell_doc name="GPS.Revision.add_revision">
      <param name="file">A string</param>
      <param name="revision">A string</param>
      <param name="symbolic_name">A string</param>
      <description>Register a new symbolic name (tag or branches) corresponding to the specified revision of file</description>
  </shell_doc>

  <shell_doc name="GPS.Revision.clear_view">
      <param name="file">A string</param>
      <description>Clear file's revision view</description>
  </shell_doc>

  <!--#################################################################
    ####  Context class
    ###################################################################-->

  <shell_doc name="GPS.Context">
      <description>Represents a context in GPS. Depending on the currently selected window, an instance of one of the derived classes will be used</description>
  </shell_doc>

  <shell_doc name="GPS.Context.contextual_menu">
      <description>returns a list containing the contextual menu labels of the currently focussed window. The output have the form "depth - label"</description>
  </shell_doc>

  <!--#################################################################
    ####   FileContext class
    ###################################################################-->

  <shell_doc name="GPS.FileContext">
      <description>Represents a context that contains file information</description>
      <see_also name="GPS.FileContext.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.FileContext.__init__">
      <param name="self">The instance we are building</param>
      <description>Dummy function, whose goal is to prevent user-creation of a GPS.FileContext instance. Such instances can only be created internally by GPS</description>
  </shell_doc>

  <shell_doc name="GPS.FileContext.file">
      <param name="self">The instance of GPS.FileContext</param>
      <return>An instance of GPS.File</return>
      <description>Return the name of the file in the context</description>
  </shell_doc>

  <shell_doc name="GPS.FileContext.project">
      <param name="self">The instance of GPS.FileContext</param>
      <return>An instance of GPS.Project</return>
      <description>Return the project in the context, or the root project if none was specified in the context. Return an error if no project can be determined from the context</description>
  </shell_doc>

  <shell_doc name="GPS.FileContext.directory">
      <param name="self">The instance of GPS.FileContext</param>
      <return>A string</return>
      <description>Return the current directory in the context</description>
  </shell_doc>

  <shell_doc name="GPS.FileContext.location">
      <param name="self">The instance of GPS.FileContext</param>
      <return>An instance of GPS.FileLocation</return>
      <description>Return the file location stored in the context</description>
  </shell_doc>

  <!--#################################################################
    ####   AreaContext class
    ###################################################################-->

  <shell_doc name="GPS.AreaContext">
      <description>Represents a context that contains file information and a range of lines currently selected</description>
      <see_also name="GPS.AreaContext.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.AreaContext.__init__">
      <param name="self">The instance we are building</param>
      <description>Dummy function, whose goal is to prevent user-creation of a GPS.AreaContext instance. Such instances can only be created internally by GPS</description>
  </shell_doc>

  <shell_doc name="GPS.AreaContext.start_line">
      <param name="self">The instance of GPS.AreaContext</param>
      <return>An integer</return>
      <description>Return the first selected line in the context</description>
  </shell_doc>

  <shell_doc name="GPS.AreaContext.end_line">
      <param name="self">The instance of GPS.AreaContext</param>
      <return>An integer</return>
      <description>Return the last selected line in the context</description>
  </shell_doc>

  <!--#################################################################
    ####   EntityContext class
    ###################################################################-->

  <shell_doc name="GPS.EntityContext">
      <description>Represents a context that contains entity information</description>
      <see_also name="GPS.EntityContext.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.EntityContext.__init__">
      <param name="self">The instance we are building</param>
      <description>Dummy function, whose goal is to prevent user-creation of a GPS.EntityContext instance. Such instances can only be created internally by GPS</description>
  </shell_doc>

  <shell_doc name="GPS.EntityContext.entity">
      <param name="self">The instance of GPS.EntityContext</param>
      <return>An instance of GPS.Entity</return>
      <description>Return the entity stored in the context</description>
  </shell_doc>

  <!--#################################################################
    ####   Help class
    ###################################################################-->

  <shell_doc name="GPS.Help">
     <description>This class gives access to the external documentation for shell commands. This external documentation is stored in the file shell_commands.xml, part of the GPS installation, and is what you are currently seeing.
You almost never need to use this class yourself, since it is used implicitly by Python when you call the help(object) command at the GPS prompt.

The help browser understands the standard http urls, with links to specific parts of the document. For instance:
     "http://remote.com/my_document"
 or  "#link"

As a special case, it also supports links starting with '%'. These are shell commands to execute within GPS, instead of a standard html file. For instance:
    &lt;a href="%shell:Editor.edit g-os_lib.ads"&gt;GNAT.OS_Lib%lt;/a%gt;

The first word after '%' is the language of the shell command, the rest of the text is the command to execute</description>
      <see_also name="GPS.Help.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Help.__init__">
     <param name="self">The instance of Help</param>
     <description>Initializes the instance of the Help class. This parses the XML file that contains the description of all the commands. With python, the memory occupied by this XML tree will be automatically freed. However, with the GPS shell you need to explicitly call GPS.Help.reset()</description>
     <see_also name="GPS.Help.reset()" />
  </shell_doc>

  <shell_doc name="GPS.Help.getdoc">
     <param name="self">The instance of Help</param>
     <param name="name">The fully qualified name of the command</param>
     <param name="html" default="false">A boolean</param>
     <return>A string, containing the help for the command</return>
     <description>Search, into the XML file shell_commands.xml, the documentation for this specific command or entity. If no documentation is found, an error is raised. If html is true, the documentation is formated in HTML</description>
     <example lang="python">
        print GPS.Help().getdoc("GPS.Help.getdoc")
     </example>
     <example lang="shell">
        Help
        Help.getdoc %1 "GPS.Help.getdoc"
        Help.reset %2
     </example>
  </shell_doc>

  <shell_doc name="GPS.Help.reset">
     <param name="self">The instance of Help</param>
     <description>Free the memory occupied by this instance. This frees the XML tree that is kept in memory. As a result, you can no longer call GPS.Help.getdoc() afterward.</description>
  </shell_doc>

  <shell_doc name="GPS.Help.file">
     <param name="self">The instance of Help</param>
     <return>A string</return>
     <description>Return the name of the file that contains the description of the shell commands. You shouldn't have to access it yourself, since you can do so through GPS.Help().getdoc() instead</description>
     <see_also name="GPS.Help.getdoc()"/>
  </shell_doc>

  <!--#################################################################
    ####   HTML class
    ###################################################################-->

  <shell_doc name="GPS.HTML">
     <description>This class gives access to the help system of GPS, as well as to the integrated browser</description>
  </shell_doc>

  <shell_doc name="GPS.HTML.add_doc_directory">
     <param name="directory">Directory that contains the documentation</param>
     <description>Add a new directory to the GPS_DOC_PATH environment variable. This directory is searched for documentation files. If this directory contains a gps_index.xml file, it is parsed to find the list of documentation files to
add to the Help menu. See the GPS documentation for more information on the
format of the gps_index.xml files</description>
  </shell_doc>

  <shell_doc name="GPS.HTML.browse">
     <param name="URL">Name of the file to browse</param>
     <param name="anchor" default="">Location in the file where to jump to</param>
     <param name="navigation" default="True">A boolean</param>
     <description>Open the GPS html viewer, and load the given URL. If anchor matches a &lt;a&gt; tag in this file, GPS will jump to it. If URL isn't an absolute file name, it is searched in the path set by the environment variable GPS_DOC_PATH.

If navigation is True, then the URL is saved in the navigation list, so that users can move back and forward from and to this location later on.

The URL can be a network file name, with the following general format:
   protocol://username@host:port/full/path
where protocol is one of the recognized protocols (http, ftp,.. see the GPS documentation), and the username and port are optional.</description>
     <see_also name="GPS.HTML.add_doc_directory()"/>
     <example lang="python">
         GPS.HTML.browse ("gps.html")
         will open the GPS documentation in the internal browser

         GPS.HTML.browse ("http://host.com/my/document")
         will download documentation from the web
     </example>
  </shell_doc>

  <!--#################################################################
    ####   Codefix class
    ###################################################################-->

  <shell_doc name="GPS.Codefix">
      <description>This class gives access to GPS's features for automatically fixing compilation errors</description>
      <see_also name="GPS.CodefixError" />
      <see_also name="GPS.Codefix.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Codefix.parse">
      <param name="category">A string</param>
      <param name="output">A string</param>
      <param name="regexp" default="">A string</param>
      <param name="file_index" default="-1">An integer</param>
      <param name="line_index" default="-1">An integer</param>
      <param name="column_index" default="-1">An integer</param>
      <param name="style_index" default="-1">An integer</param>
      <param name="warning_index" default="-1">An integer</param>
      <description>Parse the output of a tool, and suggests auto-fix possibilities whenever possible. This adds small icons in the location window, so that the user can click on it to fix compilation errors. You should call Locations.parse with the same output prior to calling this command.
The regular expression specifies how locations are recognized. By default, it matches file:line:column. The various indexes indicate the index of the opening parenthesis that contains the relevant information in the regular expression. Set it to 0 if that information is not available.
Access the various suggested fixes through the methods of the Codefix class</description>
     <see_also name="GPS.Editor.register_highlighting()" />
  </shell_doc>

  <shell_doc name="GPS.Codefix.__init__">
      <param name="self">The instance we are building</param>
      <param name="category">A string</param>
      <description>Return the instance of codefix associated with the given category</description>
  </shell_doc>

  <shell_doc name="GPS.Codefix.errors">
      <param name="self">The instance of GPS.Codefix</param>
      <return>A list of instances of GPS.CodefixError</return>
      <description>List the fixable errors in that session</description>
  </shell_doc>

    <shell_doc name="GPS.Codefix.error_at">
      <param name="self">The instance of GPS.Codefix</param>
      <param name="file">The file where the error is</param>
      <param name="line">The line where the error is</param>
      <param name="column">The column where the error is</param>
      <param name="message" default="">The message of the error</param>
      <return>An instance of GPS.CodefixError</return>
      <description>Return a specific error at a given location. If message is null, then the first matching error will be taken. None is returned if no such fixable error exists.</description>
  </shell_doc>

  <shell_doc name="GPS.Codefix.sessions">
      <return>A list of strings</return>
      <description>List all the existing Codefix sessions. The returned values can all be used to create a new instance of Codefix through its constructor.</description>
      <example lang="python">
           After a compilation failure, calling
              GPS.Codefix.sessions()
           will return a list similar to
              ['Builder results']
      </example>
  </shell_doc>

  <!--#################################################################
    ####   CodeAnalysis class
    ###################################################################-->

  <shell_doc name="GPS.CodeAnalysis">
      <description>This class is a toolset that allows to handle CodeAnalysis instances.</description>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.__del__">
      <description>Deletes a CodeAnalysis shell instance.</description>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.__init__">
      <description>Raises an exception to prevent users from using it.</description>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.get">
      <param name="name">The name of the code analysis data structure to get or create</param>
      <return>An instance of GPS.CodeAnalysis associated to a code analysis data structure in GPS.</return>
      <description>Creates an empty code analysis data structure. Data can be put in this structure by using one of the primitive operations.</description>
      <example lang="python">
          a = GPS.CodeAnalysis.get ("Coverage")
          a.add_all_gcov_project_info ()
          a.show_coverage_information ()
      </example>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.clear">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <description>Removes all code analysis information from memory.</description>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.add_gcov_file_info">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <param name="src">A GPS.File instance</param>
      <param name="cov">A GPS.File instance</param>
      <description>Adds coverage information provided by a .gcov file parsing. The data is read from the cov parameter, that should have been created from the specified src file.</description>
      <see_also name="GPS.CodeAnalysis.add_all_gcov_project_info" />
      <see_also name="GPS.CodeAnalysis.add_gcov_project_info" />
      <example lang="python">
          a = GPS.CodeAnalysis.get ("Coverage Report")
          a.add_gcov_file_info (src=GPS.File ("source_file.adb"), cov=GPS.File ("source_file.adb.gcov"))
      </example>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.add_gcov_project_info">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <param name="prj">A GPS.File instance</param>
      <description>Adds coverage information of every source files referenced in the given 'prj' gnat project file (.gpr).</description>
      <see_also name="GPS.CodeAnalysis.add_all_gcov_project_info" />
      <see_also name="GPS.CodeAnalysis.add_gcov_file_info" />
  </shell_doc>

    <shell_doc name="GPS.CodeAnalysis.add_all_gcov_project_info">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <description>Adds coverage information of every source files referenced in the current project loaded in GPS, and every imported projects.</description>
      <see_also name="GPS.CodeAnalysis.add_gcov_project_info" />
      <see_also name="GPS.CodeAnalysis.add_gcov_file_info" />
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.show_analysis_report">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <description>Displays the data stored in the CodeAnalysis instance into a new MDI window. This window contains a tree view that can be interactively manipulated to analyze the results of the code analysis (Coverage, ...).</description>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.show_coverage_information">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <description>Lists in the Locations view the lines that are not covered in the files loaded in the CodeAnalysis instance. The lines are also highlighted in the corresponding source file editors, and an annotation column is added to the source editors.</description>
      <see_also name="GPS.CodeAnalysis.hide_coverage_information" />
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.hide_coverage_information">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <description>Removes from the Locations view any listed coverage locations, and remove from the source editors their annotation column if any.</description>
      <see_also name="GPS.CodeAnalysis.show_coverage_information" />
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.dump_to_file">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <param name="xml">A GPS.File instance</param>
      <description>Create an xml-formated file that contains a representation of the given code analysis.</description>
      <see_also name="GPS.CodeAnalysis.load_from_file" />
      <example lang="python">
          a = GPS.CodeAnalysis.get ("Coverage")
          a.add_all_gcov_project_info ()
          a.dump_to_file (xml=GPS.File ("new_file.xml"))
      </example>
  </shell_doc>

  <shell_doc name="GPS.CodeAnalysis.load_from_file">
      <param name="self">An instance of GPS.CodeAnalysis</param>
      <param name="xml">A GPS.File instance</param>
      <description>Replace the current coverage information in memory with the given xml-formated file one.</description>
      <see_also name="GPS.CodeAnalysis.dump_to_file" />
      <example lang="python">
          a = GPS.CodeAnalysis.get ("Coverage")
          a.add_all_gcov_project_info ()
          a.dump_to_file (xml=GPS.File ("new_file.xml"))
          a.clear ()
          a.load_from_file (xml=GPS.File ("new_file.xml"))
      </example>
  </shell_doc>

  <!--#################################################################
    ####   CodefixError class
    ###################################################################-->

  <shell_doc name="GPS.CodefixError">
      <description>This class represents a fixable error in the compilation output</description>
      <see_also name="GPS.Codefix" />
      <see_also name="GPS.CodefixError.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.CodefixError.__init__">
      <param name="self">The instance we are building</param>
      <param name="codefix">An instance of GPS.Codefix</param>
      <param name="file">An instance of GPS.FileLocation</param>
      <param name="message" default="">A string</param>
      <description>Describe a new fixable error. If the message is not specified, the first error at that location is returned</description>
  </shell_doc>

  <shell_doc name="GPS.CodefixError.possible_fixes">
      <param name="self">The instance of GPS.CodefixError</param>
      <return>A list of strings</return>
      <description>List the possible fixes for the specific error</description>
      <example lang="python">
          for err in GPS.Codefix ("Builder results").errors():
              print err.possible_fixes()
      </example>
  </shell_doc>

  <shell_doc name="GPS.CodefixError.fix">
      <param name="self">The instance of GPS.CodefixError</param>
      <param name="choice" default="0">The index of the fix to apply, see output of GPS.CodefixError.possible_fixes()</param>
      <description>Fix the error, using one of the possible fixes. The index given in parameter is the index in the list returned by "possible_fixes. By default, the first choice is taken. Choices start at index 0.</description>
      <example lang="python">
          for err in GPS.Codefix ("Builder results").errors():
              print err.fix()
          Will automatically fix all fixable errors in the last compilation output
      </example>
  </shell_doc>

  <shell_doc name="GPS.CodefixError.message">
      <param name="self">The instance of GPS.CodefixError</param>
      <return>A string</return>
      <description>Return the error message, as issues by the tool</description>
  </shell_doc>

  <shell_doc name="GPS.CodefixError.location">
      <param name="self">The instance of GPS.CodefixError</param>
      <return>An instance of GPS.FileLocation</return>
      <description>Return the location of the error</description>
  </shell_doc>

  <!--#################################################################
    ####   Console class
    ###################################################################-->

  <shell_doc name="GPS.Console">
      <description>This class is used to create and interact with the interactive consoles in GPS. It can be used to redirect the output of scripts to various consoles in GPS, or to get input from the user has needed.</description>
      <example lang="python">
         The following example shows how to redirect the output of a script to a new console in GPS:
	    console = GPS.Console ("My_Script")
	    console.write ("Hello world")  ## Explicit redirection

	 The usual python's standard output can also be redirected to this console:
	    sys.stdout = GPS.Console ("My_Script")
	    print "Hello world, too"  ## Implicit redirection
	    sys.stdout = GPS.Console ("Python")  ## Back to python's console
	    sys.stdout = GPS.Console () ## Or back to GPS's console
      </example>
      <example lang="python">
         The following example shows an integration between the GPS.Console and GPS.Process classes, so that a window containing a shell can be added to GPS.
Note that this class is in fact available directly through "from gps_utils.console_process import Console_Process" if you need it in your own scripts.

            import GPS
            class Console_Process (GPS.Console, GPS.Process):
              def on_output (self, matched, unmatched):
                self.write (unmatched + matched)
              def on_exit (self, status, unmatched_output):
                try: self.destroy ()
                except: pass  # Might already have been destroyed
              def on_input (self, input):
                self.send (input)
              def on_destroy (self):
                self.kill ()  # Will call on_exit
              def __init__ (self, process, args=""):
                GPS.Console.__init__ \
		   (self, process, \
                    on_input=Console_Process.on_input, \
                    on_destroy=Console_Process.on_destroy, \
                    force=True)
                GPS.Process.__init__ \
		   (self, process + ' ' + args, ".+", \
                    on_exit=Console_Process.on_exit, \
                    on_match=Console_Process.on_output)

              bash = Console_Process ("/bin/sh", "-i")
      </example>
      <see_also name="GPS.Process" />
      <see_also name="GPS.Console.__init__" />
  </shell_doc>

  <shell_doc name="GPS.Console.__init__">
      <param name="self">The instance of GPS.Console</param>
      <param name="name">A string</param>
      <param name="force" default="False">A boolean</param>
      <param name="on_input" default="">A subprogram, see the description below</param>
      <param name="on_destroy" default="">A subprogram</param>
      <param name="accept_input" default="True">A boolean</param>
      <param name="on_resize" default="">A subprogram</param>
      <param name="on_interrupt" default="">A subprogram</param>
      <param name="on_completion" default="">A subprogram</param>
      <param name="on_key" default="">A subprogram</param>
      <param name="manage_prompt" default="True">A boolean</param>
      <param name="ansi" default="False">A boolean</param>
      <description>Create a new instance of GPS.Console. GPS will try to reuse any existing console with the same name. If none exists yet, or the parameter force is set to True, then GPS will create a new console.

You cannot create the Python and Shell consoles through this call. If you do, an exception is raised. Instead, use GPS.execute_action ("/Tools/Consoles/Python"), and then get a handle on the console through GPS.Console. This is because these two consoles are tightly associated with each of the scripting languages.

If GPS reuses an existing console, on_input overrides the callback that was
already set on the console, whereas on_destroy will be called in addition to
the one that was already set on the console.

If this is not the desired behavior, you can also call destroy() on the console, and call the constructor again.

The subprogram on_input is called whenever the user has entered a new command in the console and pressed &lt;enter&gt; to execute it. It is called with the following parameters:
   - $1: The instance of the GPS.Console
   - $2: The command to execute
See the subprogram GPS.Console.set_prompt_regexp for proper handling of input in the console.

The subprogram on_destroy is called whenever the user closes the console. It is called with a single parameter:
   - $1: The instance of the GPS.Console

The subprogram on_completion is called whenever the user presses tab in the console. It is called with a single parameter:
   - $1: The instance of the GPS.Console
The default implementation is to insert a tab character, but you could choose to add some user input through GPS.Console.add_input for instance.

The subprogram on_resize is called whenever the console is resized by the user. It is passed three parameters: $1 is the instance of GPS.Console, $2 is the number of visible rows in the console, and $3 is the number of visible columns. This is mostly useful when a process is running in the console, in which case you can use GPS.Process.set_size to let the process know about the size. Note that the size passed to this callback is conservative: since all characters might not have the same size, GPS tries to compute the maximal number of visible characters and pass this to the callback, but the exact number of characters might depend on the font.

The subprogram on_interrupt is called when the user presses control-c in the console. It receives a single parameter, which is the instance of GPS.Console. By default a control-c is handled by GPS itself and will kill the last process that was started.

As described above, GPS provides a high-level handling of consoles, where it manages histories, completion, command line editing and execution on its own through the callbacks described above. This is in general a good thing and provides advanced functionalities to some programs that lack them. However, there are cases where this gets in the way. For instance, if you want to run a Unix shell or a program that manipulates the console by moving the cursor around on its own, the high-level handling of GPS gets in the way. In such a case, the following parameters can be used: on_key, manage_prompt and ansi.

ansi should be set to true if GPS should emulate an ANSI terminal. These are terminals that understand certain escape sequences that applications sent to move the cursor to specific positions on screen or to change the color and attributes of text.

manage_prompt should be set to False to disable GPS's handling of prompt. In general, this is incompatible with using the on_input callback, since GPS no longer distinguishes what was typed by the user and what was written by the external application. This also means that the application is free to write anywhere on the screen. This should in general be set to True if you expect your application to send ANSI sequences.

on_key is a subprogram that is called every time the user presses a key in the console. This is much lower-level than the other callbacks above, but if you are driving external applications you might have a need to send the keys as they happen, and not wait for a newline. on_key receives four parameters:
    - $1: the instance of GPS.Console
    - $2: "keycode": this is the internal keycode for the key that the user
          pressed. All keys can be represented this way, but this will
          occasionaly be left to 0 when the user input was simulated and no
          real key was pressed.
    - $3: "key": this is the unicode character that the user entered. This will
          be 0 when the character is not printable (for instance return, tab,
          key up,...). In python, you can manipulate it with code like
                  unichr (key).encode ("utf8")
          to get a string representation that can be sent to an external
          process
    - $4: "modifier": these are the state of the control, shift, mod1 and lock
          keys. This is a bitmask, where shift is 1, lock is 2, control is 4
          and mod1 is 8.
</description>
  </shell_doc>

  <shell_doc name="GPS.Console.clear_input">
      <param name="self">The instance of GPS.Console</param>
      <description>Removes any user input that the user has started typing (ie since the last output inserted through GPS.Console.write</description>
  </shell_doc>

  <shell_doc name="GPS.Console.add_input">
      <param name="self">The instance of GPS.Console</param>
      <param name="text">A string</param>
      <description>Add some extra text to the console as if the user had typed it. As opposed to text inserted with GPS.Console.write, this text remains editable by the user</description>
  </shell_doc>

  <shell_doc name="GPS.Console.write">
      <param name="self">The instance of GPS.Console</param>
      <param name="text">A utf8 string</param>
      <param name="mode" default='"text"'>A string, one of "text", "log", "error"</param>
      <description>Output some text on the console. This text is read-only. If the user had started typing some text, that text is temporarily remove, the next text is inserted (read-only), and the user text is put back afterward.

The optional parameter mode specifies the kind of the output text: "text" for ordinary messages (this is default), "log" for log messages, and "error" for error messages.</description>
      <example lang="python">
          Console().write (u"\N{LATIN CAPITAL LETTER E WITH ACUTE}".encode("utf-8"))
      </example>
      <see_also name="GPS.Console.write_with_links" />
  </shell_doc>

  <shell_doc name="GPS.Console.create_link">
      <param name="self">The instance of GPS.Console</param>
      <param name="regexp">A string</param>
      <param name="on_click">A subprogram</param>
      <description>Register a regular expression that should be highlight in this console to provide hyper links. These links are searched for when calling GPS.Console.write_with_links. The part of the text that matches any of the link registered in the console through GPS.Console.create_link gets highlighted in blue and underlined, just like an hyper link in a web browser. If the user clicks on that text, on_click gets called with one parameter, the text that was clicked on. This can for instance be used to jump to an editor, open a web browser,...

If the regular expression does not contain any parenthesis, the text that matches the whole regexp is highlighted as a link. Otherwise, only the part of the text that matches the first parenthesis group is highlighted (so that you can test for the presence of text before or after the actual hyper link). </description>
      <see_also name="GPS.Console.write_with_links" />
  </shell_doc>

  <shell_doc name="GPS.Console.write_with_links">
      <param name="self">The instance of GPS.Console</param>
      <param name="text">A utf8 string</param>
      <description>Output some text on the console, highlight the parts of it that matches the regular expression registered by GPS.Console.create_link.</description>
      <example lang="python">
   import re

   console = GPS.Console ("myconsole")
   console.create_link ("(([\w-]+):(\d+))", open_editor)
   console.write_with_link ("a file.adb:12 location in a file")

   def open_editor (text):
      matched = re.match ("([\w+-]+):(\d+)", text)
      buffer = GPS.EditorBuffer.get (GPS.File (matched.group (1)))
      buffer.current_view().goto \
         (GPS.EditorLocation (buffer, int (matched.group (2)), 1))
      </example>
  </shell_doc>

  <shell_doc name="GPS.Console.clear">
      <param name="self">The instance of GPS.Console</param>
      <description>Clear the current contents of the console</description>
  </shell_doc>

  <shell_doc name="GPS.Console.flush">
      <param name="self">The instance of GPS.Console</param>
      <description>Do nothing, needed for compatibility with Python's file class</description>
  </shell_doc>

  <shell_doc name="GPS.Console.isatty">
      <param name="self">The instance of GPS.Console</param>
      <return>A boolean</return>
      <description>Return True if the console behaves like a terminal. Mostly needed for compatibility with Python's file class</description>
  </shell_doc>

  <shell_doc name="GPS.Console.read">
      <param name="self">The instance of GPS.Console</param>
      <return>A String</return>
      <description>Read the available input in the console. Currently, this behaves exactly like readline()</description>
  </shell_doc>

  <shell_doc name="GPS.Console.readline">
      <param name="self">The instance of GPS.Console</param>
      <return>A String</return>
      <description>Ask the user to enter a new line in the console, and returns that line. GPS is blocked until enter has been pressed in the console</description>
  </shell_doc>

  <shell_doc name="GPS.Console.accept_input">
      <param name="self">The instance of GPS.Console</param>
      <return>A boolean</return>
      <description>Return True if the console accepts input, False otherwise</description>
  </shell_doc>

  <shell_doc name="GPS.Console.enable_input">
      <param name="self">The instance of GPS.Console</param>
      <param name="enable">A boolean</param>
      <description>Make the console accept / reject input according to the value of "enable"</description>
  </shell_doc>

  <shell_doc name="GPS.Console.get_text">
      <param name="self">The instance of GPS.Console</param>
      <return>A string</return>
      <description>Return the content of the console</description>
  </shell_doc>

  <!--#################################################################
    ####   Toolbar class
    ###################################################################-->

  <shell_doc name="GPS.Toolbar">
     <description>Interface to commands related to the toolbar. This allows you to add new combo boxes to the GPS toolbars. Note that this can also be done through XML files, see the GPS documentation</description>
     <example lang="python">
         import GPS
         def on_changed (entry, choice):
             print "changed " + choice + ' ' + entry.custom
         def on_selected (entry, choice):
             print "on_selected " + choice + ' ' + entry.custom

         ent=GPS.Combo("foo", label="Foo", on_changed=on_changed)
         GPS.Toolbar().append (ent, tooltip => "What it does")
         ent.custom = "Foo"  ##  Create any field you want
         ent.add (choice="Choice1", on_selected=on_selected)
         ent.add (choice="Choice2", on_selected=on_selected)
         ent.add (choice="Choice3", on_selected=on_selected)
     </example>
     <example lang="shell">
         It is easier to use this interface through XML customization files, see the GPS documentation. However, this can also be done through standard shell commands.
         Combo "foo" "Foo" "on_changed_action"
         Toolbar
         Toolbar.append %1 %2 "What it does"

         Toolbar
         Toolbar.get %1 "foo"
         Combo.add %1 "Choice1" "on_selected"action"
     </example>
      <see_also name="GPS.Toolbar.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Toolbar.__init__">
     <param name="self">The instance of GPS.Toolbar</param>
     <description>Initializes a new instance of the toolbar, associated with the default toolbar of GPS. This is called implicitly from python</description>
  </shell_doc>

  <shell_doc name="GPS.Toolbar.get">
     <param name="self">The instance of GPS.Toolbar</param>
     <param name="id">A string, the name of the entry to get</param>
     <return>An instance of GPS.Combo</return>
     <description>Return the toolbar entry matching the given id. An error is raised if no such entry exists. The same instance of GPS.Combo is always returned for each specific id, therefore you can store your own fields in this instance and access it later.</description>
     <example lang="python">
         ent=GPS.Combo ("foo")
         GPS.Toolbar().append (ent)
         ent.my_custom_field="Whatever"

         print GPS.Toolbar().get ("foo").my_custom_field   ## "Whatever"
     </example>
  </shell_doc>

  <shell_doc name="GPS.Toolbar.get_by_pos">
     <param name="self">The instance of GPS.Toolbar</param>
     <param name="position">An integer, starting at 0</param>
     <return>An instance of a child of GPS.GUI</return>
     <description>Return the position-th widget in the toolbar. If the widget was created from a scripting language, its instance is returned. Otherwise, a generic instance of GPS.GUI is returned. This can be used to remove some items from the toolbar for instance</description>
     <example lang="python">
         GPS.Toolbar().get_by_pos (0).set_sensitive (False)
         can be used to gray out the first item in the toolbar
     </example>
  </shell_doc>

  <shell_doc name="GPS.Toolbar.append">
     <param name="self">The instance of GPS.Toolbar</param>
     <param name="widget">An instance of GPS.GUI</param>
     <param name="tooltip" default="">A string</param>
     <description>Add a new widget in the toolbar. This can be an instance of GPS.Combo, or a GPS.Button, or a GPS.ToolButton.</description>
  </shell_doc>

  <shell_doc name="GPS.Toolbar.insert">
     <param name="self">The instance of GPS.Toolbar</param>
     <param name="widget">An instance of GPS.GUI</param>
     <param name="pos" default="-1">The position at which to insert the widget</param>
     <param name="tooltip" default="">A string</param>
     <description>Add a new widget in the toolbar. This can be an instance of GPS.Combo, or a GPS.Button, or a GPS.ToolButton.</description>
  </shell_doc>

  <!--#################################################################
    ####   Button class
    ###################################################################-->

  <shell_doc name="GPS.Button">
     <description>This class represents a button that can be pressed to trigger various actions</description>
      <see_also name="GPS.Button.__init__()"/>
  </shell_doc>

  <shell_doc name="GPS.Button.__init__">
     <param name="self">An instance of GPS.Button</param>
     <param name="id">A string, a unique identifier for the button</param>
     <param name="label">A string, the text that appears on the button</param>
     <param name="on_click">A subprogram, see the GPS documentation</param>
     <description>Initializes a new button. When the button is pressed by the user, on_click is called with the following single parameter:
   - $1 = The instance of GPS.Button</description>
     <example lang="python">
         def on_click (button):
             print "Button pressed"
         button = GPS.Button ("my_id", label="Press me", on_click=on_click)
         GPS.Toolbar().append (button)
     </example>
  </shell_doc>

  <shell_doc name="GPS.Button.set_text">
     <param name="self">An instance of GPS.Button</param>
     <param name="label">A string</param>
     <description>Change the text that appears on the button</description>
  </shell_doc>

  <!--#################################################################
    ####   ToolButton class
    ###################################################################-->

  <shell_doc name="GPS.ToolButton">
     <description>This class represents a button that can be inserted in the toolbar</description>
      <see_also name="GPS.ToolButton.__init__()"/>
  </shell_doc>

  <shell_doc name="GPS.ToolButton.__init__">
     <param name="self">An instance of GPS.Button</param>
     <param name="stock_id">A string identifying the icon</param>
     <param name="label">A string, the text that appears on the button</param>
     <param name="on_click">A subprogram, see the GPS documentation</param>
     <description>Initializes a new button. When the button is pressed by the user, on_click is called with the following single parameter:
   - $1 = The instance of GPS.Button</description>
     <example lang="python">
         b = GPS.ToolButton ("gtk-new", "New File", lambda x : GPS.execute_action ("/File/New"))
         GPS.Toolbar().insert (b, 0)
     </example>
  </shell_doc>

  <!--#################################################################
    ####   Combo class
    ###################################################################-->

  <shell_doc name="GPS.Combo">
      <description>This class represents a combo box, ie a text entry widget with a number of predefined possible values. The user can interactively select one of multiple values through this widget</description>
      <see_also name="GPS.Toolbar"/>
      <see_also name="GPS.Combo.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Combo.__init__">
     <param name="self">The instance of GPS.Combo</param>
     <param name="id">A string, the name of the combo to create</param>
     <param name="label" default="">A string, the label to add next to the entry</param>
     <param name="on_changed" default="None">A subprogram, see the GPS documentaion on Subprogram parameters</param>
     <description>Create a new combo. The combo will graphically be preceded by some text if label was specified. On_Changed will be called every time the user selects a new value for the combo box. Its parameters are the following:
   - $1 = The instance of GPS.Combo (self)
   - $2 = The newly selected text (a string) </description>
     <see_also name="GPS.Toolbar.append()" />
     <see_also name="GPS.Toolbar.ge()" />
  </shell_doc>

  <shell_doc name="GPS.Combo.add">
     <param name="self">The instance of GPS.Combo</param>
     <param name="choice">A string</param>
     <param name="on_selected" default="">A subprogram, see the GPS documentation on Subprogram parameters</param>
     <description>Add a choice to specified entry, action will be executed whenever this choice is selected. It is called with the following parameters:
   - $1 = The instance of GPS.Combo (self)
   - $2 = The newly selected text (a string)
</description>
  </shell_doc>

  <shell_doc name="GPS.Combo.remove">
     <param name="self">The instance of GPS.Combo</param>
     <param name="choice">A string</param>
     <description>Remove a choice from specified entry</description>
     <see_also name="GPS.Combo.clear()"/>
  </shell_doc>

  <shell_doc name="GPS.Combo.clear">
     <param name="self">The instance of GPS.Combo</param>
     <description>Remove all choices from specified entry</description>
  </shell_doc>

  <shell_doc name="GPS.Combo.get_text">
     <param name="self">The instance of GPS.Combo</param>
     <return>A string</return>
     <description>Return the current selection in specified entry</description>
  </shell_doc>

  <shell_doc name="GPS.Combo.set_text">
     <param name="self">The instance of GPS.Combo</param>
     <param name="choice">A string</param>
     <description>Set the current selection in specified entry</description>
  </shell_doc>

  <!--#################################################################
    ####   Timeout class
    ###################################################################-->

  <shell_doc name="GPS.Timeout">
      <description>This class gives access to actions that must be executed regularly at specific intervals</description>
      <example lang="python">
         ## Execute callback three times and remove it
         import GPS;
         def callback (timeout):
            timeout.occur = timeout.occur + 1;
            print "A timeout occur=" + `timeout.occur`
            if timeout.occur == 3:
               timeout.remove ()
         t = GPS.Timeout (500, callback)
         t.occur = 0
      </example>
      <see_also name="GPS.Timeout.__init__"/>
  </shell_doc>

  <shell_doc name="GPS.Timeout.__init__">
      <param name="self">The timeout to initialize</param>
      <param name="timeout">The timeout in milliseconds at which to execute the action</param>
      <param name="action">A subprogram parameter to execute periodically</param>
      <description>A timeout object executes a specific action repeatedly, at a specified interval, as long as it is registered.
The action takes a single argument, which is the instance of GPS.Timeout that called it.</description>
  </shell_doc>

  <shell_doc name="GPS.Timeout.remove">
      <param name="self">The Timeout to remove</param>
      <description>Unregister a timeout</description>
  </shell_doc>

  <!--#################################################################
    ####   Docgen classes
    ###################################################################-->

  <shell_doc name="GPS.Docgen">
     <description>Interface for handling customized documentation generation. This class is used in conjunction with GPS.DocgenTagHandler. You cannot create directly this class, but use the ones furnished in GPS.DocgenTagHandler callbacks.</description>
     <see_also name="GPS.DocgenTagHandler" />
  </shell_doc>
  <shell_doc name="GPS.Docgen.register_css">
     <param name="filename">A file name</param>
     <description>Registers a new CSS file to use when generating the documentation. This allows either to override a default style, or add new ones for custom tags handling</description>
  </shell_doc>
  <shell_doc name="GPS.Docgen.register_main_index">
     <param name="filename">A file name</param>
     <description>Registers the file to be used as main page (e.g. index.html). By default, the first page generated in the Table of Contents is used.</description>
  </shell_doc>
  <shell_doc name="GPS.Docgen.register_tag_handler">
     <param name="handler">The handler to register</param>
     <description>Registers a new tag handler. This handler will be used each time a new documentation is generated and the corresponding tag is found</description>
     <example lang="python"># register a default handler for tag &lt;description&gt;
# that is, -- &lt;description&gt;sth&lt;/description&gt;
# will be translated as &lt;div class="description"&gt;sth&lt;/div&gt;
GPS.Docgen.register_tag_handler (GPS.DocgenTagHandler ("description"))</example>
  </shell_doc>
  <shell_doc name="GPS.Docgen.generate_index_file">
     <param name="self">The Docgen instance as passed in the GPS.DocgenTagHandler callbacks</param>
     <param name="name">The name of the new index file.</param>
     <param name="filename">The created file name.</param>
     <param name="content">The content of the created file.</param>
     <description>Create a new Index file. The file 'filename' will be titled 'name', and will contain the general decoration along with 'content'.
     All other generated documentation file will have a link to it for convenience.</description>
  </shell_doc>
  <shell_doc name="GPS.Docgen.get_current_file">
     <param name="self">The Docgen instance as passed in the GPS.DocgenTagHandler callbacks</param>
     <return>A GPS.File instance</return>
     <description>Retrieves the current analysed source file. You should call this method only from a GPS.DocgenTagHandler.on_match() callback.</description>
  </shell_doc>
  <shell_doc name="GPS.Docgen.get_doc_dir">
     <param name="self">The Docgen instance as passed in the GPS.DocgenTagHandler callbacks</param>
     <return>A GPS.File instance</return>
     <description>Retrieves the directory that will contain the documentation. You should call this method only from a GPS.DocgenTagHandler.on_match() callback.</description>
  </shell_doc>

  <shell_doc name="GPS.DocgenTagHandler">
     <description>This class is used to handle user-defined documentation tags. This allows custom handling of comments such as : -- &lt;summary&gt;This fn does something&lt;/summary&gt;</description>
     <example lang="python">import GPS

class ScreenshotTagHandler (GPS.DocgenTagHandler):
   """Handling for &lt;screenshot&gt;screen.jpg&lt;/screenshot&gt;"""
   def __init__ (self):
      GPS.DocgenTagHandler.__init__ (
        self, "screenshot",
        on_match = self.on_match, on_start=self.on_start, on_exit=self.on_exit)

   def on_start (self, docgen):
      self.list = {}

   def on_match (self, docgen, attrs, value, entity_name, entity_href):
      # In this examples, images are in the directory _project_root_/doc/imgs/
      dir = docgen.get_current_file().project().file().directory()+"doc/imgs/"
      img = """&lt;img src="%s%s" alt="%s"/&gt;""" % (dir, value, value)
      self.list[entity_name] = [entity_href, img]
      return """&lt;h3&gt;Screenshot&lt;/h3&gt;&lt;p&gt;%s&lt;/p&gt;""" % (img)

   def on_exit (self, docgen):
      content=""

      for pict in sorted(self.list.keys()):
         content += """&lt;div class='subprograms'&gt;"""
         content += """  &lt;div class='class'&gt;"""
         content += """    &lt;h3&gt;%s&lt;/h3&gt;""" % (pict)
         content += """    &lt;div class='comment'&gt;"""
         content += """      &lt;a href="%s"&gt;%s&lt;/a&gt;""" % (self.list[pict][0], self.list[pict][1])
         content += """    &lt;/div&gt;"""
         content += """  &lt;/div&gt;"""
         content += """&lt;/div&gt;"""

      if content != "":
         docgen.generate_index_file ("Screenshots", "screenshots.html", content);

def on_gps_start (hook):
   GPS.Docgen.register_css (GPS.get_system_dir() + "share/mycustomfiles/custom.css")
   GPS.Docgen.register_tag_handler (ScreenshotTagHandler ())

GPS.Hook ("gps_started").add (on_gps_start)
     </example>
     <see_also name="GPS.Docgen" />
  </shell_doc>

  <shell_doc name="GPS.DocgenTagHandler.__init__">
     <param name="self">The instance of GPS.DocgenTagHandler</param>
     <param name="tag">The tag that is handled</param>
     <param name="on_start" default="None">A subprogram</param>
     <param name="on_match" default="None">A subprogram</param>
     <param name="on_exit" default="None">A subprogram</param>
     <description>Create a new GPS.DocgenTagHandler instance handling the tag &quot;tag&quot;. You need to register it afterwards using GPS.Docgen.register_tag_handler.

&quot;on_match&quot; is a callback that is called each time a tag corresponding to the GPS.DocgenTagHandler is analysed. It takes the following parameters:
  $1 = the instance of GPS.Docgen.
  $2 = the eventual attributes of the tag.
  $3 = the value of the tag.
  $4 = the entity name linked to the analysed tag.
  $5 = the href to the entity documentation location.

&quot;on_start&quot; is a callback that is called each time a documentation generation starts. It takes the following parameters:
  $1 = the instance of GPS.Docgen.

&quot;on_exit&quot; is a callback that is called each time a documentation generation finishes. It takes the following parameters:
  $1 = the instance of GPS.Docgen.

Using the default values of the callbacks (e.g. None), the GPS.DocgenTagHandler handler will translate comments of the form "-- &lt;tag&gt;value&lt;/tag&gt;" by "&lt;div class="tag"&gt;value&lt;/div&gt;".</description>
  </shell_doc>

  <!--#################################################################
    ####   Process class
    ###################################################################-->

  <shell_doc name="GPS.Process">
      <description>Interface to expect-related commands. This class can be used to spawn new processes and communicate with them later on. It is similar to what GPS uses to communicate with gdb. This class is a subclass of GPS.Command.</description>
      <example lang="python">
The following example launches a gdb process, let it print its welcome message,
and kills it as soon as a prompt is seen in the output.
In addition, it displays debugging messages in a new GPS window.
As you might note, some instance-specific data is stored in the instance of the
process, and can be retrieve in each callback.

import GPS, sys

def my_print(msg):
   sys.stdout.set_console ("My gdb")
   print (msg)
   sys.stdout.set_console()

def on_match (self, matched, unmatched):
   my_print "on_match (" + self.id + ")=" + matched
   self.kill()

def on_exit (self, status, remaining_output):
   my_print "on_exit (" + self.id + ")"

def run():
   proc = GPS.Process("gdb", "^\\(gdb\\)", on_match=on_match, on_exit=on_exit)
   proc.id = "first session"

run()
      </example>
      <example lang="python">
A similar example can be implemented by using a new class. This is slightly
cleaner, since it doesn't pollute the global namespace.

class My_Gdb (GPS.Process):
   def matched (self, matched, unmatched):
      my_print ("matched " + self.id)
      self.kill()

   def exited (self, status, output):
      my_print ("exited " + self.id)

   def __init__ (self):
       self.id = "from class"
       GPS.Process.__init__ (self, "gdb", "^\\(gdb\\)", on_match=My_Gdb.matched, on_exit=My_Gdb.exited)

My_Gdb()
      </example>
      <see_also name="GPS.Process.__init__()" />
      <see_also name="GPS.Command" />
  </shell_doc>

  <shell_doc name="GPS.Process.__init__">
      <param name="self">The instance of GPS.Process</param>
      <param name="command">A string</param>
      <param name="regexp" default="">A string</param>
      <param name="on_match" default="None">A subprogram, see the section "Subprogram parameters" in the GPS documentation</param>
      <param name="on_exit" default="None">A subprogram</param>
      <param name="task_manager" default="True">A boolean</param>
      <param name="progress_regexp" default="">A string</param>
      <param name="progress_current" default="1">An integer</param>
      <param name="progress_total" default="1">An integer</param>
      <param name="before_kill" default="None">A subprogram</param>
      <param name="remote_server" default="">A string. Possible values are "GPS_Server", the empty string (equivalent to "GPS_Server"), "Build_Server", "Debug_Server", "Execution_Server" and "Tools_Server".</param>
      <param name="show_command" default="False">A boolean</param>
      <param name="single_line_regexp" default="False">A boolean</param>
      <param name="case_sensitive_regexp" default="True">A boolean</param>
      <param name="strip_cr" default="True">A boolean</param>
      <description>Spawn specified command. Command can include triple-quoted strings, similar to python, which will always be preserved as one argument.

 If regexp is not-empty and on_match_action is specified, launch on_match_action when regexp is found in the process output. If on_exit_action is specified, execute it when the process terminates. Return the ID of the spawned process.

regexp is always compiled with the multi_line option, so that "^" and "$" also match at the beginning and end of each line, not just the whole output. You can optionally compile it with the single_line option whereby "." also matches the newline character. Likewise you can set the regexp to be case insensitive by setting case_sensitive_regexp to False.

on_match is a subprogram called with the parameters:
  $1 = the instance of GPS.Process
  $2 = the string which matched the regexp
  $3 = the string since the last match

before_kill is a subprogram called just before the process is about to be killed. It is called when the user is interrupting the process through the task manager, or when GPS exits. It is not called when the process terminates normally. When it is called, the process is still valid and can be send commands. Its parameters are:
  $1 = the instance of GPS.Process
  $2 = the entire output of the process

on_exit is a subprogram called when the process has exited. You can no longer send input to it at this stage. Its parameters are:
  $1 = the instance of GPS.Process
  $2 = the exit status
  $3 = the output of the process since the last call to on_match

If the parameter task_manager is set to True, the process will be visible in the GPS task manager, and can be interrupted or paused by users. Otherwise, it will simply be running in the background, and never visible to the user.
If progress_regexp is specified, then the output of the process will be scanned for this regexp. The part that match will not be returned to on_match. Instead, they will be used to guess the current progress of the command. Two groups of parenthesis are parsed, the one at progress_current, and the one at progress_total. The number returned for each of these groups indicate the current progress of the command, and the total that must be reached for this command to complete. For instance, if your process outputs lines like "done 2 out of 5", you should create a regular expression that matches the 2 and the 5 to guess the current progress. As a result, a progress bar is displayed in the task manager of GPS, and will allow users to monitor commands.

remote_server represents the server used to spawn the process. By default, the GPS_Server is used, which is always the local machine. See the section "Using GPS for Remote Development" in the GPS documentation for more information on this field.

If show_command is set, then the command line used to spawn the new Process is displayed in the "Messages" console.

If strip_cr is true, the output of the process will have all its \r removed before the string is passed on to GPS and your script. This in general provides better portability to Windows systems, but might not be suitable for applications for which CR is relevant (for instance those that drive an ANSI terminal).

An exception is raised if the process could not be spawned.</description>
      <see_also name="GPS.Process"/>
  </shell_doc>

  <shell_doc name="GPS.Process.set_size">
      <param name="self">The instance of GPS.Process</param>
      <param name="rows">An integer</param>
      <param name="columns">An integer</param>
      <description>Tells the process about the size of its terminal. Rows and columns should (but need not) be the number of visible rows and columns of the terminal in which the process is running.</description>
  </shell_doc>

  <shell_doc name="GPS.Process.send">
      <param name="self">The instance of GPS.Process</param>
      <param name="command">A string</param>
      <param name="add_lf" default="true">A boolean</param>
      <description>Send a line of text to the process. If you need to close the input stream to an external process, it often works to send the character ASCII 4, for instance through the python command chr(4).</description>
  </shell_doc>

  <shell_doc name="GPS.Process.get_result">
      <param name="self">The instance of GPS.Process</param>
      <return>A string</return>
      <description>Wait till the process terminates, and return its output. This is the output since the call to get_result, ie if you call get_result after performing some calls to expect, the returned string does not return the output that was already returned by expect.</description>
  </shell_doc>

  <shell_doc name="GPS.Process.interrupt">
      <param name="self">The instance of GPS.Process</param>
      <description>Interrupt a process controlled by GPS</description>
  </shell_doc>

  <shell_doc name="GPS.Process.kill">
      <param name="self">The instance of GPS.Process</param>
      <description>Terminate a process controlled by GPS</description>
  </shell_doc>

  <shell_doc name="GPS.Process.expect">
      <param name="self">The instance of GPS.Process</param>
      <param name="regexp">A string</param>
      <param name="timeout" default="-1">An integer, in milliseconds</param>
      <return>A string</return>
      <description>Block the execution of the script until either regexp has been seen in the output of the command, or the timeout has expired. If the timeout is negative, wait forever until we see the regexp or the process finishes its execution.
While in such a call, the usual on_match callback is called as usual, so you might need to add an explicit test in your on_match callback not to do anything in this case.
This command returns the output of the process since the start of the call to expect and up to the end of the text that matched regexp. Note that it will also include the output that was sent to the on_match callback while expect was running. It will not however include output already returned by a previous call to expect (nor does it guarantee that two successive calls to expect will return the full output of the process, since some output might have been matched by on_match between the two calls, and would not be returned by the second expect).
If a timeout occurred or the process terminated, an exception is raised</description>
    <example lang="python">
       proc = GPS.Process ("/bin/sh")
       print ("Output till prompt=" + proc.expect (">"))
       proc.send ("ls")
    </example>
  </shell_doc>

  <shell_doc name="GPS.Process.wait">
      <param name="self">The instance of GPS.Process</param>
      <return>An integer</return>
      <description>Block the execution of the script until the process has finished executing. The exit callback registered when the process was started will be called before returning from this function.

This function returns the exit status of the command.</description>
  </shell_doc>

  <!--#################################################################
    ####   Command class
    ###################################################################-->

  <shell_doc name="GPS.Command">
      <description>Interface to GPS command. This class is abstract, and shall be subclassed.</description>
  </shell_doc>

  <shell_doc name="GPS.Command.__del__">
      <description>Destructor of a GPS command. This should not be called manually by the user.</description>
  </shell_doc>

  <shell_doc name="GPS.Command.get">
      <param name="name">A string</param>
      <description>Return the list of commands of the name given in parameter, scheduled or running in the task manager</description>
  </shell_doc>

  <shell_doc name="GPS.Command.get_result">
      <param name="self">The instance of GPS.Command</param>
      <description>Return the result of the command, if any. Must be overriden by children</description>
  </shell_doc>

  <shell_doc name="GPS.Command.interrupt">
      <param name="self">The instance of GPS.Command</param>
      <description>Interrupt the current command</description>
  </shell_doc>

  <shell_doc name="GPS.Command.list">
      <description>Return the list of commands scheduled or running in the task manager</description>
  </shell_doc>

  <shell_doc name="GPS.Command.name">
      <param name="self">The instance of GPS.Command</param>
      <description>Return The name of the command</description>
  </shell_doc>

  <shell_doc name="GPS.Command.progress">
      <param name="self">The instance of GPS.Command</param>
      <description>Return a list ['current', 'total'], representing the current progress of the command. If current = total, then the command is finished. </description>
  </shell_doc>

  <!--#################################################################
    ####   Hook class
    ###################################################################-->

  <shell_doc name="GPS.Hook">
      <description>General interface to hooks. Hooks are commands executed when some specific events occur in GPS, and allow you to customize some of the aspects of GPS</description>
      <see_also name="GPS.Hook.__init__()" />
 </shell_doc>

  <shell_doc name="GPS.Hook.__init__">
      <param name="self">The instance of GPS.Hook we are initializing</param>
      <param name="name">A string, the name of the hook</param>
      <description>Create a new hook instance, which refers to one of the already defined hooks</description>
  </shell_doc>

  <shell_doc name="GPS.Hook.run">
      <param name="self">The instance of GPS.Hook</param>
      <param name="...">Any number of parameters to pass to the hook.
      <return>Depends on the type of the hook</return>
The specific list depends on the hook type</param>
      <description>Run the hook. This will call all the functions that attached to that hook, and return the return value of the last callback (this depends on the type of the hook, most often this is always None). When the callbacks for this hook are expected to return a boolean, this command stops as soon as one the callbacks returns True</description>
      <see_also name="GPS.Hook.run_until_success" />
      <see_also name="GPS.Hook.run_until_failure" />
  </shell_doc>

  <shell_doc name="GPS.Hook.run_until_success">
      <param name="self">The instance of GPS.Hook</param>
      <param name="...">Any number of parameters to pass to the hook.</param>
      <return>A boolean</return>
      <description>This only applies to hooks returning a boolean. This executes all functions attached to this hook, until one returns True, in which case no further function is called. This returns the returned value of the last executed function. This is mostly the same as GPS.Hook.run, but makes the halt condition more explicit.</description>
      <see_also name="GPS.Hook.run_until_failure"/>
      <see_also name="GPS.Hook.run" />
  </shell_doc>

  <shell_doc name="GPS.Hook.run_until_failure">
      <param name="self">The instance of GPS.Hook</param>
      <param name="...">Any number of parameters to pass to the hook.</param>
      <return>A boolean</return>
      <description>This only applies to hooks returning a boolean. This executes all functions attached to this hook, until one returns False, in which case no further function is called. This returns the returned value of the last executed function.</description>
      <see_also name="GPS.Hook.run_until_success"/>
      <see_also name="GPS.Hook.run" />
  </shell_doc>

  <shell_doc name="GPS.Hook.add">
      <param name="self">The instance of GPS.Hook</param>
      <param name="function_name">A subprogram, see the "Subprogram Parameters" section in the GPS documentation</param>
      <param name="last" default="True">A boolean</param>
      <description>Connect a new function to a specific hook. Any time this hook is run through run_hook, this function will be called with the same parameters passed to run_hook. If Last is True, then this function will be called after all functions currently added to this hook. If Last is False, it will be called before.</description>
      <example lang="shell">
        parse_xml """&lt;action name="edited"&gt;&lt;shell&gt;echo "File edited hook=$1 file=$2"&lt;/shell&gt;&lt;/action&gt;"""
        Hook "file_edited"
        Hook.add %1 "edited"
     </example>
     <example lang="python">
        def filed_edited (hook_name, file):
            print "File edited (hook=" + hook_name + " file=" + file.name()
        GPS.Hook ("file_edited").add (file_edited)
     </example>
     <see_also name="GPS.Hook.remove" />
  </shell_doc>

  <shell_doc name="GPS.Hook.remove">
     <param name="self">The instance of GPS.Hooh</param>
     <param name="function_name">A subprogram, see the "Subprogram Parameters" section in the GPS documentation</param>
     <description>Remove function_name from the list of functions executed when the hook is run. This is the reverse of GPS.Hook.add</description>
     <see_also name="GPS.Hook.add" />
  </shell_doc>

  <shell_doc name="GPS.Hook.register">
      <param name="name">A string, the name of the hook to create</param>
      <param name="type" default="">A string, the type of the hook. See GPS.Hook.list_types()</param>
      <description>Defines a new hook. This hook can take any number of parameters, the default is none. The type and number of parameters is called the type of the hook, and this is described by the" optional second parameter. The value of this parameter should be either the empty string for a hook that doesn't take any parameter. Or it could be one of the predefined types exported by GPS itself (see list_hook_types). Finally, it could be the word ""generic"" if this is a new type of hook purely defined for this scripting language</description>
  </shell_doc>

  <shell_doc name="GPS.Hook.list">
      <return>A list of strings</return>
      <description>List all defined hooks. See also run_hook, register_hook and add_hook</description>
      <see_also name="GPS.Hook.list_types" />
  </shell_doc>

  <shell_doc name="GPS.Hook.describe_functions">
      <param name="self">The instance of GPS.Hook</param>
      <return>A list of strings</return>
      <description>List all the functions that are executed when the hook is executed. The returned list might contain &lt;&lt;internal&gt; strings, which indicate that some Ada function is connected to this hook</description>
  </shell_doc>

  <shell_doc name="GPS.Hook.list_types">
     <return>A list of strings</return>
     <description>List all defined type hooks</description>
     <see_also name="GPS.Hook.register"/>
  </shell_doc>

  <!--#################################################################
    ####   MDI class
    ###################################################################-->

  <shell_doc name="GPS.MDI">
    <description>Represents GPS's Multiple Document Interface. This gives access to general graphical commands for GPS, as well as control over the current layout of the windows within GPS</description>
    <see_also name="GPS.MDIWindow" />
    <example lang="python">
If you have installed the pygtk package (see GPS's documentation}, GPS will
export a few more functions to python so that it is easier to interact with
GPS itself. In particular, the GPS.MDI.add function allows you to put a
widget created by pygtk under control of GPS's MDI, so that users can interact
with it as with all other GPS windows.

Here is a small code example:

import GPS

## The following three lines are the usual to make pygtk visible
import pygtk
pygtk.require('2.0')
import gtk

def on_clicked (*args):
   GPS.Console().write ("button was pressed\n")

def create():
   button=gtk.Button ('press')
   button.connect ('clicked', on_clicked)
   GPS.MDI.add (button, "From testgtk", "testgtk")
   win = GPS.MDI.get ('testgtk')
   win.split ()

create()
    </example>
  </shell_doc>

  <shell_doc name="GPS.MDI.get">
     <param name="name">A string</param>
     <return>An instance of GPS.MDIWindow</return>
     <description>Return the window whose name is name. If there is no such window, None is returned</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.get_by_child">
     <param name="child">An instance of GPS.GUI</param>
     <return>An instance of GPS.MDIWindow</return>
     <description>Return the window that contains child, or raise an error if there is none</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.current">
     <return>An instance of GPS.MDIWindow</return>
     <description>Return the window that currently has the focus, or raise an error if there is none</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.children">
     <return>A list of GPS.MDIWindow</return>
     <description>Return all the windows currently in the MDI</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.dialog">
     <param name="msg">A string</param>
     <description>Display a modal dialog to report information to a user. This blocks the interpreter until the dialog is closed</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.yes_no_dialog">
     <param name="msg">A string</param>
     <return>A boolean</return>
     <description>Display a modal dialog to ask a question to the user. This blocks the interpreter until the dialog is closed. The dialog has two buttons Yes and No, and the selected button is returned to the caller</description>
     <example lang="python">
        if GPS.MDI.yes_no_dialog ("Do you want to print?"):
            print "You pressed yes"
     </example>
  </shell_doc>

  <shell_doc name="GPS.MDI.file_selector">
    <param name="file_filter" default="empty">A string</param>
    <return>An instance of GPS.File</return>
    <description>Display a modal file selector. The user selected file is returned, or a file with an empty name if 'Cancel' is pressed.
A file filter can be defined (such as "*.ads") to show only a category of files.</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.input_dialog">
     <param name="msg">A string</param>
     <param name="...">Any number of strings</param>
     <return>A list of strings</return>
     <description>Display a modal dialog and request some input from the user. The message is displayed at the top, and one input field is displayed for each remaining argument. The arguments can take the form ""label=value"", in which case ""value"" is used as default for this entry. The return value is the value that the user has input for each of these parameters.
An empty list is returned if the user presses Cancel</description>
     <example lang="python">
          a, b = GPS.MDI.input_dialog("Please enter values", "a", "b")
          print a, b
     </example>
  </shell_doc>

  <shell_doc name="GPS.MDI.save_all">
     <param name="force" default="false">A boolean</param>
     <description>Save all currently unsaved windows. This includes open editors, the project, and any other window that has registered some save callbacks.
If the force parameter is false, then a confirmation dialog is displayed so that the user can select which windows to save</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.exit">
      <param name="force" default="false">A boolean</param>
      <description>Exit GPS. If there are unsaved changes, a dialog is first displayed to ask whether these should be saved. If the user cancels the operation through the dialog, GPS will not exit. If force is true, then no dialog is open, and nothing is saved</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.add">
      <param name="widget">A widget, created by pygtk</param>
      <param name="title">A string</param>
      <param name="short">A string</param>
      <description>This function is only available if pygtk could be loaded in the python shell. You must install this library first, see the documentation for GPS.MDI itself.
This function adds a widget inside the MDI of GPS. The resulting window can then be manipulated by the user like any other standard GPS window. It can be split, floated, resized,... Title is the string used in the title bar of the window, short is the string used in the notebook tabs. You can immediately retrieve a handle to the created window by calling GPS.MDI.get (short).</description>
      <see_also name="GPS.MDI.get"/>
      <see_also name="GPS.GUI.pywidget" />
      <see_also name="GPS.MDI"/>
  </shell_doc>

  <shell_doc name="GPS.MDI.hide">
      <description>Hides the graphical interface of GPS.</description>
  </shell_doc>

  <shell_doc name="GPS.MDI.show">
      <description>Shows the graphical interface of GPS.</description>
  </shell_doc>

  <!--#################################################################
    ####   MDIWindow class
    ###################################################################-->

  <shell_doc name="GPS.MDIWindow">
     <description>This class represents one of the windows currently displayed in GPS. This includes both the windows currently visible to the user, and the
ones that are temporarily hidden, for instance because they are displayed below another window.
Windows acts as containers for other widgets</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.__init__">
     <param name="self">An instance of GPS.MDIWindow</param>
     <description>Prevents the creation of instances of GPS.MDIWindow. This is done by calling the various subprograms in the GPS.MDI class</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.split">
     <param name="self">An instance of GPS.MDIWindow</param>
     <param name="vertically" default="True">A boolean</param>
     <param name="reuse" default="False">A boolean</param>
     <description>Split the window in two parts, either horizontally (side by side), or vertically (one below the other). If reuse is true, attempt to reuse an existing space rather than splitting the current window. This should be used to avoid ending up with too small windows</description>
     <see_also name="GPS.MDIWindow.single()" />
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.float">
     <param name="self">An instance of GPS.MDIWindow</param>
     <param name="float" default="True">A boolean</param>
     <description>Float the window, ie create a new toplevel window to display it. It is then under control of the user's operating system or window manager. If float is False, the window is reintegrated within the GPS MDI instead</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.is_floating">
     <param name="self">An instance of GPS.MDIWindow</param>
     <return>A boolean</return>
     <description>Return whether the window is currently floating (ie in its own toplevel window), or False if the window is integrated into the main GPS window</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.raise_window">
     <param name="self">An instance of GPS.MDIWindow</param>
     <description>Raise the window so that it becomes visible to the user. The window also gains the focus</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.name">
     <param name="self">An instance of GPS.MDIWindow</param>
     <param name="short" default="False">A boolean</param>
     <return>A string</return>
     <description>Return the name of the window. If short is False, the long name is returned, ie the one that appears in the title bar. If short is True, the short name is returned, ie the one that appears in the notebook tabs.</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.rename">
     <param name="self">An instance of GPS.MDIWindow</param>
     <param name="name">A string</param>
     <param name="short" default="">A string</param>
     <description>Change the title used for a window. Name is the long title, as it appears in the title bar for instance, and short, if specified, is the name that appears in the notebook tabs.

Using this function might be dangereous in some contexts, since GPS keeps track of editors through their name.
</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.next">
     <param name="self">An instance of GPS.MDIWindow</param>
     <param name="visible_only" default="True">A boolean</param>
     <return>An instance of GPS.MDIWindow</return>
     <description>Return the next window in the MDI, or window itself if there is no other window. If visible_only is true, then only the windows currently visible to the user are visible. This always returns floating windows</description>
  </shell_doc>

  <shell_doc name="GPS.MDIWindow.get_child">
     <param name="self">An instance of GPS.MDIWindow</param>
     <return>An instance of GPS.GUI</return>
     <description>Return the child contained in the window. The returned value might be an instance of a subclass of GPS.GUI, if that window was created from a shell command</description>
     <example lang="python">
        Accessing the GPS.Console instance used for python can be done with:
           GPS.MDI.get ("Python").get_child()
     </example>
  </shell_doc>

  <!--#################################################################
    ####   Locations class
    ###################################################################-->

  <shell_doc name="GPS.Locations">
     <description>General interface to the locations window</description>
  </shell_doc>

  <shell_doc name="GPS.Locations.parse">
     <param name="output">A string</param>
     <param name="category">A string</param>
     <param name="regexp" default="">A string</param>
     <param name="file_index" default="-1">An integer</param>
     <param name="line_index" default="-1">An integer</param>
     <param name="column_index" default="-1">An integer</param>
     <param name="msg_index" default="-1">An integer</param>
     <param name="style_index" default="-1">An integer</param>
     <param name="warning_index" default="-1">An integer</param>
     <param name="highlight_category" default="Builder results">A string</param>
     <param name="style_category" default="Style errors">A string</param>
     <param name="warning_category" default="Builder warnings">A string</param>
     <description>Parse the contents of the string, which is supposedly the output of some tool, and add the errors and warnings to the locations window. A new category is created in the locations window if it doesn't exist. Preexisting contents for that category is not removed, see locations_remove_category.
The regular expression specifies how locations are recognized. By default, it matches file:line:column. The various indexes indicate the index of the opening parenthesis that contains the relevant information in the regular expression. Set it to 0 if that information is not available. Style_Index and Warning_Index, if they match, force the error message in a specific category.
highlight_category, style_category and warning_category reference the colors to use in the editor to highlight the messages when the regexp has matched. If they are set to the empty string, no highlighting is done in the editor. The default values match those by GPS itself to highlight the error messages. Create these categories with GPS.Editor.register_highlighting(). </description>
      <see_also name="GPS.Editor.register_highlighting()" />
  </shell_doc>

  <shell_doc name="GPS.Locations.add">
     <param name="category">A string</param>
     <param name="file">An instance of GPS.File</param>
     <param name="line">An integer</param>
     <param name="column">An integer</param>
     <param name="message">A string</param>
     <param name="highlight" default="">A string, the name of the highlight category</param>
     <param name="length" default="0">An integer</param>
     <param name="look_for_secondary" default="False">A boolean</param>
     <description>Add a new entry in the location window. Nodes are created as needed for the category or file. If Highlight is specified to a non-empty string, the whole line is highlighted in the file, with a color given by that highlight category (see register_highlighting for more information). Length is the length of the highlighting. The default value of 0 indicates that the whole line should be highlighted</description>
     <example lang="python">
        GPS.Editor.register_highlighting ("My_Category", "blue")
        GPS.Locations.add (category="Name in location window",
                           file=GPS.File ("foo.c"),
                           line=320,
                           column=2,
                           message="message",
                           highlight="My_Category")
     </example>
  </shell_doc>

  <shell_doc name="GPS.Locations.remove_category">
     <param name="category">A string</param>
     <description>Remove a category from the location window. This removes all associated files</description>
     <see_also name="GPS.Locations.list_categories" />
  </shell_doc>

  <shell_doc name="GPS.Locations.list_categories">
     <return>A list of strings</return>
     <description>Return the list of all categories currently displayed in the Locations window. These are the top-level nodes used to group information generally related to one command, like the result of a compilation.</description>
     <see_also name="GPS.Locations.remove_category" />
  </shell_doc>

  <shell_doc name="GPS.Locations.list_locations">
     <param name="category">A string</param>
     <param name="file">A string</param>
     <return>A list of EditorLocation</return>
     <description>Return the list of all file locations currently listed in the given category and file.</description>
     <see_also name="GPS.Locations.remove_category" />
  </shell_doc>

  <shell_doc name="GPS.Locations.dump">
     <param name="file">A string</param>
     <description>Dump the contents of the Locations View to the specified file, in XML format.</description>
  </shell_doc>

  <!--#################################################################
    ####   Debugger class
    ###################################################################-->

  <shell_doc name="GPS.Debugger">
     <description>Interface to debugger related commands. This class allows you to start a debugger and send commands to it.
By connection to the various debugger_* hooks, you can also monitor the state of the debugger.

By connecting to the "debugger_command_action_hook", you can also create your
own debugger commands, that the user can then type in the debugger console. This
is a nice way to implement debugger macros.

While developping such debugger interfaces, it might be useful to modify the file $HOME/.gps/traces.cfg, and add a line "GVD.Out=yes" in it. This will copy all input/output with the debuggers into the GPS log file.</description>
      <example lang="python">
import GPS

def debugger_stopped (hook, debugger):
   GPS.Console ("Messages").write (
     "hook=" + hook + " on debugger="
     + `debugger.get_num()` + "\n")
def start():
   d = GPS.Debugger.spawn (GPS.File ("../obj/parse"))
   d.send ("begin")
   d.send ("next")
   d.send ("next")
   d.send ("graph display A")
GPS.Hook ("debugger_process_stopped").add (debugger_stopped)
      </example>
      <see_also name="GPS.Debugger.__init__()" />
      <see_also name="@hook@ debugger_started" />
      <see_also name="@hook@ debugger_process_stopped" />
      <see_also name="@hook@ debugger_context_changed" />
  </shell_doc>

  <shell_doc name="GPS.Debugger.__init__">
     <param name="self">An instance of GPS.Debugger</param>
     <description>It is an error to create a Debugger instance directly. Instead, use GPS.Debugger.get() or GPS.Debugger.spawn()</description>
     <see_also name="GPS.Debugger.get()" />
     <see_also name="GPS.Debugger.spawn()" />
  </shell_doc>

  <shell_doc name="GPS.Debugger.get">
     <param name="id" default="">Either an integer or an instance of GPS.File</param>
     <return>An instance of GPS.Debugger</return>
     <description>This command gives access to an already running debugger, and will return an instance of GPS.Debugger attached to it. The parameter can be null, in which case the current debugger is returned; it can be an integer, in which case the corresponding debugger is returned (starting at 1); or it can be a file, in which case this function returns the debugger currently debugging that file.</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.list">
     <return>A list of GPS.Debugger instances</return>
     <description>This command returns the list of currently running debuggers</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.send">
     <param name="self">An instance of GPS.Debugger</param>
     <param name="cmd">A string</param>
     <param name="output" default="true">A boolean</param>
     <param name="show_in_console" default="false">A boolean</param>
     <return>A string</return>
     <description>This command executes cmd in the debugger. GPS is blocked while cmd is executing on the debugger. If output is true, the command is displayed in the console.
If show_in_console is True, the output of the command is displayed in the debugger console, but is not returned by this function. If show_in_console is False, the result is not displayed in the console, but is returned by this function</description>
     <see_also name="GPS.Debugger.non_blocking_send" />
   </shell_doc>

   <shell_doc name="GPS.Debugger.non_blocking_send">
     <param name="self">An instance of GPS.Debugger</param>
     <param name="cmd">A string</param>
     <param name="output" default="true">A boolean</param>
     <description>This command works like send, but is not blocking, and does not return the result.</description>
     <see_also name="GPS.Debugger.send" />
   </shell_doc>

   <shell_doc name="GPS.Debugger.command">
     <param name="self">An instance of GPS.Debugger</param>
     <return>A string</return>
     <description>Return the command that is being executed in the debugger. This is often only available when called from the debugger_state_changed hook, where it might also indicate the command that just finished</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.is_exec_command">
     <param name="self">An instance of GPS.Debugger</param>
     <return>A boolean</return>
     <description>Return true if the command returned by GPS.Debugger.command is likely to modify the stack trace in the debugger ("next", "cont", ...)</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.is_context_command">
     <param name="self">An instance of GPS.Debugger</param>
     <return>A boolean</return>
     <description>Return true if the command returned by GPS.Debugger.command is likely to modify the current context (current task, thread,...) after it has finished executing</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.is_break_command">
     <param name="self">An instance of GPS.Debugger</param>
     <return>A boolean</return>
     <description>Return true if the command returned by GPS.Debugger.command is likely to modify the list of breakpoints after it has finished executing</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.get_executable">
     <param name="self">An instance of GPS.Debugger</param>
     <return>An instance of GPS.File</return>
     <description>Returns the name of the executable currently debugged in that debugger</description>
     <see_also name="GPS.Debugger.get_num()" />
   </shell_doc>

   <shell_doc name="GPS.Debugger.get_num">
     <param name="self">An instance of GPS.Debugger</param>
     <return>An integer</return>
     <description>Returns the index of the debugger. This can be used later on to retrieve the debugger from GPS.Debugger.get(), or to get access to other windows associated with that debugger</description>
     <see_also name="GPS.Debugger.get_file()" />
   </shell_doc>

   <shell_doc name="GPS.Debugger.is_busy">
     <param name="self">An instance of GPS.Debugger</param>
     <return>A boolean</return>
     <description>Returns true if the debugger is currently executing a command. In this case, it is an error to send a new command to it</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.close">
     <param name="self">An instance of GPS.Debugger</param>
     <description>Closes the given debugger. This also closes all associated windows (call stack, console,...)</description>
   </shell_doc>

   <shell_doc name="GPS.Debugger.spawn">
     <param name="executable">An instance of GPS.File</param>
     <param name="args" default="">A string</param>
     <return>An instance of GPS.Debugger</return>
     <description>This command starts a new debugger. It will debug file. When file is executed, the extra arguments args are passed</description>
   </shell_doc>

  <!--#################################################################
    ####   Preference class
    ###################################################################-->

  <shell_doc name="GPS.Preference">
     <description>Interface to the GPS preferences, as set in the Edit/Preferences dialog. New preferences are created through XML customization files (or calls to GPS.parse_xml(), see the GPS documentation</description>
     <example lang="python">
        GPS.parse_xml ("""
           &lt;preference name="custom-adb-file-color"
               label="Background color for .adb files"
               page="Editor:Fonts &amp;amp; Colors"
               default="yellow"
               type="color" /&gt;""")
        print "color is " + GPS.Preference ("custom-adb-file-color").get()
     </example>
      <see_also name="GPS.Preference.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Preference.__init__">
     <param name="self">The instance of GPS.Preference</param>
     <param name="name">A string</param>
     <description>Initializes an instance of the GPS.Preference class, associating it with the preference given in parameter. The name is the one that can be found in the $HOME/.gps/preferences file. When you are creating a new preference, this name can include '/' characters, which will result in subpages created in the Preferences dialog. The name after the last '/' should only include letters and '-' characters.</description>
  </shell_doc>

  <shell_doc name="GPS.Preference.create">
     <param name="self">The instance of GPS.Preference</param>
     <param name="label">A string</param>
     <param name="type">A string, one of "integer", "boolean", "string", "color", "font", "enum", "multiline"</param>
     <param name="doc" default="">A string</param>
     <param name="default" default="">Depends on the type</param>
     <param name="*">Additional parameters depending on the type</param>
     <description>This function creates a new preference, and makes it visible in the preferences dialog. In the dialog, the preference appears in the page given by the name used when creating the instance of GPS.Preference. The label is used to qualify the preference, and doc will appear as a tooltip to explain the preference to users. The type describes the type of preference, and therefore how it should be edited by users.
The additional parameters depend on the type of preference you are creating:

For an "integer", the default value is 0, and the two additional parameters are the minimum and maximum possible values. These are integers.

For a "boolean", the default is True.

For a "string", the default is the empty string.
A "multiline" behaves the same as a string except it is edited on multiple lines in the Preferences dialog.

For a "color", the default is "black".

For a "font", the default is "sans 9".

For a "enum", any number of additional parameters can be specified. They are
all the possible values of the preference. The default is the index in the list of possible values, starting at 0.
     </description>
   </shell_doc>

  <shell_doc name="GPS.Preference.get">
     <param name="self">The instance of GPS.Preference</param>
     <return>A string or an integer</return>
     <description>Get value for the given preference. The exact returned type depends on the type of the preference. Note that boolean values are returned as integers, for compatibility with older versions of Pythons</description>
     <example lang="python">
         if GPS.Preference ("MDI-All-Floating"):
            print "We are in all-floating mode"
     </example>
  </shell_doc>

  <shell_doc name="GPS.Preference.set">
     <param name="self">The instance of GPS.Preference</param>
     <param name="value">A string, boolean or integer</param>
     <param name="save" default="true">A boolean</param>
     <description>Set value for the given preference. The type of the parameter depends on the type of the preference. If the save parameter is true, the new value is immediately saved for future GPS sessions, and the new value is taken into account by GPS itself. Otherwise, if set to false, you will need to call the hook "preferences_changed" to force it</description>
  </shell_doc>

  <!--#################################################################
    ####   GUI class
    ###################################################################-->

  <shell_doc name="GPS.GUI" >
     <description>This is an abstract class (ie no instances of it can be created from your code, which represents a graphical element of the GPS interface</description>
      <see_also name="GPS.GUI.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.GUI.__init__">
     <param name="self">The instance of GPS.GUI</param>
     <description>Prevents the creation of instances of GPS.GUI. Such instances are created automatically by GPS as a result of calling other functions</description>
     <see_also name="GPS.Toolbar().apppend()" />
     <see_also name="GPS.Toolbar().entry()" />
     <see_also name="GPS.Menu.get()" />
  </shell_doc>

  <shell_doc name="GPS.GUI.set_sensitive">
     <param name="self">The instance of GPS.GUI</param>
     <param name="sensitive" default="True">A boolean</param>
     <description>Indicate whether the associated graphical element should respond to user interaction or not. If the element is not sensitive, then the user will not be able to click on it</description>
     <see_also name="GPS.GUI.is_sensitive()" />
  </shell_doc>

  <shell_doc name="GPS.GUI.pywidget">
     <param name="self">The instance of GPS.GUI</param>
     <return>An instance of PyWidget</return>
     <description>This function is only available if GPS was compiled with support for pygtk, and the latter was found at run time. It returns a widget that can be manipulated through the usual PyGtk functions. PyGtk is a binding to the gtk+ toolkit, and allows you to create your own windows easily, or manipulate the entire GPS GUI from python</description>
     <see_also name="GPS.MDI.add()" />
     <example lang="python">
          # The following example makes the project view inactive. One could easily
          # change the contents of the project view as well
          widget = GPS.MDI.get ("Project View")
          widget.pywidget().set_sensitive (False)
     </example>
  </shell_doc>

  <shell_doc name="GPS.GUI.is_sensitive">
     <param name="self">The instance of GPS.GUI</param>
     <return>A boolean</return>
     <description>Return False if the widget is currently greyed out, and is not clickable by users</description>
     <see_also name="GPS.GUI.set_sensitive()" />
  </shell_doc>

  <shell_doc name="GPS.GUI.destroy">
     <param name="self">The instance of GPS.GUI</param>
     <description>Destroy the graphical element. It will disappear from the interface, and cannot necessarily be recreated later on</description>
  </shell_doc>

  <shell_doc name="GPS.GUI.hide">
     <param name="self">The instance of GPS.GUI</param>
     <description>Temporarily hide the graphical element. It can be shown again through a call to GPS.GUI.show()</description>
     <see_also name="GPS.GUI.show()" />
  </shell_doc>

  <shell_doc name="GPS.GUI.show">
     <param name="self">The instance of GPS.GUI</param>
     <description>Show again the graphical element that was hidden by hide()</description>
     <see_also name="GPS.GUI.hide()" />
  </shell_doc>

  <!--#################################################################
    ####   Contextual class
    ###################################################################-->

  <shell_doc name="GPS.Contextual" >
     <description>This class is a general interface to the contextual menus in GPS. It gives you control over which menus should be displayed when the user right clicks in parts of GPS</description>
     <see_also name="GPS.Contextual.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Contextual.__init__">
     <param name="self">The instance of GPS.Contextual</param>
     <param name="name">A string</param>
     <description>Initializes a new instance of GPS.Contextual. The name is the name that was given to the contextual menu when it was created, and is a static string independent of the actual label used when the menu is displayed (and which is dynamic, depending on the context). You can get the list of valid names by checking the list of names returned by GPS.Contextual.list</description>
     <example lang="python">
You could for instance decide to always hide the "Goto declaration" contextual
menu with the following call:
    GPS.Contextual ('Goto declaration of entity').hide()

After this, the menu will never be displayed again.
     </example>
     <see_also name="GPS.Contextual.list()" />
  </shell_doc>

  <shell_doc name="GPS.Contextual.list">
     <description>Return the list of all registered contextual menus. This is a list of strings which are valid names that can be passed to the constructor of GPS.Contextual. These names were created when the contextual menu was registered in GPS.</description>
     <see_also name="GPS.Contextual.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Contextual.show">
     <param name="self">The instance of GPS.Contextual</param>
     <description>Make sure the contextual menu will be shown when appropriate. The entry might still be invisible if you right clicked on a context where it doesn't apply, but it will be checked</description>
     <see_also name="GPS.Contextual.hide" />
  </shell_doc>

  <shell_doc name="GPS.Contextual.hide">
     <param name="self">The instance of GPS.Contextual</param>
     <description>Make sure the contextual menu will never appear when the user right clicks anywhere in GPS. This is the standard way to disable contextual menus</description>
     <see_also name="GPS.Contextual.show" />
  </shell_doc>

  <shell_doc name="GPS.Contextual.set_sensitive">
     <param name="self">The instance of GPS.Contextual</param>
     <param name="Sensitivity">Boolean value</param>
     <description>Control whether the contextual menu is grayed-out: False if it should be grayed-out, True otherwise.</description>
  </shell_doc>

  <shell_doc name="GPS.Contextual.create">
     <param name="self">The instance of GPS.Contextual</param>
     <param name="on_activate">A subprogram with one parameter context</param>
     <param name="label" default="None">A subprogram</param>
     <param name="ref" default="">A string</param>
     <param name="add_before" default="True">A boolean</param>
     <param name="filter" default="None">A subprogram</param>
     <param name="group" default="0">An integer</param>
     <description>Create a new contextual menu entry.
Whenever this menu entry is selected by the user, GPS will execute on_activate, passing one parameter which is the context for which the menu is displayed (this is generally the same as GPS.current_contextual()).

If on_activate is None, a separator will be created.

The filter parameter can be used to filter when the entry should be displayed in the menu. It is a subprogram that receives one parameter, an instance of GPS.Context, and returns a boolean. If it returns True, the entry will be displayed, otherwise it is hidden.

The label parameter can be used to control the text displayed in the contextual menu.
By default, it is the same as the contextual name (used in the constructor to GPS.Contextual.__init__).
If specified, it must be a subprogram that takes an instance of
GPS.Context in parameter, and returns a string, which will be displayed in the menu.
The parameters group, ref and add_before can be used to control the location of the entry within the contextual menu.
group allows you to create groups of contextual menus that will be put together.
Items of the same group appear before all items with a greater group number.
ref is the name of another contextual menu entry, and add_before indicates
whether the new entry is put before or after that second entry.</description>
     <example lang="python">
## This example demonstrates how to create a contextual
## menu with global functions

def on_contextual (context):
   GPS.Console ("Messages").write ("You selected the custom entry\n")

def on_filter (context):
   return isinstance (context, GPS.EntityContext)

def on_label (context):
   global count
   count = count + 1
   return "Custom " + count

GPS.Contextual  ("Custom").create \
   (on_activate=on_contextual, filter=on_filter, label=on_label)
     </example>
     <example lang="python">
## This example is similar to the one above, but uses a python
## class to encapsulate date.
## Note how the extra parameter self can be passed to the callbacks
## thanks to the call to self.create

class My_Context (GPS.Contextual):
   def on_contextual (self, context):
       GPS.Console ("Messages").write \
          ("You selected the custom entry " + self.data)
   def on_filter (self, context):
       return isinstance (context, GPS.EntityContext)
   def on_label (self, context):
       return self.data
   def __init__ (self):
       GPS.Contextual.__init__ (self, "Custom")
       self.data = "Menu Name"
       self.create (on_activate=self.on_contextual,
                    filter     =self.on_filter,
                    label      =self.label)
      </example>
   </shell_doc>

   <shell_doc name="GPS.Contextual.create_dynamic">
     <param name="self">The instance of GPS.Contextual</param>
     <param name="factory">A subprogram</param>
     <param name="on_activate">A subprogram</param>
     <param name="label" default="">A string</param>
     <param name="filter" default="None">A subprogram</param>
     <param name="ref" default="">A string</param>
     <param name="add_before" default="True">A boolean</param>
     <param name="group" default="0">A integer</param>
     <description>Create a new dynamic contextual menu.
This is a submenu of a contextual menu, where the entries are generated by the factory parameter. This parameter should return a list of strings, which will be converted to menus by GPS. These strings can contain '/' characters to indicate submenus.

filter is a subprogram that takes the GPS.Context as a parameter, and returns a boolean indicating whether the submenu should be displayed.

Label can be used to specify the label to use for the menu entry. It can include directory-like syntax to indicate submenus. This label can include standard macro substitution (see the GPS documentation), for instance %e for the current entity name.

on_activate is called whenever any of the entry of the menu is selected, and is passed three parameters, the context in which the contextual menu was displayed, the string representing the selected entry and the index of the selected entry within the array returned by factory (index starts at 0).

The parameters ref and add_before can be used to control the location of the entry within the contextual menu. ref is the name of another contextual menu entry, and add_before indicates whether the new entry is put before or after that second entry.</description>
     <example lang="python">
## This example shows how to create a contextual menu
## through global functions

def build_contextual (context):
   return ["Choice1", "Choice2"]

def on_activate (context, choice, choice_index):
   GPS.Console ("Messages").write ("You selected " + choice)

def filter (contextl):
   return isinstance (context, GPS.EntityContext)

GPS.Contextual ("My_Dynamic_Menu").create_dynamic \
   (on_activate=on_activate, factory=build_contextual, filter=filter)
      </example>
      <example lang="python">
## This example is similar to the one above, but shows how
## to create the menu through a python class.
## Note how self can be passed to the callbacks thanks to the
## call to self.create_dynamic.

class Dynamic (GPS.Contextual):
   def __init__ (self):
      GPS.Contextual.__init__ (self, "My Dynamic Menu")
      self.create_dynamic (on_activate = self.on_activate,
                           label       = "References/My menu",
                           filter      = self.filter,
                           factory     = self.factory)
   def filter (self, context):
      return isinstance (context, GPS.EntityContext)
   def on_activate (self, context, choice):
      GPS.Console ("Messages").write ("You selected " + choice)
   def factory (self, context):
      return ["Choice1", "Choice2"]
       </example>
   </shell_doc>

  <!--#################################################################
   ##### Socket class
   ####################################################################-->

  <shell_doc name="GPS.Socket">
     <description>This class provides an interface to the sockets created by GPS when using the --server switch</description>
     <see_also name="GPS.Socket.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Socket.__init__">
     <param name="self">The instance of GPS.Socket</param>
     <param name="id">A string</param>
     <description>Creates an interface to one of the specific clients connected to GPS through the --server socket. The id can be set by the client by sending the "id" command to GPS</description>
  </shell_doc>

  <shell_doc name="GPS.Socket.send">
     <param name="self">An instance of the Socket class</param>
     <param name="msg">A string</param>
     <description>When GPS is running in server mode (using the --server switch), send msg to the socket identified by self.</description>
  </shell_doc>

  <shell_doc name="GPS.Socket.close">
     <param name="self">An instance of the Socket class</param>
     <description>Closes the socket. The client that was connected to that socket will be notified by the system that the socket was closed, and react as needed</description>
  </shell_doc>

  <shell_doc name="GPS.Socket.list">
     <return>List of strings</return>
     <description>Return a list of all the registered socket identifiers. These strings can be used to instantiate GPS.Socket.</description>
   </shell_doc>

  <!--#################################################################
      ### SwitchesChooser
      #################################################################-->

  <shell_doc name="GPS.SwitchesChooser">
     <description>This class represents a gtk widget that can be used to edit a tool's command line.</description>
  </shell_doc>

  <shell_doc name="GPS.SwitchesChooser.__init__">
     <param name="self">The instance of GPS.SwitchesChooser</param>
     <param name="name">A string</param>
     <param name="xml">A string</param>
     <description>Creates a new SwitchesChooser widget from the tool's name and switch description in xml format.</description>
  </shell_doc>

  <shell_doc name="GPS.SwitchesChooser.set_cmd_line">
      <param name="self">An instance of GPS.SwitchesChooser</param>
      <param name="cmd_line">A string</param>
      <description>Modify the widget's aspect to reflect the command line.</description>
  </shell_doc>

  <shell_doc name="GPS.SwitchesChooser.get_cmd_line">
      <param name="self">An instance of GPS.SwitchesChooser</param>
      <return>A string</return>
      <description>Return the tool's command line parameter</description>
  </shell_doc>

  <!--#################################################################
      ### EditorOverlay
      #################################################################-->

  <shell_doc name="GPS.EditorOverlay">
     <description>This class represents properties that can be applied to one or more ranges of text. This can be used to change the display properties of the text (colors, fonts,...) or store any user-specific attributes that can be retrieved later. GPS itself uses overlays to do syntax highlighting. If two or more overlays are applied to the same range of text, the final colors and fonts of the text depends on the priorities of these overlays and the order in which they were applied to the buffer.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorOverlay.__init__">
     <description>This subprogram is used to prevent the direct creation of overlays. Overlays need to be created through GPS.EditorBuffer.create_overlay</description>
     <see_also name="GPS.EditorBuffer.create_overlay" />
  </shell_doc>

  <shell_doc name="GPS.EditorOverlay.set_property">
      <param name="self">An instance of GPS.EditorOverlay</param>
      <param name="name">A string</param>
      <param name="value">A string or a boolean, depending on the property</param>
      <description>This function is used to change some of the predefined properties of the overlay. These are mostly used to change the visual rendering of the text,... The following attribute names are currently recognized:

    - &lt;b&gt;foreground&lt;/b&gt;(value is a string with the color name): Change the foreground color of the text.

    - &lt;b&gt;background&lt;/b&gt;(value is a string with the color name): Change the background color of the text.

    - &lt;b&gt;font&lt;/b&gt;(value is a string with the font name): Changes the font of the text

    - &lt;b&gt;weight&lt;/b&gt;(value is a string, one of "light", "normal" and "bold"

    - &lt;b&gt;style&lt;/b&gt;(value is a string, one of "normal", "oblique" and "italic"

    - &lt;b&gt;editable&lt;/b&gt;(value is a boolean): Indicates whether this range of text is editable or not

The set of predefined attributes is fixed. However, overlays are especially useful to store your own user data in the usual python manner, which you can retrieve later. This can be used to mark specially specific ranges of text which you want to be able to find easily later on, even if the buffer has been modified since then (see GPS.EditorLocation.forward_overlay)
    </description>
  </shell_doc>

  <shell_doc name="GPS.EditorOverlay.get_property">
      <param name="self">An instance of GPS.EditorOverlay</param>
      <param name="name">A string</param>
      <return>A string or a boolean, depending on the property</return>
      <description>This subprogram is used to retrieve one of the predefined properties of the overlay. This list of these properties is described for GPS.EditorOverlay.set_property</description>
  </shell_doc>

  <shell_doc name="GPS.EditorOverlay.name">
      <param name="self">An instance of GPS.EditorOverlay</param>
      <return>A string</return>
      <description>Return the name associated with this overlay, as given to GPS.EditorBuffer.create_overlay()</description>
      <see_also name="GPS.EditorBuffer.create_overlay" />
  </shell_doc>

  <!--#################################################################
      ### EditorLocation
      #################################################################-->

  <shell_doc name="GPS.EditorLocation">
     <description>This class represents a location in a specific editor buffer. This location is not updated when the buffer changes, but will keep pointing to
the same line/column even if new lines are added in the buffer. This location is no longer valid when the buffer itself is destroyed, and the use of any of these subprograms will raise an exception.</description>
     <see_also name="GPS.EditorMark" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.__init__">
     <param name="self">The instance of GPS.EditorLocation</param>
     <param name="buffer">The instance of GPS.EditorBuffer</param>
     <param name="line">An integer</param>
     <param name="column">An integer</param>
     <description>Initializes a new instance. Creating two instances at the same location will not return the same instance of GPS.EditorLocation, and therefore any user data you have stored in the location will not be available in the second instance</description>
     <example lang="python">
         ed  = GPS.EditorBuffer.get (GPS.File ("a.adb"))
         loc = GPS.EditorLocation (ed, line=4, column=5)
         loc.data = "MY OWN DATA"
         loc2 = GPS.EditorLocation (ed, line=4, column=5)
         # loc2.data is not defined at this point
     </example>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.__cmp__">
     <param name="self">The instance of GPS.EditorLocation</param>
     <param name="location">An instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Internal subprogram used to implement the comparison of two locations. It returns -1, 0, or 1 depending on whether the first location is before, equal or after the second one. This is more conveniently used through the usual &lt;, == and &gt; operators in most languages</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.__add__">
     <param name="self">The instance of GPS.EditorLocation</param>
     <param name="count">An integer</param>
     <return>An instance of GPS.EditorLocation</return>
     <description>Return a new location located count characters after self. If count is negative, this moves backward in the buffer. It is more conveniently used through the standard + operator in python</description>
     <example lang="python">
         ed   = GPS.EditorBuffer.get (GPS.File ("a.adb"))
         loc  = GPS.EditorLocation (ed, line=4, column=5)
         loc2 = loc + 3
     </example>
     <see_also name="GPS.EditorLocation.__sub__"/>
     <see_also name="GPS.EditorLocation.forward_char"/>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.__sub__">
     <param name="self">The instance of GPS.EditorLocation</param>
     <param name="count">An integer or another instance of GPS.EditorLocation</param>
     <return>A new instance of GPS.EditorLocation</return>
     <description>Return a new location located count characters before self, if count is an integer. If count is negative, moves forward instead. If count is another location, it returns the number of characters between the two locations. This function is more conveniently used through the standard - operator in python.</description>
     <see_also name="GPS.EditorLocation.__add__" />
     <see_also name="GPS.EditorLocation.forward_char" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.beginning_of_line">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>A new instance of GPS.EditorLocation</return>
     <description>Return a location located at the beginning of the line on which self is.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.end_of_line">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>A new instance of GPS.EditorLocation</return>
     <description>Return a location located at the end of the line on which self is.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_end_line">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Return the last line of the block surrounding the location. The definition of a block depends on the specific language of the source file</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_name">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>A string</return>
     <description>Return the name of the bock surrounding the location. The definition of a block depends on the specific language of the source file</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_fold">
     <param name="self">The instance of GPS.EditorLocation</param>
     <description>Fold the block containing the location, ie make it invisible on the screen, except for its first line. Clicking on the icon next to this first line will unfold the block and make it visible to the user</description>
     <see_also name="GPS.EditorLocation.block_unfold" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_unfold">
     <param name="self">The instance of GPS.EditorLocation</param>
     <description>Unfold the block containing the location, ie make it visible any information that was hidden as a result of running GPS.EditorLocation.block_fold</description>
     <see_also name="GPS.EditorLocation.block_fold" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_level">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Return the nesting level of the block surrounding the location. The definition of a block depends on the specific programming language</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_start_line">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Return the first line of the block surrounding the location. The definition of a block depends on the programming language</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_start">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An instance of GPS.EditorLocation</return>
     <description>Return the location of the beginning of the current block</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_end">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An instance of GPS.EditorLocation</return>
     <description>Return the location of the end of the current block</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.block_type">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>A string</return>
     <description>Return the type of the block surrounding the location. This type indicates whether the block is a subprogram, an if statement,...</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.buffer">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An instance of GPS.EditorBuffer</return>
     <description>Return the buffer in which the location is found</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.line">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Return the line of the location</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.column">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>An integer</return>
     <description>Return the column of the location</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.get_char">
     <param name="self">The instance of GPS.EditorLocation</param>
     <return>A UTF8 string</return>
     <description>Return the character at that location in the buffer. An exception is raised when trying to read past the end of the buffer. The character might be encoded on several bytes, since it is a UTF8 string.</description>
     <example lang="python">
        char = buffer.beginning_of_buffer().get_char()
        GPS.Console().write (char)  ## Prints the character
        # To manipulate in python, convert the string to a unicode string:
        unicode = char.decode("utf-8")
     </example>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.create_mark">
     <param name="self">The instance of GPS.EditorLocation</param>
     <param name="name" default="">A string</param>
     <return>An instance of GPS.EditorMark</return>
     <description>Create a mark at that location in the buffer. The mark will stay permanently at that location, and follows if the buffer is modified. If the name is specified, this creates a named mark, which can be retrieved through a call to GPS.EditorBuffer.get_mark. If a mark with the same name already exists, it is moved to the new location, and then returned</description>
     <example lang="python">
         buffer = GPS.EditorBuffer.get (GPS.File ("a.adb"))
         loc = GPS.EditorLocation (buffer, 3, 4)
         mark = loc.create_mark ()
         buffer.insert (loc, "text")
         loc = mark.location()
         # loc.column() is now 8
     </example>
     <see_also name="GPS.EditorBuffer.get_mark" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.forward_char">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="count">An integer</param>
      <return>A new instance of GPS.EditorLocation</return>
      <description>Return a new location located count characters after self. If count is negative, the location is moved backward instead</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.forward_word">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="count">An integer</param>
      <return>A new instance of GPS.EditorLocation</return>
      <description>Return a new location located count words after self. If count is negative, the location is moved backward instead. The definition of a word depends on the language used</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.starts_word">
      <param name="self">The instance of GPS.EditorLocation</param>
      <return>A boolean</return>
      <description>Return true if self is currently at the start of a word. The definition of a word depends on the language used</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.ends_word">
      <param name="self">The instance of GPS.EditorLocation</param>
      <return>A boolean</return>
      <description>Return true if self is currently at the end of a word. The definition of a word depends on the language used</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.forward_line">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="count">An integer</param>
      <return>A new instance of GPS.EditorLocation</return>
      <description>Return a new location located count lines after self. The location is moved back to the beginning of the line. In case self is on the last line, the beginning of the last line is returned.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.search">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="pattern">A string</param>
      <param name="backward" default="False">A boolean</param>
      <param name="case_sensitive" default="False">A boolean</param>
      <param name="regexp" default="False">A boolean</param>
      <param name="whole_word" default="False">A boolean</param>
      <param name="scope" default="Whole">A string</param>
      <param name="dialog_on_failure" default="True">A boolean</param>
      <return>A list of two GPS.EditorLocation</return>
      <description>This function searches for the next occurrence of Pattern in the editor, starting at the given location. If there is such a match, this function returns the two locations for the beginning of the match and the end of the match. Typically, these would be used to highlight the match in the editor.
When no match is found, this function returns null. Additionally, if dialog_on_failure is true then a dialog is displayed to the user asking whether the search should restart at the beginning of the buffer.</description>
      <see_also name="GPS.File.search" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.offset">
      <param name="self">The instance of GPS.EditorLocation</param>
      <return>An integer</return>
      <description>Return the offset of the location in the buffer, ie the number of characters from the beginning of the buffer to the location</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.subprogram_name">
      <param name="self">The instance of GPS.EditorLocation</param>
      <return>A string</return>
      <description>Return the name of the subprogram enclosing the location</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.get_overlays">
      <param name="self">The instance of GPS.EditorLocation</param>
      <return>A list of GPS.EditorOverlay instances</return>
      <description>This function returns the list of all the overlays that apply at this specific location. The color and font of the text is composed through the contents of these overlays.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.has_overlay">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="overlay">An instance of GPS.EditorOverlay</param>
      <return>A boolean</return>
      <description>This function returns True if the given overlay applies to the character at that location</description>
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.forward_overlay">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="overlay" default="">An instance of GPS.EditorOverlay</param>
      <return>An instance of GPS.EditorLocation</return>
      <description>Moves to the next change in the list of overlays applying to the character. If overlay is specified, go to the next change for this specific overlay (ie the next beginning or end of range where it applies). If there are no more changes, the location is left at the end of the buffer.</description>
      <see_also name="GPS.EditorLocation.backward_overlay" />
  </shell_doc>

  <shell_doc name="GPS.EditorLocation.backward_overlay">
      <param name="self">The instance of GPS.EditorLocation</param>
      <param name="overlay" default="">An instance of GPS.EditorOverlay</param>
      <return>An instance of GPS.EditorLocation</return>
      <description>Same as GPS.EditorLocation.forward_overlay, but moves backward instead. If there are no more changes, the location is left at the beginning of the buffer.</description>
  </shell_doc>

  <!--#################################################################
      ### EditorMark class
      #################################################################-->

  <shell_doc name="GPS.EditorMark">
      <description>This class represents a specific location in an open editor. As opposed to the GPS.EditorLocation class, the exact location is updated whenever the buffer is modified. For instance, if you add a line before the mark, then the mark is moved one line forward as well, so that it still points to the same character in the buffer.

The mark remains valid even if you close the buffer; or if you reopen it and modify it. It will always point to the same location in the file, while you have kept the python object.

GPS.EditorLocation.create_mark allows you to create named marks which you can then retrieve through GPS.EditorBuffer.get_mark. Such named marks are only valid while the editor exists. As soon as you close the editor, you can no longer use get_mark to retrieve it (but the mark is still valid if you have kept a python object referencing it).</description>
      <see_also name="GPS.EditorLocation" />
  </shell_doc>

  <shell_doc name="GPS.EditorMark.__init__">
     <description>This subprogram will always raise an exception, thus preventing the direct creation of a mark. Instead, you should use GPS.EditorLocation.create_mark() to create such a mark</description>
  </shell_doc>

  <shell_doc name="GPS.EditorMark.__del__">
     <param name="self">An instance of GPS.EditorMark</param>
     <description>This subprogram is automatically called whenever self is unreferenced by Python, and will destroy the physical mark in the buffer if the mark is unnamed, since there is no way to access it anyway afterward</description>
  </shell_doc>

  <shell_doc name="GPS.EditorMark.delete">
      <param name="self">An instance of GPS.EditorMark</param>
      <description>Delets the physical mark from the buffer. All instances referencing the same mark will no longer be valid. If you haven't given a name to the mark in the call to GPS.EditorLocation.create_mark(), it will automatically be destroyed when the last instance referencing it goes out of scope. Therefore, calling delete() is not mandatory in the case of unnamed marks, although it is still recommanded</description>
  </shell_doc>

  <shell_doc name="GPS.EditorMark.is_present">
      <param name="self">An instance of GPS.EditorMark</param>
      <description>Returns True if mark's location is still present in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorMark.location">
      <param name="self">An instance of GPS.EditorMark</param>
      <return>An instance of GPS.EditorLocation</return>
      <description>Returns the current location of the mark. This location will vary depending on the changes that take place in the buffer</description>
      <example lang="python">
         ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
         loc = GPS.EditorLocation (ed, 3, 5)
         mark = loc.create_mark()
         # ...
         loc = mark.location()
      </example>
  </shell_doc>

  <shell_doc name="GPS.EditorMark.move">
       <param name="self">An instance of GPS.EditorMark</param>
       <param name="location">An instance of GPS.EditorLocation</param>
       <description>Moves the mark to a new location in the buffer. This is slightly less expensive that destroying the mark and creating a new one through GPS.EditorLocation.create_mark, although the result is the same</description>
  </shell_doc>

  <!--#################################################################
      ### EditorBuffer class
      #################################################################-->

  <shell_doc name="GPS.EditorBuffer">
     <description>This class represents the physical contents of a file. It is always associated with at least one view (a GPS.EditorView instance), which makes it visible to the user. The contents of the file can be manipulated through this class</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.__init__">
     <description>This function prevents the direct creation of instances of EditorBuffer. Use GPS.EditorBuffer.get instead</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.add_special_line">
      <param name="start_line">An integer</param>
      <param name="text">A string</param>
      <param name="category" default="">A string</param>
      <param name="name" default="">A string</param>
      <return>An instance of GPS.EditorMark</return>
      <description>Adds one non-editable line to the buffer, starting at line start_line and contains string text. If category is specified, use it for highlighting. Create a mark at beginning of block and return it. If name is specified, retuned mark will have this name</description>
      <see_also name="GPS.EditorBuffer.get_mark"/>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.remove_special_lines">
      <param name="mark">An instance of GPS.EditorMark</param>
      <param name="lines">An integer</param>
      <description>Removes specified number of special lines at the specified mark. It doesn't delete the mark</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.get">
      <param name="file" default="current editor">An instance of GPS.File</param>
      <param name="force" default="false">A boolean</param>
      <param name="open" default="True">A boolean</param>
      <return>An instance of GPS.EditorBuffer</return>
      <description>If file is already opened in an editor, get a handle on its buffer. This instance is then shared with all other buffers referencing the same file. As a result, you can for instance associate your own data with the buffer, and retrieve it at any time until the buffer is closed. If the file is not opened yet, it is loaded in a new editor, and a new view is opened at the same time (and thus the editor becomes visible to the user).
If file is not specified, the current editor is returned, ie the last one that had the keyboard focus.

If the file is not currently open, the behavior depends on the open parameter: if true, a new editor is created for that file, otherwise None is returned.

When a new file is open, it has received the focus. But if the editor already existed, it is not raised explicitly, and you need to do it yourself through a call to GPS.MDIWindow.raise_window (see the example below).

If force is set to true, a reload is forced in case the file is already open.
      </description>
      <example lang="python">
          ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
          GPS.MDI.get_by_child (ed.current_view()).raise_window()
          ed.data = "whatever"
          # ... Whatever, including modifying ed
          ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
          data = ed.data   # "whatever"
      </example>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.get_new">
      <return>An instance of GPS.EditorBuffer</return>
      <description>Open a new editor on a blank file. This file has no name, and you'll have to provide one when you save it</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.list">
       <return>A list of instances of GPS.EditorBuffer</return>
       <description>This function returns the list of all editors that are currently open in GPS.</description>
       <example lang="python">
It is possible to close all editors at once using a command like
      for ed in GPS.EditorBuffer.list(): ed.close()
       </example>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.file">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An instance of GPS.File</return>
       <description>Returns the name of the file edited in this buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.current_view">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An instance of GPS.EditorView</return>
       <description>Returns the last view used for this buffer, ie the last view that had the focus and through which the user might have edited the buffer's contents</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.views">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>A list of GPS.EditorView instances</return>
       <description>Returns the list of all views currently editing the buffer. There is always at least one such view. When the last view is destroyed, the buffer itself is destroyed</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.close">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="force" default="False">A boolean</param>
       <description>Closes the editor and all its views. If the buffer has been modified and not saved, a dialog is open asking the user whether to save. If force is True, do not save and do not ask the user. All changes are lost</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.characters_count">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An integer</return>
       <description>Returns the total number of characters in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.lines_count">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An integer</return>
       <description>Returns the total number of lines in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.select">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
       <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
       <description>Selects an area in the buffer. The boundaries are included in the selection. The order of the boundaries is irrelevant, but the cursor will be left on to</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.unselect">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Cancel the current selection in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.selection_start">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An instance of GPS.EditorLocation</return>
       <description>Return the start of the selection. This will always be located before the end of the selection, no matter the order of parameters given to GPS.EditorBuffer.select</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.selection_end">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>An instance of GPS.EditorLocation</return>
       <description>Return the character after the end of the selection. This will always be located after the start of the selection, no matter the order of parameters given to GPS.EditorBuffer.select. If the selection is empty, EditorBuffer.selection_start and EditorBuffer.selection_end will be equal.</description>
       <example lang="python">
       To get the contents of the current selection, one would use:
           buffer = GPS.EditorBuffer.get()
           selection = buffer.get_chars (buffer.selection_start(), buffer.selection_end() - 1)
       </example>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.copy">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
       <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
       <param name="append" default="False">A boolean</param>
       <description>Copy the given range of text into the clipboard, so that it can be further pasted into other applications or other parts of GPS. If append is True, the text is appended to the last clipboard entry instead of generating a new one</description>
       <see_also name="GPS.Clipboard.copy"/>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.cut">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
       <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
       <param name="append" default="False">A boolean</param>
       <description>Copy the given range of text into the clipboard, so that it can be further pasted into other applications or other parts of GPS. The text is removed from the edited buffer. If append is True, the text is appended to the last clipboard entry instead of generating a new one</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.paste">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="location">An instance of GPS.EditorLocation</param>
       <description>Paste the contents of the clipboard at the given location in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.is_modified">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <return>A boolean</return>
       <description>Tests whether the buffer has been modified since it was last open or saved</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.blocks_fold">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Folds all the blocks in all the views of the buffer. Block folding is a language-dependent feature, whereby one can hide part of the source code temporarily, by keeping only the first line of the block (for instance the first line of a subprogram body, the rest is hidden). A small icon is displayed to the left of the first line so that it can be unfolded later on</description>
       <see_also name="GPS.EditorBuffer.blocks_unfold" />
       <see_also name="GPS.EditorLocation.block_fold" />
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.blocks_unfold">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Unfolds all the blocks that were previously folded in the buffer, ie make the whole source code visible. This is a language dependent feature</description>
       <see_also name="GPS.EditorBuffer.blocks_fold" />
       <see_also name="GPS.EditorLocation.block_unfold" />
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.get_chars">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
       <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
       <return>A string</return>
       <description>Returns the contents of the buffer between the two locations given in parameter. Modifying the returned value has no effect on the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.insert">
    <param name="self">An instance of GPS.EditorBuffer</param>
    <param name="location">An instance of GPS.EditorLocation</param>
    <param name="text">A string</param>
    <description>Inserts some text in the buffer</description>
    <see_also name="GPS.EditorBuffer.delete" />
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.delete">
    <param name="self">An instance of GPS.EditorBuffer</param>
    <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
    <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
    <description>Delete the given range of text from the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.indent">
    <param name="self">An instance of GPS.EditorBuffer</param>
    <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
    <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
    <description>Recompute the indentation of the given range of text. This feature is language-dependent</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.refill">
    <param name="self">An instance of GPS.EditorBuffer</param>
    <param name="frm" default="beginning of buffer">An instance of GPS.EditorLocation</param>
    <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
    <description>Refill the given range of text, ie cut long lines if necessary so that they fit in the limit specified in the GPS preferences</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.beginning_of_buffer">
     <param name="self">An instance of GPS.EditorBuffer</param>
     <return>An instance of GPS.EditorLocation</return>
     <description>Returns a location pointing to the first character in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.end_of_buffer">
     <param name="self">An instance of GPS.EditorBuffer</param>
     <return>An instance of GPS.EditorLocation</return>
     <description>Returns a location pointing to the last character in the buffer</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.save">
     <param name="self">An instance of GPS.EditorBuffer</param>
     <param name="interactive" default="True">A boolean</param>
     <param name="file" default="Same file as edited by the buffer">An instance of GPS.File</param>
     <description>Saves the buffer to the given file. If interactive is true, a dialog is open to ask for confirmation from the user first, which gives him a chance to cancel the saving. "interactive" is ignored if file is specified.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.get_mark">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <param name="name">A string</param>
      <return>An instance of GPS.EditorMark</return>
      <description>Check whether there is a mark with that name in the buffer, and return it. An exception is raised if there is no such mark</description>
      <see_also name="GPS.EditorLocation.create_mark" />
      <example lang="python">
         ed = GPS.EditorBuffer.get (GPS.File ("a.adb"))
         loc = GPS.EditorLocation (ed, 4, 5)
         mark = loc.create_mark ("name")
         mark.data = "whatever"
         # .. anything else
         mark = ed.get_mark ("name")
         # mark.data is still "whatever"
      </example>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.create_overlay">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <param name="name" default="">A string</param>
      <return>An instance of GPS.EditorOverlay</return>
      <description>Create a new overlay. Properties can be set on this overlay, which can then be applied to one or more ranges of text to changes its visual rqendering or to associate user data with it. If name is specified, this function will return an existing overlay with the same name in this buffer if any can be found. If the name is not specified, a new overlay is created. Changing the properties of an existing overlay results in an immediate graphical update of the views associated with the buffer.
A number of predefined overlay exits. Among these are the ones used for syntax highlighting by GPS itself, which are "keyword", "comment", "string", "character". You can use these to navigate from one comment section to the next for instance.
</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.apply_overlay">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <param name="overlay">An instance of GPS.EditorOverlay</param>
      <param name="frm" default="begining of buffer">An instance of GPS.EditorLocation</param>
      <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
      <description>Applies the overlay to the given range of text. This immediately changes the rendering of the text based on the properties of the overlay</description>
      <see_also name="GPS.EditorBuffer.remove_overlay" />
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.remove_overlay">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <param name="overlay">An instance of GPS.EditorOverlay</param>
      <param name="frm" default="begining of buffer">An instance of GPS.EditorLocation</param>
      <param name="to" default="end of buffer">An instance of GPS.EditorLocation</param>
      <description>Removes all instances of the overlay in the given range of text. It isn't an error if the overlay is not applied to any of the character in the range, it just has no effect in that case.</description>
      <see_also name="GPS.EditorBuffer.apply_overlay" />
   </shell_doc>

  <shell_doc name="GPS.EditorBuffer.start_undo_group">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Starts grouping commands on the editor. All future editions will be considered as belonging to the same group. finish_undo_group should be called once for every call to start_undo_group.</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.finish_undo_group">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Cancels the grouping of commands on the editor. See GPS.EditorBuffer.start_undo_group</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.undo">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Undo the last command on the editor</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.redo">
       <param name="self">An instance of GPS.EditorBuffer</param>
       <description>Redo the last undone command on the editor</description>
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.is_read_only">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <return>A boolean</return>
      <description>Whether the buffer is editable or not.</description>
      <see_also name="GPS.EditorBuffer.set_read_only" />
  </shell_doc>

  <shell_doc name="GPS.EditorBuffer.set_read_only">
      <param name="self">An instance of GPS.EditorBuffer</param>
      <param name="read_only" default="True">A boolean</param>
      <description>Indicates whether the user should be able to edit the buffer interactively (through any view).</description>
      <see_also name="GPS.EditorBuffer.is_read_only" />
  </shell_doc>

  <!--#################################################################
      ### EditorView class
      #################################################################-->

  <shell_doc name="GPS.EditorView">
     <description>One view of an editor, ie the visible part through which users can modify text files. A given GPS.EditorBuffer can be associated with multiple views. Closing the last view associated with a buffer will also close the buffer</description>
     <example lang="python">
To get a handle on the current editor, use the following code:
     view = GPS.EditorBuffer.get().current_view()
     </example>
  </shell_doc>

  <shell_doc name="GPS.EditorView.__init__">
      <param name="self">An instance of GPS.EditorView</param>
      <param name="buffer">An instance of GPS.EditorBuffer</param>
      <description>This constructor is called implicitly whenever you create a new view. It creates a new view for the given buffer, and is automatically inserted into the GPS MDI</description>
  </shell_doc>

  <shell_doc name="GPS.EditorView.buffer">
      <param name="self">An instance of GPS.EditorView</param>
      <return>An instance of GPS.EditorBuffer</return>
      <description>Returns the buffer to which the view is attached. Editing the text of the file should be done through this instance</description>
  </shell_doc>

  <shell_doc name="GPS.EditorView.is_read_only">
      <obsolescent />
      <param name="self">An instance of GPS.EditorView</param>
      <return>A boolean</return>
      <description>Whether the view is editable or not. This property is in fact shared by all views of the same buffer.</description>
      <see_also name="GPS.EditorBuffer.is_read_only" />
  </shell_doc>

  <shell_doc name="GPS.EditorView.set_read_only">
      <obsolescent />
      <param name="self">An instance of GPS.EditorView</param>
      <param name="read_only" default="True">A boolean</param>
      <description>Indicates whether the user should be able to edit interactively through this view. Setting a view Writable/Read Only will also modify the status of the other views of the same buffer.xx</description>
      <see_also name="GPS.EditorBuffer.get_read_only" />
  </shell_doc>

  <shell_doc name="GPS.EditorView.center">
      <param name="self">An instance of GPS.EditorView</param>
      <param name="location" default="location of cursor">An instance of GPS.EditorLocation</param>
      <description>Scrolls the view so that the location is centered</description>
  </shell_doc>

  <shell_doc name="GPS.EditorView.title">
      <param name="self">An instance of GPS.EditorView</param>
      <param name="short" default="False">A boolean</param>
      <description>Returns the view's title, the short title is returned if
      short is set to True</description>
  </shell_doc>

  <shell_doc name="GPS.EditorView.goto">
      <param name="self">An instance of GPS.EditorView</param>
      <param name="location">An instance of GPS.EditorLocation</param>
      <description>Moves the cursor at the given location. Each view of a particular buffer has its own cursor position, which is where characters typed by the user will be inserted</description>
  </shell_doc>

  <shell_doc name="GPS.EditorView.cursor">
      <param name="self">An instance of GPS.EditorView</param>
      <return>An instance of GPS.EditorLocation</return>
      <description>Return the current location of the cursor in this view</description>
  </shell_doc>

  <!--#################################################################
    ####   Menu class
    ###################################################################-->

  <shell_doc name="GPS.Menu" >
      <description>This class is a general interface to the menu system in GPS. It gives you control over which menus should be active, what should be executed when the menu is selected by the user,...</description>
      <see_also name="GPS.Menu.__init__()" />
  </shell_doc>

  <shell_doc name="GPS.Menu.__init__">
     <param name="self">The instance of GPS.Menu</param>
     <description>Prevents the creation of a menu instance. Such instances can only be created internally by GPS as a result of calling GPS.Menu.get or GPS.Menu.create. This is so that you always get the same instance of GPS.Menu when
you are refering to a given menu in GPS, and so that you can store your own
specific data with the menu</description>
  </shell_doc>

  <shell_doc name="GPS.Menu.get">
     <param name="path">A string</param>
     <return>The instance of GPS.Menu</return>
     <description>Return the menu found at the given path. Path is similar to what one finds on a hard disk, starting with the main GPS menu ('/'), down to each submenus. For instance, '/VCS/Directory/Update Directory' refers to the
submenu 'Update Directory' of the submenu 'Directory' of the menu 'VCS'. Path is case-sensitive</description>
     <example lang="python">
        The following example will prevent the user from using the VCS menu and
        all its entries:
           GPS.Menu.get ('/VCS').set_sensitive (False)
     </example>
  </shell_doc>

  <shell_doc name="GPS.Menu.create">
     <param name="path">A string</param>
     <param name="on_activate" default="">A subprogram, see the GPS documentation on subprogram parameters</param>
     <param name="ref" default="">A string</param>
     <param name="add_before" default="True">A boolean</param>
     <return>The instance of GPS.Menu</return>
     <description>Create a new menu in the GPS system. The menu is added at the given location (see GPS.Menu.get for more information on the path parameter). Submenus are created as necessary so that path is valid.
If on_activate is specified, it will be executed every time the user selects that menu. It is called with only one parameter, the instance of GPS.Menu that was just created.
If ref and add_before are specified, they specify the name of another item in the parent menu (and not a full path) before or after which the new menu should be added.
If the name of the menu starts with a '-' sign, as in "/Edit/-", then a menu separator is inserted instead. In this case, on_activate is ignored.
Underscore characters ('_') need to be duplicated in the path. A single underscore indicates the mnemonic to be used for that menu. For instance, if you create the menu "/_File", then the user can open the menu by pressing alt-F. But the underscore itself will not be displayed in the name of the menu.</description>
     <example lang="python">
         def on_activate (self):
             print "A menu was selected: " + self.data

         menu = GPS.Menu.create ("/Edit/My Company/My Action", on_activate)
         menu.data = "my own data"   ## Store your own data in the instance
     </example>
  </shell_doc>

  <shell_doc name="GPS.Menu.rename">
     <param name="self">The instance of GPS.Menu</param>
     <param name="name">A string</param>
     <description>Change the name of a menu. The first underscore character seen in name will be used as the keyboard shortcut to access this menu from now on. If you actually want to insert an underscore in the name, you need to double it</description>
  </shell_doc>

  <!--#################################################################
      ### XMLViewer class
      #################################################################-->

  <shell_doc name="GPS.XMLViewer">
     <description>This class represents Tree-based views for XML files</description>
  </shell_doc>

  <shell_doc name="GPS.XMLViewer.__init__">
     <param name="self">An instance of GPS.XMLViewer</param>
     <param name="name">A string</param>
     <param name="columns" default="3">An integer</param>
     <param name="parser" default="none">A subprogram</param>
     <param name="on_click" default="none">A subprogram</param>
     <param name="on_select" default="none">A subprogram</param>
     <param name="sorted" default="False">A boolean</param>
     <description>Create a new XMLViewer, with the given name.

Columns is the number of columns that the table representation should have. The first column is
always the one used for sorting the table.

Parser is a subprogram called for each XML node that is parsed. It takes three arguments: the name of the XML node being visited, its attributes (in the form "attr='foo' attr="bar""), and the text value of that node. This subprogram should return a list of strings, one per visible column create for the table. Each element will be put in the corresponding column.

If Parser is unspecified, the default is to display in the first column the tag name, in the second column the list of attributes, and in the third column when it exists the textual contents of the node.

On_Click is an optional subprogram. It is called every time the user double-click on a line, and is passed the same arguments as Parser. It has no return value.

On_Select has the same profile as On_Click, but is called when the user has
selected a new line, not double-clicked on it.

If sorted is True, then the resulting graphical list is sorted on the first column.
</description>
      <example lang="python">
          # Display a very simply tree. If you click on the file name,
          # the file will be edited.
          import re

          xml = """&lt;project name='foo'&gt;
    &lt;file&gt;source.adb&lt;/file&gt;
 &lt;/project&gt;"""

          view = GPS.XMLViewer ("Dummy", 1, parser, on_click)
          view.parse_string (xml)

          def parser (node_name, attrs, value):
             attr = dict ()
             for a in re.findall ("""(\\w+)=['"](.*?)['"]\B""", attrs):
                attr[a[0]] = a[1]

             if node_name == "project":
                 return [attr["name"]]
             elif node_name == "file":
                 return [value]

          def on_click (node_Name, attrs, value):
             if node_name == "file":
                GPS.EditorBuffer.get (GPS.File (value))
      </example>
  </shell_doc>

  <shell_doc name="GPS.XMLViewer.create_metric">
     <param name="self">An instance of GPS.XMLViewer</param>
     <param name="name">A string</param>
     <description>Create a new XMLViewer for an XML file generated by gnatmetric.
Name is used as the name for the window</description>
  </shell_doc>

  <shell_doc name="GPS.XMLViewer.parse">
     <param name="self">An instance of GPS.XMLViewer</param>
     <param name="filename">An XML file</param>
     <description>Replace the contents of self by that of the XML file</description>
  </shell_doc>

  <shell_doc name="GPS.XMLViewer.parse_string">
     <param name="self">An instance of GPS.XMLViewer</param>
     <param name="str">A string</param>
     <description>Replace the contents of self by that of the XML string</description>
  </shell_doc>

  <!--#################################################################
      ## Logger class
      #################################################################-->

  <shell_doc name="GPS.Logger">
     <description>This class provides an interface to the GPS logging mechanism. This can be used when debugging scripts, or even be left in production scripts for post-mortem analysis for instance. All output through this class is done in the GPS log file, in $HOME/.gps/log.
GPS comes with some predefined logging streams, which can be used to configure the format of the log file, such as whether colors should be used, whether timestamps should be logged with each message,...</description>
  </shell_doc>

  <shell_doc name="GPS.Logger.__init__">
     <param name="self">An instance of GPS.Logger</param>
     <param name="name">A string</param>
     <description>Create a new logging stream. Each stream is associated with a name, which is displayed before each line in the GPS log file, and is used to distinguish between various parts of GPS. Calling this constructor with the same name multiple times will create a new class instance.</description>
     <example language="python">
         log = GPS.Logger ("my_script")
         log.log ("A message")
     </example>
  </shell_doc>

  <shell_doc name="GPS.Logger.log">
     <param name="self">An instance of GPS.Logger</param>
     <param name="message">A string</param>
     <description>Logs a message in the GPS log file</description>
  </shell_doc>

  <shell_doc name="GPS.Logger.set_active">
     <param name="self">An instance of GPS.Logger</param>
     <param name="active">A boolean</param>
     <description>Activate or deactivate a logging stream. The default for a sttream depends on the file $HOME/.gps/traces.cfg, and will generally be active. When a stream is inactive, no message is sent to the log file</description>
  </shell_doc>

  <shell_doc name="GPS.Logger.check">
     <param name="self">An instance of GPS.Logger</param>
     <param name="condition">A boolean</param>
     <param name="error_message">A string</param>
     <param name="success_message" default="">A string</param>
     <description>If condition evaluates to False, then error_message will be logged in the log file. If the condition evaluates to True, then success_message is logged if it was specified</description>
     <example language="python">
         log=GPS.Logger ("my_script")
         log.check (1 == 2, "Invalid addition")
     </example>
  </shell_doc>

  <!--#################################################################
      ## Bookmark class
      #################################################################-->

  <shell_doc name="GPS.Bookmark">
     <description>This class provides access to the bookmarks of GPS. These are special types of markers that are saved across sessions, and can be used to save a context within GPS. They are generally associated with a specific location in an editor, but can also be used to location special boxes in a graphical browser for instance. </description>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.__init__">
     <description>This function prevents the creation of a bookmark instance directly. You must use GPS.Bookmark.get() instead, which will always return the same instance for a given bookmark, thus allowing you to save your own custom data with the bookmark</description>
     <see_also name="GPS.Bookmark.get" />
  </shell_doc>

  <shell_doc name="GPS.Bookmark.create">
     <param name="name">A string</param>
     <return>An instance of GPS.Bookmark</return>
     <description>This function creates a new bookmark at the current location in GPS. If the current window is an editor, it creates a bookmark that will save the exact line and column, so that the user can go back to them easily. Name is the string that appears in the bookmarks window, and that can be used later to query the same instance using GPS.Bookmark.get. This function emits the hook bookmark_added</description>
     <see_also name="GPS.Bookmark.get" />
     <example lang="python">
         GPS.MDI.get ("file.adb").raise_window()
         bm = GPS.Bookmark.create ("name")
     </example>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.get">
     <param name="name">A string</param>
     <return>An instance of GPS.Bookmark</return>
     <description>This function retrieves a bookmark by its name. If no such bookmark exists, an exception is raised. The same instance of GPS.Bookmark is always return for a given bookmark, so that you can store your own user data within the instance. Note however that this custom data will not be automatically preserved across GPS sessions, so you might want to save all your data when GPS exits</description>
     <see_also name="GPS.Bookmark.create" />
     <example lang="python">
          GPS.Bookmark.get ("name").my_own_field = "GPS"
          print GPS.Bookmark.get ("name").my_own_field  ## prints "GPS"
     </example>
   </shell_doc>

   <shell_doc name="GPS.Bookmark.list">
      <return>A list of GPS.Bookmark instances</return>
      <description>Return the list of all existing bookmarks</description>
      <example lang="python">
          # The following command returns a list with the name of all
          # existing purposes
          names = [bm.name() for bm in GPS.Bookmark.list()]
     </example>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.name">
      <param name="self">An instance of GPS.Bookmark</param>
      <return>A string</return>
      <description>Return the current name of the bookmark. It might not be the same one that was used to create or get the bookmark, since the user might have used the bookmarks view to rename it</description>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.rename">
      <param name="self">An instance of GPS.Bookmark</param>
      <param name="name">A string</param>
      <description>Rename an existing bookmark. This updates the bookmarks view automatically, and emits the hooks bookmark_removed and bookmark_added</description>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.delete">
      <param name="self">An instance of GPS.Bookmark</param>
      <description>Delete an existing bookmark. This emits the hook bookmark_removed</description>
  </shell_doc>

  <shell_doc name="GPS.Bookmark.goto">
      <param name="self">An instance of GPS.Bookmark</param>
      <description>Change the current context in GPS so that it matches the one saved in the bookmark. In particular, if the bookmark is inside an editor, this editor is raised, and the cursor moved to the correct line and column. You cannot query directly the line and column from the bookmark, since these might not exist, for instance when the editor points inside a browser.</description>
  </shell_doc>

  <!--################################################################
      ## CommandWindow class
      ################################################################-->

  <shell_doc name="GPS.CommandWindow">
     <description>This class gives access to a command-line window that pops up on the screen. This window is short-lived (in fact there can be only one such window at any given time), and any key press is redirected to that window. As a result, it should be used to interactively query a parameter for an action, for instance.
Among other things, it is used in the implementation of the interactive search facility, where each key pressed should be added to the search pattern instead of to the editor.</description>
      <example lang="python">
   class Isearch (CommandWindow):
      def __init__ (self):
         CommandWindow.__init__ \
           (self, prompt="Pattern",
            on_key = self.on_key,
            on_changed = self.on_changed)

      def on_key (self, input, key, cursor_pos):
         if key == "control-w":
            .... # Copy current word from editor into the window
            self.write (input [:cursor_pos + 1] + "FOO" + input [cursor_pos + 1:])
            return True  ## No further processing needed
         return False

      def on_changed (self, input, cursor_pos):
         ## Search for next occurrence of input in buffer
         ....
      </example>
  </shell_doc>

  <shell_doc name="GPS.CommandWindow.__init__">
     <param name="self">The instance of GPS.CommandWindow we are creating</param>
     <param name="prompt" default="">A string</param>
     <param name="global_window" default="False">A boolean</param>
     <param name="on_changed" default="null">A subprogram</param>
     <param name="on_activate" default="null">A subprogram</param>
     <param name="on_cancel" default="null">A subprogram</param>
     <param name="on_key" default="null">A subprogram</param>
     <param name="close_on_activate" default="True">A boolean</param>
     <description>This function initializes an instance of a command window. An exception is raised if such a window is already active in GPS. Otherwise, the new window is popped up on the screen. Its location depends on the global_window parameter: if true, the command window is displayed at the bottom of the GPS window and occupies its whole width. If false, it is displayed at the bottom of the currently selected window.
The prompt is the short string displayed just before the command line itself. Its goal is to indicate to the user what he is entering.
The last four parameters are callbacks:
   - on_changed is called when the user has entered one or more new characters in the command line. This function is given two parameters: the current input string, and the last cursor position in this string. See the example above on how to get the part of the input before and after the cursor.
   - on_activate is called when the user has pressed enter. The command window has already been closed at that point if close_on_activate is True, and the focus given back to the initial MDI window that had it. This callback is given a single parameter, the final input string
   - on_cancel is called when the user has pressed a key that closed the dialog, for instance Esc. It is given a single parameter, the final input string. This callback is also called when you explicitly destroy the window yourself by calling self.destroy().
   - on_key is called when the user has pressed a new key on his keyboard, but before the corresponding character has been added to the command line. This can be used to filter out some characters, or provide special behavior for some key combination (see the example above). It is given three parameters, the current input string, the key that was pressed, and the current cursor position.</description>
   </shell_doc>

  <shell_doc name="GPS.CommandWindow.write">
      <param name="self">An instance of GPS.CommandWindow</param>
      <param name="text">A string</param>
      <param name="cursor" default="-1">An integer</param>
      <description>This function replaces the current content of the command line. As a result, you should make sure to preserve the character you want, as in the on_key callback in the example above. Calling this function will also result in several calls to the on_changed callback, one of them with an empty string (since gtk first deletes the contents and then writes the new contents.
The cursor parameter can be used to specify where the cursor should be left after the insertion. -1 indicates the end of the string.</description>
  </shell_doc>

  <shell_doc name="GPS.CommandWindow.read">
      <param name="self">An instance of GPS.CommandWindow</param>
      <return>A string</return>
      <description>This function returns the current contents of the command window</description>
  </shell_doc>

  <shell_doc name="GPS.CommandWindow.set_background">
      <param name="self">An instance of GPS.CommandWindow</param>
      <param name="color" default="">A string</param>
      <description>Change the background color of the command window. In most cases, this can be used to make the command window more obvious, or to point out errors by changing the color. If the color parameter is not specified, the color reverts to its default</description>
  </shell_doc>

  <shell_doc name="GPS.CommandWindow.set_prompt">
      <param name="self">An instance of GPS.CommandWindow</param>
      <param name="prompt">A string</param>
      <description>Changes the prompt that is displayed before the text field</description>
  </shell_doc>

  <!--#################################################################
      ## Clipboard class
      #################################################################-->

  <shell_doc name="GPS.Clipboard">
     <description>This class provides an interface to the GPS clipboard. This clipboard contains the previous selections that were copied or cut from a text editor. Several older selections are
also saved so that they can be pasted later on</description>
  </shell_doc>

  <shell_doc name="GPS.Clipboard.copy">
       <param name="text">A string</param>
       <param name="append" default="False">A boolean</param>
       <description>Copies a given static text into the clipboard. It is better in general to use GPS.EditorBuffer.copy, but it might happen that you need to append text that doesn't exist in the buffer.</description>
       <see_also name="GPS.EditorBuffer.copy" />
  </shell_doc>

  <shell_doc name="GPS.Clipboard.merge">
       <param name="index1">A null or positive integer</param>
       <param name="index2">A null or positive integer</param>
       <description>This function merges two levels of the clipboard, so that the one at index index1 now contains the concatenation of both. The one at index2 is removed.</description>
  </shell_doc>

  <shell_doc name="GPS.Clipboard.contents">
       <return>A list of strings</return>
       <description>This function returns the contents of the clipboard. Each item in the list corresponds to a past selection, the one at position 0 being the most recent. If you want to paste text in a buffer, you should paste the text at position GPS.Clipboard.current rather than the first in the list</description>
  </shell_doc>

  <shell_doc name="GPS.Clipboard.current">
       <return>An integer</return>
       <description>This function returns the index, in GPS.Clipboard.contents(), of the text that was last pasted by the user. If you were to select the menu /Edit/Paste, that would be the text pasted by GPS. If you select /Edit/Paste Previous, current will be incremented by 1, and the next selection in the clipboard will be pasted</description>
  </shell_doc>

  <!--#################################################################
      ## Vdiff class
      #################################################################-->

  <shell_doc name="GPS.Vdiff">
     <description>This class provides access to the graphical comparison between two or three files or two versions of the same file within GPS. A visual diff is a group of two or three editors with synchronized scrolling. Differences are rendered using blank lines and color highlighting.</description>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.__init__">
     <description>This function prevents the creation of a visual diff instance directly. You must use GPS.Vdiff.create() or GPS.Vdiff.get() instead.</description>
     <see_also name="GPS.Vdiff.create" />
     <see_also name="GPS.Vdiff.get" />
  </shell_doc>

  <shell_doc name="GPS.Vdiff.close_editors">
     <param name="self">An instance of GPS.Vdiff</param>
     <description>Close all editors implied in a visual diff.</description>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.create">
     <param name="file1">An instance of GPS.File</param>
     <param name="file2">An instance of GPS.File</param>
     <param name="file3" default="">An instance of GPS.File</param>
     <return>An instance of GPS.Vdiff</return>
     <description>If none of the files given as parameter is already used in a visual diff, this function creates a new visual diff and returns it. Otherwise, None is returned.</description>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.files">
     <param name="self">An instance of GPS.Vdiff</param>
     <return>A list of GPS.File</return>
     <description>Return the list of files used in a visual diff.</description>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.get">
     <param name="file1">An instance of GPS.File</param>
     <param name="file2" default="">An instance of GPS.File</param>
     <param name="file3" default="">An instance of GPS.File</param>
     <description>Return an instance of an already exisiting visual diff. If an instance already exists for this visual diff, it is returned. All files passed as parameters have to be part of the visual diff but not all files of the visual diff have to be passed for the visual diff to be returned. For example if only one file is passed the visual diff that contains it, if any, will be returned no matter it is a two or three files visual diff.</description>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.list">
     <return>A list GPS.Vdiff</return>
     <description>This function returns the list of visual diff currently opened in GPS.</description>
     <example lang="python">
         # Here is an example that demonstrates how to use GPS.Vdiff.list to
         # close all the visual diff.

         # First two visual diff are created
         vdiff1 = GPS.Vdiff.create (GPS.File ("a.adb"), GPS.File ("b.adb"))
         vdiff2 = GPS.Vdiff.create (GPS.File ("a.adb"), GPS.File ("b.adb"))

         # Then we get the list of all current visual diff
         vdiff_list = GPS.Vdiff.list ()

         # And we iterate on that list in order to close all editors used in
         # each visual diff from the list.
         for vdiff in vdiff_list:
            files = vdiff.files ()

            # But before each visual diff is actually closed, we just inform
            #  the user of the files that will be closed.
            for file in files:
               print "Beware! " + file.name () + "will be closed."

            # Finally, we close the visual diff
            vdiff.close_editors ()
     </example>
  </shell_doc>

  <shell_doc name="GPS.Vdiff.recompute">
     <param name="self">An instance of GPS.Vdiff</param>
     <description>Recompute a visual diff. The content of each editor used in the visual diff is saved. The files are recompared and the display is redone (blank lines and color highlighting).</description>
  </shell_doc>

  <!--#################################################################
      ## Action
      #################################################################-->

  <shell_doc name="GPS.Action">
     <description>This class gives access to the interactive commands in GPS. These are the commands to which the user can bind a key shortcut, or for which we can create a menu. Another way to manipulate those commands is through the XML tag &lt;action&gt;, but it might be more convenient to use python since you do not have to qualify the function name as a result</description>
  </shell_doc>

  <shell_doc name="GPS.Action.__init__">
     <param name='self'>An instance of GPS.Action</param>
     <param name='name'>A string</param>
     <description>Creates a new instance of Action. This is bound with either an existing action, or with an action that will be created through GPS.Action.create(). The name of the action can either be a simple name, or a path name to reference a menu, as in /Edit/Copy for instance</description>
  </shell_doc>

  <shell_doc name="GPS.Action.create">
     <param name="self">An instance of GPS.Action</param>
     <param name="on_activate">A subprogram</param>
     <param name="filter" default="">A string or subprogram</param>
     <param name="category" default="General">A string</param>
     <param name="description" default="">A string</param>
     <description>Export the function on_activate and make it interactive so that users can bind keys and menus to it. The function should not require any argument, since it will be called with none.
filter is either the name of a predefined filter (a string), or a subprogram that receives the context as a parameter, and should return True if the command can be executed within that context. This is used to disable menu items when they are not available.
category is the category of the command in the /Edit/Key Shortcuts dialog.
description is the description of the command that appears in that dialog. If you are using python, a convenient value is on_activate.__doc__, which avoids duplicating the comment.
The package gps_utils.py provides a somewhat more convenient python interface to make function interactives (see gps_utils.interactive).</description>
  </shell_doc>

  <shell_doc name="GPS.Action.key">
     <param name="self">An instance of GPS.Action</param>
     <param name="key">A string</param>
     <description>Associate a default key binding with the action. This will be ignored if the user has defined his own key binding. Possible values for key can be experimented with by using the /Edit/Key Shortcuts dialog</description>
  </shell_doc>

  <shell_doc name="GPS.Action.menu">
     <param name="self">An instance of GPS.Action</param>
     <param name="path">A string</param>
     <param name="ref" default="">A string</param>
     <param name="add_before" default="True">A boolean</param>
     <description>Create a new menu associated with the command. This function is somewhat a duplicate of GPS.Menu.create, but with one major difference: the callback for the action is a python function that takes no argument, whereas the callback for GPS.Menu receives one argument</description>
  </shell_doc>

  <shell_doc name="GPS.Action.contextual">
     <param name="self">An instance of GPS.Action</param>
     <param name="path">A string</param>
     <param name="ref" default="">A string</param>
     <param name="add_before" default="True">A boolean</param>
     <description>Create a new contextual menu associated with the command. This function is somewhat a duplicate of GPS.Contextual.create, but with one major difference: the callback for the action is a python function that takes no argument, whereas the callback for GPS.Contextual receives one argument</description>
  </shell_doc>

  <!--#################################################################
      ## Exceptions
      #################################################################-->

  <shell_doc name="GPS.Exception">
     <description>One of the exceptions that can be raised by GPS. It is a general error message, and its semantic depends on what subprogram raised the exception.</description>
  </shell_doc>

  <shell_doc name="GPS.Invalid_Argument">
     <description>An exception raised by GPS. Raised when calling a subprogram from the GPS module with an invalid argument type (passing an integer when a string is expected, for instance)</description>
  </shell_doc>

  <shell_doc name="GPS.Missing_Arguments">
     <description>An exception raised by GPS. Raised when calling a subprogram from the GPS module with missing arguments</description>
  </shell_doc>

  <shell_doc name="GPS.Unexpected_Exception">
     <description>An exception raised by GPS. It indicates an internal error in GPS, raised by the Ada code itself. This exception is unexpected and indicates a bug in GPS itself, not in the python script, although it might be possible to modify the latter to work around the issue</description>
  </shell_doc>

  <!--#################################################################
      ## BuildTarget class
      #################################################################-->

  <shell_doc name="GPS.BuildTarget">
     <description>This class provides an interface to the GPS build targets. Build targets can be configured through XML or through the Target Configuration dialog.</description>
  </shell_doc>

  <shell_doc name="GPS.BuildTarget.__init__">
      <param name="self">The instance being constructed</param>
      <param name="name">Name of the target associated with this instance</param>
      <description>Initializes a new instance of the class BuildTarget. Name must correspond to an existing target.</description>
      <example lang="python">
         compile_file_target=GPS.BuildTarget("Compile File")
         compile_file_target.execute()
      </example>
  </shell_doc>

  <shell_doc name="GPS.BuildTarget.execute">
       <param name="self">An instance of BuildTarget</param>
       <param name="main_name" default="">A String</param>
       <param name="file" default="">A GPS.File</param>
       <param name="force" default="False">A Boolean</param>
       <param name="extra_args" default="">A String</param>
       <param name="build_mode" default="">A String</param>
       <param name="synchronous" default="True">A Boolean</param>
       <param name="directory" default="">A String</param>
       <description>Launch the build target:
      - main_name indicates the base name of the main source to build, if this target acts on a main file.
      - file indicates the file to build if this targets acts on a file.
      - if force is True, this means that the target should be launched directly, even if its parameters indicate that it should be launched through an intermediary dialog.
      - extra_args contains any extra parameters to pass to the command line.
      - build_mode indicates build mode to be used for build.
      - if synchronous is False, build target is launched asynchronously. execution_finished hook will be called when build target execution is completed. </description>
      - if directory is not "", the target will be executed under directory.
  </shell_doc>

  <shell_doc name="GPS.BuildTarget.remove">
       <param name="self">An instance of BuildTarget</param>
       <description>Remove target from the list of known targets.
       Any graphical element corresponding to this target is also removed.</description>
  </shell_doc>

  <shell_doc name="GPS.BuildTarget.clone">
       <param name="self">An instance of BuildTarget</param>
       <param name="new_name">The name of the new target</param>
       <param name="new_category">The category in which to place the new target</param>
       <description>Clone the target to a new target. All the properties of the new target are copied from the target.
       Any graphical element corresponding to this new target is created.</description>
  </shell_doc>


  <!--#################################################################
      ## Task class
      #################################################################-->

  <shell_doc name="GPS.Task">
     <description>This class provides an interface to the background tasks being handled by GPS, such as the
      build commands, the query of cross references, etc. These are the same tasks that are visible through the
      GPS Task Manager.
      Note that the classes represented with this class cannot be stored.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Task.list">
       <description>Return a list of all running tasks</description>
  </shell_doc>

  <shell_doc name="GPS.Task.interrupt">
       <param name="self">An instance of Task</param>
       <description>Interrupt the task</description>
  </shell_doc>

  <shell_doc name="GPS.Task.pause">
       <param name="self">An instance of Task</param>
       <description>Pause the task</description>
  </shell_doc>

  <shell_doc name="GPS.Task.resume">
       <param name="self">An instance of Task</param>
       <description>Resume the paused task</description>
  </shell_doc>

  <shell_doc name="GPS.Task.name">
       <param name="self">An instance of Task</param>
       <return>A string</return>
       <description>Return the name of the task</description>
  </shell_doc>

  <shell_doc name="GPS.Task.status">
       <param name="self">An instance of Task</param>
       <return>A string</return>
       <description>Return the status of the task</description>
  </shell_doc>


  <!--#################################################################
      ## EditorHighlighter class
      #################################################################-->

  <shell_doc name="GPS.EditorHighlighter">
     <description>This class can be used to transform source editor text into
     hyperlinks when the Control key is pressed.
     Two actions can then be associated with this hyperlink: clicking with
     the left mouse button on the hyperlink triggers the primary action, and
     clicking with the middle mouse button on the hyperlink triggers the
     alternate action.
     </description>
  </shell_doc>

  <shell_doc name="GPS.EditorHighlighter.__init__">
     <param name="self">An instance of EditorHighlighter</param>
     <param name="pattern">A regular expression representing the patterns on
     which we want to create hyperlinks.</param>
     <param name="action">The primary action for this hyperlink</param>
     <param name="index" default="0">This indicate the number of the
     parenthesized group in pattern that needs to be highlighted.</param>
     <param name="secondary_action" default="null">The alternate action for this hyperlink</param>

     <description>Register a highlighter. The action is a Python function that
     takes a string as a parameter: the string being passed is the section of
     text which is highlighted.
     </description>

     <example lang="python">
     # Define an action
     def view_html(url):
         GPS.HTML.browse (url)

     def wget_url(url):
         def on_exit_cb(self, code, output):
             GPS.Editor.edit (GPS.dump (output))
         p=GPS.Process("wget %s -O -" % url, on_exit=on_exit_cb)

     # Register a highlighter to launch a browser on any URL
     #  left-clicking on an URL will open the default browser to this URL
     #  middle-clicking will call "wget" to get the source of this URL and
     #    open the output in a new editor

     h=GPS.EditorHighlighter ("http(s)?://[^\s:,]*", view_html, 0, wget_url)

     # Remove the highlighter
     h.remove()

     </example>
  </shell_doc>

  <shell_doc name="GPS.EditorHighlighter.remove">
     <param name="self">An instance of EditorHighlighter</param>
     <description>Unregister the highlighter. This cannot be called while the
      hyper-mode is active.
     </description>
  </shell_doc>

    <!--#################################################################
      ## Message class
      #################################################################-->

  <shell_doc name="GPS.Message">
     <description>This class is used to manipulate GPS messages: build errors,
     editor annotations, etc.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Message.__init__">
      <param name="self">An instance of Message</param>
      <param name="category">A String indicating the message category</param>
      <param name="file">A File indicating the file</param>
      <param name="line">An integer indicating the line</param>
      <param name="column">An integer indicating the column</param>
      <param name="text">A pango markup String containg the message text</param>
      <param name="flags">An integer representing the location of the message</param>

      <description>Add a Message in GPS.</description>


     <example lang="python">
     # Create a message

     m=GPS.Message ("default", GPS.File("gps-main.adb"), 1841, 20, "test message", 0)

     # Remove the message
     m.remove()

     </example>
  </shell_doc>

  <shell_doc name="GPS.Message.__del__">
      <description>Destroy the Message instance.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.list">
     <param name="file">(optional) a GPS File. Specifying this parameter
     restricts the output to messages for this file only.</param>
     <param name="category">(optional) a String. Specifying this parameter
     restricts the output to messages for this category only</param>
     <description>Return a list of all messages currently stored in GPS.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_category">
     <description>Return the message's category.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_flags">
     <description>Return an integer which represents the location of the
      message
     </description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_file">
     <description>Return the message's file.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_line">
     <description>Return the message's line.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_column">
     <description>Return the message's column.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_mark">
     <description>Return an EditorMark which was created with the message and
     keeps track of the location when the file is edited.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.get_text">
     <description>Return the message's text.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.remove">
     <description>Remove the message from GPS.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.execute_action">
     <description>If the message has an associated action, execute it.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Message.set_style">
     <param>An instance of Style</param>
     <param>An Integer</param>
     <description>Set the style of the message. The second parameter indicates
     the length in number of characters to highlight. If 0, then highlight the
     whole line. If left out, this means the length of the message highlighting
     is not modified.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.set_action">
     <param name="action">A String corresponding to a registered GPS action.
     </param>
     <param name="image">A String corresponding to the id of a registered GPS
     image. See icons.xml for an example of how to register icons in GPS.
     </param>
     <param name="tooltip">A string (optional) which contains the tooltip to
     display when the mouse is on the icon.</param>
     <description>Add an action item to the message. This will add an icon to
     the message, and clicking on this icon will execute action.</description>
  </shell_doc>

  <shell_doc name="GPS.Message.set_subprogram">
     <param name="subprogram">A subprogram in the scripting language.
     This subprogram takes as a parameter one message.
     </param>
     <param name="image">A String corresponding to the id of a registered GPS
     image. See icons.xml for an example of how to register icons in GPS.
     </param>
     <param name="tooltip">A string (optional) which contains the tooltip to
     display when the mouse is on the icon.</param>
     <description>Add an action item to the message. This will add an icon to
     the message, and clicking on this icon will execute the subprogram, with
     the messaged passed as parameter of the subprogram.</description>

     <example lang="python">
     # This adds a "close" button to all the messages
     [msg.set_subprogram (lambda m : m.remove(), "gtk-close", "") for msg in GPS.Message.list()]
     </example>
  </shell_doc>

    <!--#################################################################
      ## Style class
      #################################################################-->

  <shell_doc name="GPS.Style">
     <description>This class is used to manipulate GPS Styles, which are used
     for instance to represent graphical attributes given to Messages.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Style.__init__">
      <param name="self">An instance of Style</param>
      <param name="name">A String indicating the name of the Style</param>
      <param name="create">A File indicating the file</param>

      <description>Create a Style</description>

      <example lang="python">
         # Create a new style
         s=GPS.Style("my new style")

         # Set the background color to yellow
         s.set_background ("#ffff00")

         # Apply the style to all the messages
         [m.set_style(s) for m in GPS.Message.list()]
      </example>
  </shell_doc>

  <shell_doc name="GPS.Style.list">
     <description>Return a list of all styles currently registered in GPS.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Style.get_name">
     <description>Return the name of the style.</description>
  </shell_doc>

  <shell_doc name="GPS.Style.get_background">
     <description>Return a String describing the background of the style.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Style.get_foreground">
     <description>Return a String describing the foreground of the style.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Style.get_in_speedbar">
     <description>Return a Boolean indicating whether this style is shown in
     the speedbar.
     </description>
  </shell_doc>

  <shell_doc name="GPS.Style.set_background">
      <param>A string representing a color, for instance "blue" or "#0000ff"
      </param>
     <description>Set the background of style to the given color.</description>
  </shell_doc>

  <shell_doc name="GPS.Style.set_foreground">
      <param>A string representing a color, for instance "blue" or "#0000ff"
      </param>
     <description>Set the foreground of style to the given color.</description>
  </shell_doc>

  <shell_doc name="GPS.Style.set_in_speedbar">
     <param>A Boolean</param>
     <description>Whether this style should appear in the speedbar.
     </description>
  </shell_doc>

    <!--#################################################################
      ## Project Templates
      #################################################################-->

  <shell_doc name="GPS.ProjectTemplate">
     <description>This class is used to manipulate GPS Project Templates.
     </description>
  </shell_doc>

  <shell_doc name="GPS.ProjectTemplate.add_templates_dir">
     <param>A GPS.File pointing to a directory.</param>
     <description>Add a directory to the path in which GPS looks for templates.
     GPS will look for project templates in immediate subdirectories of this
     directory.</description>
  </shell_doc>
</docs>