Adonthell  0.4
py_object.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 1999/2000/2001/2003 Kai Sterker <kai.sterker@gmail.com>
3  Copyright (C) 2001 Alexandre Courbot <alexandrecourbot@linuxgames.com>
4  Part of the Adonthell Project <http://adonthell.nongnu.org>
5 
6  Adonthell is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10 
11  Adonthell is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with Adonthell. If not, see <http://www.gnu.org/licenses/>.
18 */
19 
20 
21 /**
22  * @file py_object.h
23  * @author Kai Sterker <kai.sterker@gmail.com>
24  * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
25  *
26  * @brief Declares the py_object class.
27  */
28 
29 
30 #ifndef PY_OBJECT_H
31 #define PY_OBJECT_H
32 
33 #include "python_class.h"
34 
35 
36 /**
37  * Python object class.
38  *
39  * Use this class to create instances of Python classes contained in Python
40  * modules, then control their execution. You can pass an argument tuple to
41  * the class constructor and to any method you want to run. It is further
42  * possible to access and change attributes of the Python instance.
43  *
44  */
45 class py_object
46 {
47 public:
48  /**
49  * Default constructor.
50  *
51  */
52  py_object ();
53 
54  /**
55  * Destructor.
56  *
57  */
58  ~py_object ();
59 
60  /**
61  * Resets the script to it's post-constructor state.
62  *
63  */
64  void clear ();
65 
66  /**
67  * @name PyObject creation
68  */
69  //@{
70  /**
71  * Creates an instance of a Python class.
72  *
73  * @param file file name of the module to use.
74  * @param classname name of the class to import.
75  * @param args Python tuple containing the arguments to pass to the
76  * Python class constructor.
77  */
78  bool create_instance (string file, string classname, PyObject * args = NULL);
79 
80  /**
81  * Similar to create_instance, except that it will reload the module
82  * from disk, in case it has been changed in the meantime. Mainly interesting
83  * for script development or tools like dlgedit.
84  *
85  * @param file file name of the module to use.
86  * @param classname name of the class to import.
87  * @param args Python tuple containing the arguments to pass to the
88  * Python class constructor.
89  */
90  bool reload_instance (string file, string classname, PyObject * args = NULL);
91  //@}
92 
93  /**
94  * @name PyObject method calling
95  */
96  //@{
97  /**
98  * Call a method of this object.
99  *
100  * @param name name of the method to call.
101  * @param args Python tuple containing the arguments to pass to the method.
102  * @return the return value of the method as PyObject. Needs to be
103  * Py_DECREF'd when no longer needed.
104  */
105  PyObject *call_method_ret (const string &name, PyObject *args = NULL) const;
106 
107  /**
108  * Call a method of this object.
109  *
110  * @param name name of the method to call.
111  * @param args Python tuple containing the arguments to pass to the method.
112  */
113  void call_method (const string & name, PyObject * args = NULL) const
114  {
115  PyObject *result = call_method_ret (name, args);
116  Py_XDECREF (result);
117  }
118 
119  /**
120  * Calls the run () method of this object.
121  * Equivalent to call_method ("run", args);
122  *
123  * @param args Python tuple containing the arguments to pass to the method.
124  */
125  void run (PyObject * args = NULL)
126  {
127  call_method ("run", args);
128  }
129  //@}
130 
131  /**
132  * @name PyObject member access
133  */
134  //@{
135  /**
136  * Tests whether the object contains a certain attribute (i.e. method
137  * or variable).
138  *
139  * @param name Name of the attribute to test for
140  * @return <b>true</b> if the attribute exists, <b>false</b> otherwise.
141  */
142  bool has_attribute (const std::string & name);
143 
144  /**
145  * Returns a new reference to an attribute of this object.
146  *
147  * @param name Name of the attribute to access
148  * @return New reference to the attribute or NULL on error
149  */
150  PyObject* get_attribute (const string & name) const;
151 
152  /**
153  * Returns the given attribute as integer value.
154  *
155  * @param name Name of the attribute to access
156  * @return An integer.
157  */
158  s_int32 get_attribute_int (const string & name);
159 
160  /**
161  * Returns the given attribute as string value.
162  *
163  * @param name Name of the attribute to access
164  * @return A string.
165  */
166  string get_attribute_string (const string & name);
167 
168  /**
169  * Assign a new attribute to the module, overriding an existing
170  * attribute of the same name.
171  *
172  * @param name The attribute's name
173  * @param value The attribute's value
174  */
175  void set_attribute (const string & name, PyObject *value);
176 
177  /**
178  * Assign a new integer attribute to the module, overriding an
179  * existing attribute of the same name.
180  *
181  * @param name The attribute's name
182  * @param value The attribute's value
183  */
184  void set_attribute_int (const string & name, s_int32 value);
185 
186  /**
187  * Assign a new string attribute to the module, overriding an
188  * existing attribute of the same name.
189  *
190  * @param name The attribute's name
191  * @param value The attribute's value
192  */
193  void set_attribute_string (const string & name, const string & value);
194  //@}
195 
196  /**
197  * @name Member access
198  */
199  //@{
200  /**
201  * Direct access to the instance object. The default behaviour is to
202  * increase the instance's reference count, so that this method can
203  * be safely called from Python scripts.
204  *
205  * @param incref whether to increase the reference count.
206  * @return the Python class instance.
207  */
208  PyObject *get_instance (const bool & incref = true) const
209  {
210  if (incref)
211  {
212  Py_XINCREF (Instance);
213  }
214  return Instance;
215  }
216 
217  /**
218  * Returns the class name of this object. This is the name of the
219  * wrapped Python class.
220  *
221  * @return class name of this object.
222  */
223  std::string class_name () const
224  {
225  return Classname;
226  }
227 
228  /**
229  * Returns the file name of this object. This is the name of the
230  * Python module containing the wrapped class.
231  *
232  * @return fi�e name of this object.
233  */
234  std::string file_name () const
235  {
236  return Filename;
237  }
238  //@}
239 
240 protected:
241  /**
242  * The python class instance wrapped by %py_object
243  */
244  PyObject *Instance;
245 
246 private:
247  /**
248  * Helper for create_instance and reload_instance
249  *
250  */
251  bool instanciate (PyObject*, string, string, PyObject*);
252 
253  /**
254  * The class name of the current script
255  */
256  std::string Classname;
257 
258  /**
259  * The file name of the current script
260  */
261  std::string Filename;
262 };
263 
264 #endif // PY_OBJECT_H
#define s_int32
32 bits long signed integer
Definition: types.h:50
void clear()
Resets the script to it&#39;s post-constructor state.
Definition: py_object.cc:46
Python object class.
Definition: py_object.h:45
py_object()
Default constructor.
Definition: py_object.cc:33
~py_object()
Destructor.
Definition: py_object.cc:40
string get_attribute_string(const string &name)
Returns the given attribute as string value.
Definition: py_object.cc:169
void call_method(const string &name, PyObject *args=NULL) const
Call a method of this object.
Definition: py_object.h:113
void set_attribute(const string &name, PyObject *value)
Assign a new attribute to the module, overriding an existing attribute of the same name...
Definition: py_object.cc:186
PyObject * get_attribute(const string &name) const
Returns a new reference to an attribute of this object.
Definition: py_object.cc:143
void set_attribute_int(const string &name, s_int32 value)
Assign a new integer attribute to the module, overriding an existing attribute of the same name...
Definition: py_object.cc:194
bool create_instance(string file, string classname, PyObject *args=NULL)
Creates an instance of a Python class.
Definition: py_object.cc:57
std::string file_name() const
Returns the file name of this object.
Definition: py_object.h:234
PyObject * call_method_ret(const string &name, PyObject *args=NULL) const
Call a method of this object.
Definition: py_object.cc:112
void run(PyObject *args=NULL)
Calls the run () method of this object.
Definition: py_object.h:125
PyObject * get_instance(const bool &incref=true) const
Direct access to the instance object.
Definition: py_object.h:208
Defines the python class. This file is named this way so it doesn&#39;t conflicts with Python...
void set_attribute_string(const string &name, const string &value)
Assign a new string attribute to the module, overriding an existing attribute of the same name...
Definition: py_object.cc:209
bool reload_instance(string file, string classname, PyObject *args=NULL)
Similar to create_instance, except that it will reload the module from disk, in case it has been chan...
Definition: py_object.cc:68
PyObject * Instance
The python class instance wrapped by py_object.
Definition: py_object.h:244
std::string class_name() const
Returns the class name of this object.
Definition: py_object.h:223
s_int32 get_attribute_int(const string &name)
Returns the given attribute as integer value.
Definition: py_object.cc:152
bool has_attribute(const std::string &name)
Tests whether the object contains a certain attribute (i.e.
Definition: py_object.cc:134