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