/usr/share/doc/gnat-gps/html/The-Python-Interpreter.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 2002-2010 AdaCore.

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

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

You should have received a copy of the GNU General Public License along
with this program; if not, see http://www.gnu.org/licenses/.

A copy of the license is included in the section entitled
"GNU General Public License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNAT Programming Studio: The Python Interpreter</title>

<meta name="description" content="Using the GNAT Programming Studio: The Python Interpreter">
<meta name="keywords" content="Using the GNAT Programming Studio: The Python Interpreter">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-table.html#Index-table" rel="index" title="Index table">
<link href="Scripting-GPS.html#Scripting-GPS" rel="up" title="Scripting GPS">
<link href="Subprogram-parameters.html#Subprogram-parameters" rel="next" title="Subprogram parameters">
<link href="The-GPS-Shell.html#The-GPS-Shell" rel="previous" title="The GPS Shell">
<style type="text/css">
<!--
   

a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    

-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="The-Python-Interpreter"></a>
<div class="header">
<p>
Next: <a href="Subprogram-parameters.html#Subprogram-parameters" accesskey="n" rel="next">Subprogram parameters</a>, Previous: <a href="The-GPS-Shell.html#The-GPS-Shell" accesskey="p" rel="previous">The GPS Shell</a>, Up: <a href="Scripting-GPS.html#Scripting-GPS" accesskey="u" rel="up">Scripting GPS</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="The-Python-Interpreter-1"></a>
<h4 class="subsection">16.8.4 The Python Interpreter</h4>
<a name="index-python-1"></a>

<p>Python is an interpreted object-oriented language, created by Guido
Van Rossum. It is similar in its capabilities to languages such as
Perl, Tcl or Lisp. This section is not a tutorial on python
programming. See <a href="http://docs.python.org/">http://docs.python.org/</a> to access the
documentation for the current version of python.
</p>
<p>If python support has been enabled, the python shell is accessible through the
<code>Python</code> window at the bottom of the GPS window. You can also
display it by using the menu <samp>Tools-&gt;Consoles-&gt;Python</samp>.
</p>
<p>The full documentation on what GPS makes visible through python is available
through the <code>/Help/Python extensions</code>.
</p>
<p>The same example that was used to show the GPS shell follows, now using
python. As you can notice, the name of the commands is
similar, although they are not run exactly in the same
way. Specifically, GPS benefits from the object-oriented aspects of
python to create classes and instances of these classes.
</p>
<p>In the first line, a new instance of the class Entity is created
through the <code>create_entity</code> function. Various methods can then be
applied to that instance, including <code>find_all_refs</code>, which lists
all references to that entity in the location window:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; e=GPS.Entity (&quot;entity_name&quot;, &quot;file_name.adb&quot;)
&gt;&gt;&gt; e.find_all_refs()
</pre></div>

<p>The screen representation of the classes exported by GPS to python has
been modified, so that most GPS functions will return an instance of a
class, but still display their output in a user-readable manner.
</p>
<p>Python has extensive introspection capabilities. Continuing the
previous example, you can find what class <code>e</code> is an instance of
with the following command:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; help(e)
Help on instance of Entity:

&lt;GPS.Entity instance&gt;
</pre></div>

<p>It is also possible to find all attributes and methods that can be
applied to <code>e</code>, as in the following example:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; dir (e)
['__doc__', '__gps_data__', '__module__', 'called_by', 'calls',
'find_all_refs']
</pre></div>

<p>Note that the list of methods may vary depending on what modules were
loaded in GPS, since each module can add its own methods to any class.
</p>
<p>In addition, the list of all existing modules and objects currently known
in the interpreter can be found with the following command:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; dir ()
['GPS', 'GPSStdout', '__builtins__', '__doc__', '__name__', 'e', 'sys']
</pre></div>

<p>You can also load and execute python scripts with the <code>execfile</code> command,
as in the following example:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; execfile (&quot;test.py&quot;)
</pre></div>

<p>Python supports named parameters. Most functions exported by GPS define
names for their parameters, so that you can use this Python feature, and
make your scripts more readable. A notable exception to this rule are the
functions that take a variable number of parameters.
Using named parameters allows you to specify the parameters in any order
you wish, e.g:
</p>
<div class="smallexample">
<pre class="smallexample">&gt;&gt;&gt; e=GPS.Entity (name=&quot;foo&quot;, file=&quot;file.adb&quot;)
</pre></div>

<a name="Python-modules"></a>
<h4 class="subsection">16.8.5 Python modules</h4>

<p>On startup, GPS will automatically import (with python&rsquo;s <code>import</code>
command) all the files with the extension <samp>.py</samp> found in the directory
<samp>$HOME/.gps/plug-ins</samp>, the directory <samp>$prefix/share/gps/plug-ins</samp>
 or in the directories pointed to by
<samp>GPS_CUSTOM_PATH</samp>. These files are loaded only after all standard
GPS modules have been loaded, as well as the custom files, and before
the script file or batch commands specified on the command lines with
the <code>--eval</code> or <code>--load</code> switches.
</p>
<p>As a result, one can use the usual GPS functions exported to python in these
startup scripts. Likewise, the script run from the command line can use
functions defined in the startup files.
</p>
<p>Since the <code>import</code> command is used, the functions defined in this
modules will only be accessible by prefixing their name by the name of the
file in which they are defined. For instance if a file <samp>mystartup.py</samp>
is copied to the startup directory, and defines the function <code>func</code>,
then the latter will be accessible in GPS through <code>mystartup.func</code>.
</p>
<p>Python&rsquo;s own mechanism for loading files at startup (the environment
variable <code>PYTHONSTARTUP</code>) is not suitable for use within the context
of GPS. When python is loaded by GPS, the GPS module itself is not yet
available, and thus any script that depends on that module will fail to
load correctly. Instead, copy your script to one of the plug-ins directories,
as documented above.
</p>
<p>If you are writing a set of python scripts that other people will use,
you need to provide several things:
</p>
<ul>
<li> The python files themselves. This is a set of <samp>.py</samp> files, which
 the user should install in the <samp>plug-ins</samp> directory.

</li><li> Optionally: an XML file with the format described in the customization section
 of this documentation. This XML file should create a set of actions,
 through the <code>&lt;action&gt;</code> tag, exported to the user. This allows him
 to either create menus to execute these commands or to bind them to special
 key shortcuts. The menus can be created directly in python, with the
 <code>GPS.Menu</code> class. The same XML can in fact be directly embedded in the
 python file itself and executed through <code>GPS.parse_xml</code>.
</li></ul>

<p>The following example defines a python command that inserts a line full of
dashes (&rsquo;-&rsquo;) at the current cursor location. This command is associated with
the key binding <tt class="key">control-c n</tt>, and can be distributed as a single XML
file.
</p>
<div class="smallexample">
<pre class="smallexample"># This code can be stored in a file test.py in $HOME/.gps/plug-ins
from GPS import *

def add_dashes_line():
   Editor.replace_text (current_context().file().name(),
                        current_context().location().line(),
                        current_context().location().column(),
                        &quot;--------------------------------&quot;, 0, 0)
GPS.parse_xml (&quot;&quot;&quot;
   &lt;action name=&quot;dashes line&quot;&gt;
      &lt;shell lang=&quot;python&quot;&gt;test.add_dashes_line()&lt;/shell&gt;
      &lt;context&gt;Source editor&lt;/context&gt;
   &lt;/action&gt;
   &lt;key action=&quot;dashes line&quot;&gt;control-c n&lt;/key&gt;
&quot;&quot;&quot;)

</pre></div>

<p>Several complex examples are provided in the GPS distribution, in the
directory <samp>examples/python</samp>. These are modules that you might want
to use for your own GPS, but more important that will show how GPS can
be extended from Python.
</p>
<p>If your script doesn&rsquo;t do what you expect it to do, there are several
ways to debug it, among which the easiest is probably to add some &quot;print&quot;
statements. Since some output of the scripts is sometimes hidden by GPS
(for instance for interactive commands), you might not see this output.
</p>
<p>In this case, you can reuse the tracing facility embedded in GPS itself.
Modify the file <samp>$HOME/.gps/traces.cfg</samp>, and add the following line:
</p>
<div class="smallexample">
<pre class="smallexample">PYTHON.OUT=yes
</pre></div>

<p>This will include the python traces as part of the general traces available
in the file <samp>$HOME/.gps/log</samp>. Note that it may slow down GPS if there is
a lot of output to process.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Subprogram-parameters.html#Subprogram-parameters" accesskey="n" rel="next">Subprogram parameters</a>, Previous: <a href="The-GPS-Shell.html#The-GPS-Shell" accesskey="p" rel="previous">The GPS Shell</a>, Up: <a href="Scripting-GPS.html#Scripting-GPS" accesskey="u" rel="up">Scripting GPS</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnat-gps-doc 5.0-16 / usr / share / doc / gnat-gps / html / The-Python-Interpreter.html
