/[adonthell]/adonthell/src/python/python.h
ViewVC logotype

Diff of /adonthell/src/python/python.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.12 by ksterker, Mon Oct 25 06:50:09 2004 UTC revision 1.13 by ksterker, Tue Mar 8 09:41:48 2005 UTC
# Line 1  Line 1 
1  /*  /*
2     $Id$     $Id$
3    
4     Copyright (C) 2003/2004 Alexandre Courbot <alexandrecourbot@linuxgames.com>     Copyright (C) 2003/2004 Alexandre Courbot <alexandrecourbot@linuxgames.com>
5     Part of the Adonthell Project http://adonthell.linuxgames.com     Part of the Adonthell Project http://adonthell.linuxgames.com
6    
7     Adonthell is free software; you can redistribute it and/or modify     Adonthell is free software; you can redistribute it and/or modify
8     it under the terms of the GNU General Public License as published by     it under the terms of the GNU General Public License as published by
9     the Free Software Foundation; either version 2 of the License, or     the Free Software Foundation; either version 2 of the License, or
10     (at your option) any later version.     (at your option) any later version.
11    
12     Adonthell is distributed in the hope that it will be useful,     Adonthell is distributed in the hope that it will be useful,
13     but WITHOUT ANY WARRANTY; without even the implied warranty of     but WITHOUT ANY WARRANTY; without even the implied warranty of
14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15     GNU General Public License for more details.     GNU General Public License for more details.
16    
17     You should have received a copy of the GNU General Public License     You should have received a copy of the GNU General Public License
18     along with Adonthell; if not, write to the Free Software     along with Adonthell; if not, write to the Free Software
19     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20  */  */
21    
22    
23  /**  /**
24   * @file   python.h   * @file   python.h
25   * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>   * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
26   *   *
27   * @brief  The python module main include file.   * @brief  The python module main include file.
28   *   *
29   *   *
30   */   */
31    
32  #ifndef PYTHON_PYTHON_H_  #ifndef PYTHON_PYTHON_H_
33  #define PYTHON_PYTHON_H_  #define PYTHON_PYTHON_H_
34    
35  #include <Python.h>  #include <Python.h>
36  #include "base/flat.h"  #include "base/flat.h"
37    
38  struct swig_type_info;  struct swig_type_info;
39  extern "C" {  extern "C" {
40      swig_type_info *SWIG_Python_TypeQuery (const char*);      swig_type_info *SWIG_Python_TypeQuery (const char*);
41      int SWIG_Python_ConvertPtr (PyObject*, void**, swig_type_info*, int);      int SWIG_Python_ConvertPtr (PyObject*, void**, swig_type_info*, int);
42      PyObject *SWIG_Python_NewPointerObj (void*, swig_type_info*, int);      PyObject *SWIG_Python_NewPointerObj (void*, swig_type_info*, int);
43  }  }
44    
45  /**  /**
46   * Provides a bridge between C++ and Python,   * Provides a bridge between C++ and Python,
47   * as well as some convenience classes to ease   * as well as some convenience classes to ease
48   * the use of the Adonthell library from Python.   * the use of the Adonthell library from Python.
49   *   *
50   */   */
51  namespace python  namespace python
52  {  {
53      /**      /**
54       * Dump any error information to stderr.       * Dump any error information to stderr.
55       *       *
56       * This function should be called after every operation       * This function should be called after every operation
57       * involving Python from C++, so the user can get informed if       * involving Python from C++, so the user can get informed if
58       * something went wrong. By default, all the methods of this       * something went wrong. By default, all the methods of this
59       * module call it when appropriate.       * module call it when appropriate.
60       *       *
61       */       */
62      void show_traceback();      void show_traceback();
63    
64      /**      /**
65       * @name Initialization and cleanup.       * @name Initialization and cleanup.
66       *       *
67       */       */
68      //@{      //@{
69        /**
70      void init();       * Initialize the embedded Python interpreter.
71      void cleanup();       */
72        void init();
73      //@}  
74        /**
75      /**       * Shutdown the embedded Python interpreter.
76       * @name High-level functions.       */
77       *      void cleanup();
78       */      //@}
79      //@{  
80      /**      /**
81       * Add given path to Python's list of module directories.       * @name High-level functions.
82       * @param path the path to add.       *
83       * @return \b true on success, \b false otherwise.       */
84       */      //@{
85      bool add_search_path(const std::string & path);      /**
86         * Add given path to Python's list of module directories.
87      /**       * @param path the path to add.
88       * Execute a python statement and return resulting object.       * @return \b true on success, \b false otherwise.
89       * This is a new reference that needs to be Py_DECREF'd when done.       */
90       * @param statement Python code to execute.      bool add_search_path(const std::string & path);
91       * @param one of Py_eval_input, Py_file_input or Py_single_input  
92       * @return \b result on success, \b NULL otherwise.      /**
93       */       * Execute a python statement and return resulting object.
94      PyObject* run_string (const std::string & statement, const int & start = Py_eval_input);       * This is a new reference that needs to be Py_DECREF'd when done.
95             * @param statement Python code to execute.
96      /**       * @param start one of Py_eval_input, Py_file_input or Py_single_input
97       * Execute a python statement and return success.       * @return \b result on success, \b NULL otherwise.
98       * @param statement Python code to execute.       */
99       * @return \b true on success, \b false otherwise.      PyObject* run_string (const std::string & statement, const int & start = Py_eval_input);
100       */      
101      bool run_simple_string (const std::string & statement);      /**
102         * Execute a python statement and return success.
103      PyObject * import_module(const std::string & name);       * @param statement Python code to execute.
104         * @return \b true on success, \b false otherwise.
105      //@}       */
106        bool run_simple_string (const std::string & statement);
107      /**  
108       * @name C++ to Python instance passing functions.      /**
109       *       * Import %python module with given name.
110       */       * @param name name of module to import
111      //@{       * @return imported module or \c NULL on error.
112         */
113      /**      PyObject * import_module(const std::string & name);
114       * Ownership of a python object made with pass_instance. Value  
115       * python::c_owns means that once the Python object is deleted, the      //@}
116       * C++ instance will remain valid. On the contrary, python::python_owns  
117       * will cause the C++ instance to be destroyed when the Python object is      /**
118       * deleted.       * @name C++ to Python instance passing functions.
119       *       *
120       */       */
121      typedef enum { c_owns = 0, python_owns = 1 } ownership;      //@{
122    
123      /**      /**
124       * Default version of pass_instance - it will fetch the name of the class       * Ownership of a python object made with pass_instance. Value
125       * that is passed using a specialized version of get_type_name to create       * python::c_owns means that once the Python object is deleted, the
126       * a Python object from a pointer.       * C++ instance will remain valid. On the contrary, python::python_owns
127       *       * will cause the C++ instance to be destroyed when the Python object is
128       * @param arg a pointer to the object to pass to Python.       * deleted.
129       * @param own ownership of the C++ object.       *
130       *       */
131       * @return a Python object representing \e arg.      typedef enum { c_owns = 0, python_owns = 1 } ownership;
132       */  
133      template <class A> inline      /**
134      PyObject * pass_instance(A arg, const ownership own = c_owns)       * Default version of pass_instance - it will fetch the name of the class
135      {       * that is passed using a specialized version of get_type_name to create
136          swig_type_info * tt = SWIG_Python_TypeQuery (arg->get_type_name ());       * a Python object from a pointer.
137          if (tt) return SWIG_Python_NewPointerObj(arg, tt, own);       *
138                 * @param arg a pointer to the object to pass to Python.
139          fprintf (stderr, "*** pass_instance: type '%s' unknown to SWIG\n", arg->get_type_name ());       * @param own ownership of the C++ object.
140          return NULL;       *
141      }       * @return a Python object representing \e arg.
142             */
143      /**      template <class A> inline
144       * Specialized version of pass_instance which makes a Python integer      PyObject * pass_instance(A arg, const ownership own = c_owns)
145       * from a C++ one.      {
146       *          swig_type_info * tt = SWIG_Python_TypeQuery (arg->get_type_name ());
147       * @param arg the integer to be passed to Python.          if (tt) return SWIG_Python_NewPointerObj(arg, tt, own);
148       * @param own useless here.          
149       *          fprintf (stderr, "*** pass_instance: type '%s' unknown to SWIG\n", arg->get_type_name ());
150       * @return a Python object representing \e arg.          return NULL;
151       */      }
152      template <> inline      
153      PyObject * pass_instance<int>(int arg, const ownership own)      /**
154      {       * Specialized version of pass_instance which makes a Python integer
155          return PyInt_FromLong(arg);       * from a C++ one.
156          show_traceback();       *
157      }       * @param arg the integer to be passed to Python.
158         * @param own useless here.
159      /**       *
160       * Specialized version of pass_instance which makes a Python boolean       * @return a Python object representing \e arg.
161       * from a C++ one.       */
162       *      template <> inline
163       * @param arg the boolean to be passed to Python.      PyObject * pass_instance<int>(int arg, const ownership own)
164       * @param own useless here.      {
165       *          return PyInt_FromLong(arg);
166       * @return a Python object representing \e arg.          show_traceback();
167       */      }
168      template <> inline  
169      PyObject * pass_instance<bool>(bool arg, const ownership own)      /**
170      {       * Specialized version of pass_instance which makes a Python boolean
171          return PyInt_FromLong((int)arg);       * from a C++ one.
172          show_traceback();       *
173      }       * @param arg the boolean to be passed to Python.
174             * @param own useless here.
175      /**       *
176       * Specialized version of pass_instance which makes a Python string       * @return a Python object representing \e arg.
177       * from a C++ std::string.       */
178       *      template <> inline
179       * @param arg the std::string to be passed to Python.      PyObject * pass_instance<bool>(bool arg, const ownership own)
180       * @param own useless here.      {
181       *          return PyInt_FromLong((int)arg);
182       * @return a Python object representing \e arg.          show_traceback();
183       */      }
184      template <> inline      
185      PyObject * pass_instance<std::string &>(std::string & arg, const ownership own)      /**
186      {       * Specialized version of pass_instance which makes a Python string
187          return PyString_FromString(arg.c_str());       * from a C++ std::string.
188          show_traceback();       *
189      }       * @param arg the std::string to be passed to Python.
190         * @param own useless here.
191      /**       *
192       * Specialized version of pass_instance which makes a Python string       * @return a Python object representing \e arg.
193       * from a C++ char *.       */
194       *      template <> inline
195       * @param arg the char * to be passed to Python.      PyObject * pass_instance<std::string &>(std::string & arg, const ownership own)
196       * @param own useless here.      {
197       *          return PyString_FromString(arg.c_str());
198       * @return a Python object representing \e arg.          show_traceback();
199       */      }
200      template <> inline  
201      PyObject * pass_instance<const char *>(const char * arg, const ownership own)      /**
202      {       * Specialized version of pass_instance which makes a Python string
203          return PyString_FromString((char *) arg);       * from a C++ char *.
204          show_traceback();       *
205      }       * @param arg the char * to be passed to Python.
206         * @param own useless here.
207      /**       *
208       * Sets the ownership of an object created with pass_instance.       * @return a Python object representing \e arg.
209       *       */
210       * @param obj the object to change ownership of.      template <> inline
211       * @param o the new ownership.      PyObject * pass_instance<const char *>(const char * arg, const ownership own)
212       */      {
213      inline void set_ownership(PyObject * obj, const ownership o)          return PyString_FromString((char *) arg);
214      {          show_traceback();
215          PyObject * n = PyInt_FromLong(o);      }
216          PyObject_SetAttrString (obj, (char*)"thisown", n);  
217          Py_DECREF(n);      /**
218          show_traceback();       * Sets the ownership of an object created with pass_instance.
219      }       *
220             * @param obj the object to change ownership of.
221      //@}       * @param o the new ownership.
222         */
223      /**      inline void set_ownership(PyObject * obj, const ownership o)
224       * @name Python to C++ instance passing functions.      {
225       *          PyObject * n = PyInt_FromLong(o);
226       */          PyObject_SetAttrString (obj, (char*)"thisown", n);
227      //@{          Py_DECREF(n);
228            show_traceback();
229      /**      }
230       * Retrieves the C++ intance of a Python object created with pass_instance.      
231       *      //@}
232       * This is the default version of retrieve_instance. The template element A must  
233       * be a pointer type.      /**
234       *       * @name Python to C++ instance passing functions.
235       * @param pyinstance The Python instance of the object to retrieve.       *
236       *       */
237       * @return A borrowed pointer to the C++ instance of the object.      //@{
238       */  
239      template <class A, class B> inline      /**
240      A retrieve_instance(PyObject * pyinstance)       * Retrieves the C++ intance of a Python object created with pass_instance.
241      {       *
242          B *retvalue = NULL;       * This is the default version of retrieve_instance. The template element A must
243         * be a pointer type.
244          swig_type_info * tt = SWIG_Python_TypeQuery (B::get_type_name_s ());       *
245          if (!tt) return NULL;       * @param pyinstance The Python instance of the object to retrieve.
246          if (SWIG_Python_ConvertPtr(pyinstance, (void **) &retvalue, tt, 0) == -1) return NULL;       *
247          return retvalue;       * @return A borrowed pointer to the C++ instance of the object.
248      }       */
249        template <class A, class B> inline
250      /**      A retrieve_instance(PyObject * pyinstance)
251       * Retrieves the C++ value of a Python integer.      {
252       *          B *retvalue = NULL;
253       * @param pyinstance The Python integer to retrieve.  
254       *          swig_type_info * tt = SWIG_Python_TypeQuery (B::get_type_name_s ());
255       * @return C++ value of pyinstance.          if (!tt) return NULL;
256       */          if (SWIG_Python_ConvertPtr(pyinstance, (void **) &retvalue, tt, 0) == -1) return NULL;
257      template <> inline          return retvalue;
258      int retrieve_instance<int, int>(PyObject * pyinstance)      }
259      {  
260          return PyInt_AsLong(pyinstance);      /**
261          show_traceback();       * Retrieves the C++ value of a Python integer.
262      }       *
263         * @param pyinstance The Python integer to retrieve.
264      /**       *
265       * Retrieves the C++ value of a Python boolean.       * @return C++ value of pyinstance.
266       *       */
267       * @param pyinstance The Python boolean to retrieve.      template <> inline
268       *      int retrieve_instance<int, int>(PyObject * pyinstance)
269       * @return C++ value of pyinstance.      {
270       */          return PyInt_AsLong(pyinstance);
271      template <> inline          show_traceback();
272      bool retrieve_instance<bool, bool>(PyObject * pyinstance)      }
273      {  
274          return (bool)PyInt_AsLong(pyinstance);      /**
275          show_traceback();       * Retrieves the C++ value of a Python boolean.
276      }       *
277         * @param pyinstance The Python boolean to retrieve.
278      /**       *
279       * Retrieves the C++ value of a Python string as a char *.       * @return C++ value of pyinstance.
280       *       */
281       * @param pyinstance The Python string to retrieve.      template <> inline
282       *      bool retrieve_instance<bool, bool>(PyObject * pyinstance)
283       * @return char * string value of pyinstance.      {
284       */          return (bool)PyInt_AsLong(pyinstance);
285      template <> inline          show_traceback();
286      const char * retrieve_instance<const char *, const char *>(PyObject * pyinstance)      }
287      {  
288          return PyString_AsString(pyinstance);      /**
289          show_traceback();       * Retrieves the C++ value of a Python string as a char *.
290      }       *
291         * @param pyinstance The Python string to retrieve.
292      /**       *
293       * Retrieves the C++ value of a Python string as a std::string.       * @return char * string value of pyinstance.
294       *       */
295       * @param pyinstance The Python string to retrieve.      template <> inline
296       *      const char * retrieve_instance<const char *, const char *>(PyObject * pyinstance)
297       * @return std::string value of pyinstance.      {
298       */          return PyString_AsString(pyinstance);
299      template <> inline          show_traceback();
300      std::string retrieve_instance<std::string, std::string>(PyObject * pyinstance)      }
301      {  
302          return std::string(PyString_AsString(pyinstance));      /**
303          show_traceback();       * Retrieves the C++ value of a Python string as a std::string.
304      }       *
305      //@}       * @param pyinstance The Python string to retrieve.
306         *
307      /**       * @return std::string value of pyinstance.
308       * @name Loading / Saving       */
309       */      template <> inline
310      //@{      std::string retrieve_instance<std::string, std::string>(PyObject * pyinstance)
311      /**      {
312       * Read the contents of a tuple from given stream.          return std::string(PyString_AsString(pyinstance));
313       * @param out flattener to read the tuple from.          show_traceback();
314       * @param start index from where to start filling the tuple.      }
315       * @return a new tuple filled with the data read from stream.      //@}
316       */  
317      PyObject *get_tuple (base::flat & in, u_int16 start = 0);      /**
318         * @name Loading / Saving
319      /**       */
320       * Write the contents of a tuple to given stream. Only supports integer and      //@{
321       * string objects.      /**
322       * @param tuple Python tuple whose contents to save.       * Read the contents of a tuple from given stream.
323       * @param in flattener to store the tuple in.       * @param in flattener to read the tuple from.
324       * @param start index from where to start flattening the tuple.       * @param start index from where to start filling the tuple.
325       */       * @return a new tuple filled with the data read from stream.
326      void put_tuple (PyObject *tuple, base::flat & out, u_int16 start = 0);       */
327      //@}      PyObject *get_tuple (base::flat & in, u_int16 start = 0);
328  }  
329        /**
330  #include "python/callback.h"       * Write the contents of a tuple to given stream. Only supports integer and
331         * string objects.
332  #endif       * @param tuple Python tuple whose contents to save.
333         * @param out flattener to store the tuple in.
334         * @param start index from where to start flattening the tuple.
335         */
336        void put_tuple (PyObject *tuple, base::flat & out, u_int16 start = 0);
337        //@}
338    }
339    
340    #include "python/callback.h"
341    
342    #endif

Legend:
Removed from v.1.12  
changed lines
  Added in v.1.13

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26