[tinypy commit] r52 - trunk/tinypy
codesite...@google.com
Date: Tue Jun 10 07:24:10 2008
New Revision: 52
Modified:
trunk/tinypy/misc.c
trunk/tinypy/ops.c
trunk/tinypy/tp.h
trunk/tinypy/vm.c
Log:
Added naturaldocs parse-able comments to a few random functions.
Modified: trunk/tinypy/misc.c
==============================================================================
--- trunk/tinypy/misc.c (original)
+++ trunk/tinypy/misc.c Tue Jun 10 07:24:10 2008
@@ -1,3 +1,7 @@
+/* File: Miscellaneous
+ * Various functions to help interface tinypy.
+ */
+
tp_obj *tp_ptr(tp_obj o) {
tp_obj *ptr = (tp_obj*)tp_malloc(sizeof(tp_obj)); *ptr = o;
return ptr;
@@ -28,6 +32,12 @@
return tp_fnc_new(tp,1,v,tp_None,g);
}
+/* Function: tp_fnc
+ * Creates a new tinypy function object.
+ *
+ * This is how you can create a tinypy function object which, when
called in
+ * the script, calls the provided C function.
+ */
tp_obj tp_fnc(TP,tp_obj v(TP)) {
return tp_fnc_new(tp,0,v,tp_None,tp_None);
}
@@ -36,6 +46,36 @@
return tp_fnc_new(tp,2,v,self,tp_None);
}
+/* Function: tp_data
+ * Creates a new data object.
+ *
+ * Parameters:
+ * magic - An integer number associated with the data type. This can
be used
+ * to check the type of data objects.
+ * v - A pointer to user data. Only the pointer is stored in the object,
+ * you keep all responsibility for the data it points to.
+ *
+ *
+ * Returns:
+ * The new data object.
+ *
+ * Public fields:
+ * The following fields can be access in a data object:
+ *
+ * magic - An integer number stored in the object.
+ * val - The data pointer of the object.
+ * info->free - If not NULL, a callback function called when the
object gets
+ * destroyed.
+ *
+ * Example:
+ * > void *__free__(TP, tp_obj self)
+ * > {
+ * > free(self.data.val);
+ * > }
+ * >
+ * > tp_obj my_obj = tp_data(TP, 0, my_ptr);
+ * > my_obj.data.info->free = __free__;
+ */
tp_obj tp_data(TP,int magic,void *v) {
tp_obj r = {TP_DATA};
r.data.info = (_tp_data*)tp_malloc(sizeof(_tp_data));
@@ -56,6 +96,22 @@
int i; for (i=0; i<n; i++) {
_tp_list_append(tp,r.list.val,argv[i]); }
return r;
}
+
+/* Function: tp_params_v
+ * Pass parameters for a tinypy function call.
+ *
+ * When you want to call a tinypy method, then you use this to pass parameters
+ * to it.
+ *
+ * Parameters:
+ * n - The number of variable arguments following.
+ * ... - Pass n tinypy objects, which a subsequently called tinypy
method will
+ * receive as parameters.
+ *
+ * Returns:
+ * A tinypy list object representing the current call parameters. You
can modify
+ * the list before doing the function call.
+ */
tp_obj tp_params_v(TP,int n,...) {
int i;
tp_obj r = tp_params(tp);
Modified: trunk/tinypy/ops.c
==============================================================================
--- trunk/tinypy/ops.c (original)
+++ trunk/tinypy/ops.c Tue Jun 10 07:24:10 2008
@@ -1,3 +1,6 @@
+/* File: Operations
+ * Various tinypy operations.
+ */
#define TP_META_BEGIN(self,name) \
if (self.dict.dtype && self.dict.val->meta.type != TP_NONE) { \
int n =
_tp_dict_find(tp,self.dict.val->meta.dict.val,tp_string(name)); \
@@ -75,6 +78,12 @@
}
+/* Function: tp_get
+ * Attribute lookup.
+ *
+ * This returns the result of using self[k] in actual code. It works for
+ * dictionaries (including classes and instantiated objects), lists
and strings.
+ */
tp_obj tp_get(TP,tp_obj self, tp_obj k) {
int type = self.type;
tp_obj r;
@@ -171,6 +180,12 @@
return 1;
}
+/* Function: tp_set
+ * Attribute modification.
+ *
+ * This is the counterpart of tp_get, it does the same as self[k] = v
would do
+ * in actual tinypy code.
+ */
void tp_set(TP,tp_obj self, tp_obj k, tp_obj v) {
int type = self.type;
Modified: trunk/tinypy/tp.h
==============================================================================
--- trunk/tinypy/tp.h (original)
+++ trunk/tinypy/tp.h Tue Jun 10 07:24:10 2008
@@ -1,3 +1,6 @@
+/* File: Helpers
+ * From tp.h.
+ */
#ifndef TP_H
#define TP_H
@@ -192,6 +195,13 @@
tp_obj tp_call(TP, tp_obj fnc, tp_obj params);
/* __func__ __VA_ARGS__ __FILE__ __LINE__ */
+
+/* Function: tp_raise
+ * Macro to raise an exception.
+ *
+ * This macro will return from the current function returning "r". The
+ * remaining parameters are used to format the exception message.
+ */
#define tp_raise(r,fmt,...) { \
_tp_raise(tp,tp_printf(tp,fmt,__VA_ARGS__)); \
return r; \
@@ -216,12 +226,23 @@
tp_inline static int _tp_max(int a, int b) { return (a>b?a:b); }
tp_inline static int _tp_sign(tp_num v) { return (v<0?-1:(v>0?1:0)); }
+/* Function: tp_number
+ * Creates a new numeric object.
+ */
tp_inline static tp_obj tp_number(tp_num v) {
tp_obj val = {TP_NUMBER};
val.number.val = v;
return val;
}
+/* Function: tp_string
+ * Creates a new string object from a C string.
+ *
+ * Given a pointer to a C string, creates a tinypy object representing the
+ * same string.
+ *
+ * TODO: Can the string be deleted after passing it to this function?
+ */
tp_inline static tp_obj tp_string(char const *v) {
tp_obj val;
tp_string_ s = {TP_STRING, 0, v, 0};
@@ -230,6 +251,12 @@
return val;
}
+/* Function: tp_string_n
+ * Creates a new string object from a partial C string.
+ *
+ * Like <tp_string>, but you specify how many bytes of the given C
string to
+ * use for the string object.
+ */
tp_inline static tp_obj tp_string_n(char const *v,int n) {
tp_obj val;
tp_string_ s = {TP_STRING, 0,v,n};
Modified: trunk/tinypy/vm.c
==============================================================================
--- trunk/tinypy/vm.c (original)
+++ trunk/tinypy/vm.c Tue Jun 10 07:24:10 2008
@@ -1,3 +1,6 @@
+/* File: VM
+ * Functionality pertaining to the virtual machine.
+ */
void tp_run(TP,int cur);
tp_vm *_tp_init(void) {
@@ -27,6 +30,14 @@
return tp;
}
+
+/* Function: tp_deinit
+ * Destroys a VM instance.
+ *
+ * When you no longer need an instance of tinypy, you can use this to
free all
+ * memory used by it. Even when you are using only a single tinypy
instance, it
+ * may be good practice to call this function on shutdown.
+ */
void tp_deinit(TP) {
while (tp->root.list.val->len) {
_tp_list_pop(tp,tp->root.list.val,0,"tp_deinit");
@@ -280,6 +291,17 @@
return tp_call(tp,tmp,params);
}
+/* Function: tp_import
+ * Imports a module.
+ *
+ * Parameters:
+ * fname - The filename of a file containing the module's code.
+ * name - The name of the module.
+ * codes - The module's code. If this is given, fname is ignored.
+ *
+ * Returns:
+ * The module object.
+ */
tp_obj tp_import(TP, char const *fname, char const *name, void *codes) {
tp_obj code = tp_None;
tp_obj g;
@@ -386,6 +408,15 @@
return tp_exec(tp,code,globals);
}
+/* Function: tp_init
+ * Initializes a new virtual machine.
+ *
+ * The given parameters have the same format as the parameters to
main, and
+ * allow passing arguments to your tinypy scripts.
+ *
+ * Returns:
+ * The newly created tinypy instance.
+ */
tp_vm *tp_init(int argc, char *argv[]) {
tp_vm *tp = _tp_init();
tp_builtins(tp);