/usr/share/doc/gnat-gps/html/The-Python-Interpreter.html is in gnat-gps-doc 5.0-6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 | <html lang="en">
<head>
<title>The Python Interpreter - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Scripting-GPS.html#Scripting-GPS" title="Scripting GPS">
<link rel="prev" href="The-GPS-Shell.html#The-GPS-Shell" title="The GPS Shell">
<link rel="next" href="Subprogram-parameters.html#Subprogram-parameters" title="Subprogram parameters">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.
This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
pre.smallexample {background-color:rgb(240,240,240);
font-family: courier new,courier,fixed;
font-size: 14px;
margin: 0px 40px 0px 40px;
border-width: 1px 2px 2px 1px;
border-top-style: dotted;
border-left-style: dotted;
border-right-style: solid;
border-bottom-style: solid;
border-color: black;}
code {color:black;
font-family: courier new,courier,fixed;
font-size: 14px;}
body {font-family: arial,helvetica,sans-serif;
font-size: 16px;
max-width: 800px;
text-align: justify}
samp {font-family: courier new,courier,fixed;
font-size: 14px}
--></style>
</head>
<body>
<div class="node">
<a name="The-Python-Interpreter"></a>
<p>
Next: <a rel="next" accesskey="n" href="Subprogram-parameters.html#Subprogram-parameters">Subprogram parameters</a>,
Previous: <a rel="previous" accesskey="p" href="The-GPS-Shell.html#The-GPS-Shell">The GPS Shell</a>,
Up: <a rel="up" accesskey="u" href="Scripting-GPS.html#Scripting-GPS">Scripting GPS</a>
<hr>
</div>
<h4 class="subsection">16.8.4 The Python Interpreter</h4>
<p><a name="index-python-895"></a><!-- -->
<p class="noindent">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>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><span class="file">Tools->Consoles->Python</span></samp>.
<p>The full documentation on what GPS makes visible through python is available
through the <code>/Help/Python extensions</code>.
<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>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:
<pre class="smallexample"> >>> e=GPS.Entity ("entity_name", "file_name.adb")
>>> e.find_all_refs()
</pre>
<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>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:
<pre class="smallexample"> >>> help(e)
Help on instance of Entity:
<GPS.Entity instance>
</pre>
<p>It is also possible to find all attributes and methods that can be
applied to <code>e</code>, as in the following example:
<pre class="smallexample"> >>> dir (e)
['__doc__', '__gps_data__', '__module__', 'called_by', 'calls',
'find_all_refs']
</pre>
<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>In addition, the list of all existing modules and objects currently known
in the interpreter can be found with the following command:
<pre class="smallexample"> >>> dir ()
['GPS', 'GPSStdout', '__builtins__', '__doc__', '__name__', 'e', 'sys']
</pre>
<p>You can also load and execute python scripts with the <code>execfile</code> command,
as in the following example:
<pre class="smallexample"> >>> execfile ("test.py")
</pre>
<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:
<pre class="smallexample"> >>> e=GPS.Entity (name="foo", file="file.adb")
</pre>
<h4 class="subsection">16.8.5 Python modules</h4>
<p>On startup, GPS will automatically import (with python's <code>import</code>
command) all the files with the extension <samp><span class="file">.py</span></samp> found in the directory
<samp><span class="file">$HOME/.gps/plug-ins</span></samp>, the directory <samp><span class="file">$prefix/share/gps/plug-ins</span></samp>
or in the directories pointed to by
<samp><span class="file">GPS_CUSTOM_PATH</span></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>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>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><span class="file">mystartup.py</span></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>Python'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>If you are writing a set of python scripts that other people will use,
you need to provide several things:
<ul>
<li>The python files themselves. This is a set of <samp><span class="file">.py</span></samp> files, which
the user should install in the <samp><span class="file">plug-ins</span></samp> directory.
<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><action></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>.
</ul>
<p>The following example defines a python command that inserts a line full of
dashes ('-') at the current cursor location. This command is associated with
the key binding <control-c n>, and can be distributed as a single XML
file.
<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(),
"--------------------------------", 0, 0)
GPS.parse_xml ("""
<action name="dashes line">
<shell lang="python">test.add_dashes_line()</shell>
<context>Source editor</context>
</action>
<key action="dashes line">control-c n</key>
""")
</pre>
<p>Several complex examples are provided in the GPS distribution, in the
directory <samp><span class="file">examples/python</span></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>If your script doesn't do what you expect it to do, there are several
ways to debug it, among which the easiest is probably to add some "print"
statements. Since some output of the scripts is sometimes hidden by GPS
(for instance for interactive commands), you might not see this output.
<p>In this case, you can reuse the tracing facility embedded in GPS itself.
Modify the file <samp><span class="file">$HOME/.gps/traces.cfg</span></samp>, and add the following line:
<pre class="smallexample"> PYTHON.OUT=yes
</pre>
<p>This will include the python traces as part of the general traces available
in the file <samp><span class="file">$HOME/.gps/log</span></samp>. Note that it may slow down GPS if there is
a lot of output to process.
<!-- -->
</body></html>
|