annotate libpurple/dbus-analyze-functions.py @ 20329:24ce4fcce5b0

applied changes from e56db1b8a7bb8729e30fb3bf99a94ff7887fe4ec through 3efb5d625e5a73423be8be77a6baeed0b65f7e55 applied changes from 74f0e6698f9f17bc8335cf2454c06e6b13748039 through 017296ee954fb91349806c809983c916842603da applied changes from c8ff393c43d8a5f4136c653853a95284cc5710dc through f53dbbff44537aa86b1cb8788fd306c90e6ccca9 applied changes from f53dbbff44537aa86b1cb8788fd306c90e6ccca9 through 5798594431164383deacd7d4aad5a9a0d5b867ae applied changes from 5798594431164383deacd7d4aad5a9a0d5b867ae through 0822c640f22b63d7bc8992e62b80bccd1eea12a2 applied changes from 703c3f9437d5e71255819c747f9690d19c6ba6e3 through b7a2c4d81867c3bbd262c2a4b1d924ea7fd3afb6 applied changes from b7a2c4d81867c3bbd262c2a4b1d924ea7fd3afb6 through 5ea15b000ee727088be88bb335c2ded6b2ab96e3 applied changes from 5ea15b000ee727088be88bb335c2ded6b2ab96e3 through c5051010dd50f9fdb7f85d779d882ce8bbc149f2

import re
import string
import sys

# types translated into "int"
simpletypes = ["int", "gint", "guint", "gboolean", "gpointer", "size_t", "gssize", "time_t"]

# List "excluded" contains functions that shouldn't be exported via
# DBus.  If you remove a function from this list, please make sure
# that it does not break "make" with the configure option
# "--enable-dbus" turned on.

excluded = [\
    # I don't remember why this function is excluded; something to do
    # with the fact that it takes a (const) GList as a parameter.
    "purple_presence_add_list",

    # These functions are excluded because they involve value of the
    # type PurpleConvPlacementFunc, which is a pointer to a function and
    # (currently?) can't be translated into a DBus type.  Normally,
    # functions with untranslatable types are skipped, but this script
    # assumes that all non-pointer type names beginning with "Purple"
    # are enums, which is not true in this case.
    "purple_conv_placement_add_fnc",
    "purple_conv_placement_get_fnc",
    "purple_conv_placement_get_current_func",
    "purple_conv_placement_set_current_func",

    # Similar to the above:
    "purple_account_set_register_callback",
    "purple_account_unregister",
    "purple_connection_new_unregister",

    # This is excluded because this script treats PurpleLogReadFlags*
    # as pointer to a struct, instead of a pointer to an enum.  This
    # causes a compilation error. Someone should fix this script.
    "purple_log_read",
    ]

# This is a list of functions that return a GList* or GSList * whose elements
# are strings, not pointers to objects.
stringlists = [
    "purple_prefs_get_path_list",
    "purple_prefs_get_string_list",
    "purple_uri_list_extract_filenames",
    "purple_uri_list_extract_uris",
    "purple_prefs_get_children_names",
]

# This is a list of functions that return a GList* or GSList* that should
# not be freed.  Ideally, this information should be obtained from the Doxygen
# documentation at some point.
constlists = [
    "purple_account_get_status_types",
    "purple_accounts_get_all",
    "purple_account_option_get_list",
    "purple_connections_get_all",
    "purple_connections_get_connecting",
    "purple_get_conversations",
    "purple_get_ims",
    "purple_get_chats",
    "purple_conv_chat_get_users",
    "purple_conv_chat_get_ignored",
    "purple_mime_document_get_fields",
    "purple_mime_document_get_parts",
    "purple_mime_part_get_fields",
    "purple_notify_user_info_get_entries",
    "purple_request_fields_get_required",
    "purple_request_field_list_get_selected",
    "purple_request_field_list_get_items",
    "purple_savedstatuses_get_all",
    "purple_status_type_get_attrs",
    "purple_presence_get_statuses",
    "purple_conversation_get_message_history",
]

pointer = "#pointer#"
myexception = "My Exception"

def ctopascal(name):
    newname = ""
    for word in name.split("_"):
        newname += word.capitalize()
    return newname

class Parameter:
    def __init__(self, type, name):
        self.name = name
        self.type = type

    def fromtokens(tokens, parameternumber = -1):
        if len(tokens) == 0:
            raise myexception
        if (len(tokens) == 1) or (tokens[-1] == pointer):
            if parameternumber >= 0:
                return Parameter(tokens, "param%i" % parameternumber)
            else:
                raise myexception
        else:
            return Parameter(tokens[:-1], tokens[-1])
                    
    fromtokens = staticmethod(fromtokens)

class Binding:
    def __init__(self, functiontext, paramtexts):
        self.function = Parameter.fromtokens(functiontext.split())

        if self.function.name in excluded:
            raise myexception

        self.params = []
        for i in range(len(paramtexts)):
            self.params.append(Parameter.fromtokens(paramtexts[i].split(), i))

        self.call = "%s(%s)" % (self.function.name,
                                ", ".join([param.name for param in self.params]))
        
    
    def process(self):
        for param in self.params:
            self.processinput(param.type, param.name)

        self.processoutput(self.function.type, "RESULT")
        self.flush()
        

    def processinput(self, type, name):
        const = False
        unsigned = False
        if type[0] == "const":
            type = type[1:]
            const = True

        if type[0] == "unsigned":
            type = type[1:]
            unsigned = True

        if len(type) == 1:
            # simple types (int, gboolean, etc.) and enums
            if (type[0] in simpletypes) or ((type[0].startswith("Purple") and not type[0].endswith("Callback"))):
                return self.inputsimple(type, name, unsigned)

        # pointers ... 
        if (len(type) == 2) and (type[1] == pointer):
            # strings
            if type[0] in ["char", "gchar"]:
                if const:
                    return self.inputstring(type, name, unsigned)
                else:
                    raise myexception

            elif type[0] == "GHashTable":
                return self.inputhash(type, name)
                
            # known object types are transformed to integer handles
            elif type[0].startswith("Purple") or type[0] == "xmlnode":
                return self.inputpurplestructure(type, name)

            # unknown pointers are always replaced with NULL
            else:
                return self.inputpointer(type, name)

        raise myexception

   
    def processoutput(self, type, name):
        # the "void" type is simple ...
        if type == ["void"]:
            return self.outputvoid(type, name)

        const = False
        if type[0] == "const":
            type = type[1:]
            const = True

        # a string
        if type == ["char", pointer] or type == ["gchar", pointer]:
            return self.outputstring(type, name, const)

        # simple types (ints, booleans, enums, ...)
        if (len(type) == 1) and \
               ((type[0] in simpletypes) or (type[0].startswith("Purple"))):
            return self.outputsimple(type, name)

        # pointers ...
        if (len(type) == 2) and (type[1] == pointer):

            # handles
            if type[0].startswith("Purple"):
                return self.outputpurplestructure(type, name)

            if type[0] in ["GList", "GSList"]:
                return self.outputlist(type, name)

        raise myexception
    

class ClientBinding (Binding):
    def __init__(self, functiontext, paramtexts, knowntypes, headersonly):
        Binding.__init__(self, functiontext, paramtexts)
        self.knowntypes = knowntypes
        self.headersonly = headersonly
        self.paramshdr = []
        self.decls = []
        self.inputparams = []
        self.outputparams = []
        self.returncode = []

    def flush(self):
        paramslist = ", ".join(self.paramshdr)
        if (paramslist == "") :
            paramslist = "void"
        print "%s %s(%s)" % (self.functiontype, self.function.name,
                             paramslist),

        if self.headersonly:
            print ";"
            return

        print "{"

        for decl in self.decls:
            print decl

        print 'dbus_g_proxy_call(purple_proxy, "%s", NULL,' % ctopascal(self.function.name)
        
        for type_name in self.inputparams:
            print "\t%s, %s, " % type_name,
        print "G_TYPE_INVALID,"

        for type_name in self.outputparams:
            print "\t%s, &%s, " % type_name,
        print "G_TYPE_INVALID);"
        
        for code in self.returncode:
            print code

        print "}\n"
        

    def definepurplestructure(self, type):
        if (self.headersonly) and (type[0] not in self.knowntypes):
            print "struct _%s;" % type[0]
            print "typedef struct _%s %s;" % (type[0], type[0])
            self.knowntypes.append(type[0])

    def inputsimple(self, type, name, us):
        self.paramshdr.append("%s %s" % (type[0], name))
        if us:
            self.inputparams.append(("G_TYPE_UINT", name))
        else:
            self.inputparams.append(("G_TYPE_INT", name))

    def inputstring(self, type, name, us):
        if us:
            self.paramshdr.append("const unsigned char *%s" % name)
        else:
            self.paramshdr.append("const char *%s" % name)
        self.inputparams.append(("G_TYPE_STRING", name))
        
    def inputpurplestructure(self, type, name):
        self.paramshdr.append("const %s *%s" % (type[0], name))
        self.inputparams.append(("G_TYPE_INT", "GPOINTER_TO_INT(%s)" % name))
        self.definepurplestructure(type)

    def inputpointer(self, type, name):
        name += "_NULL"
        self.paramshdr.append("const %s *%s" % (type[0], name))
        self.inputparams.append(("G_TYPE_INT", "0"))
        
    def inputhash(self, type, name):
        self.paramshdr.append("const GHashTable *%s" % name)
        self.inputparams.append(('dbus_g_type_get_map ("GHashTable", G_TYPE_STRING, G_TYPE_STRING)', name))

    def outputvoid(self, type, name):
        self.functiontype = "void"

    def outputstring(self, type, name, const):
        self.functiontype = "char*"
        self.decls.append("char *%s = NULL;" % name)
        self.outputparams.append(("G_TYPE_STRING", name))
#        self.returncode.append("NULLIFY(%s);" % name)
        self.returncode.append("return %s;" % name);

    def outputsimple(self, type, name):
        self.functiontype = type[0]
        self.decls.append("%s %s = 0;" % (type[0], name))
        self.outputparams.append(("G_TYPE_INT", name))
        self.returncode.append("return %s;" % name);

    # we could add "const" to the return type but this would probably
    # be a nuisance
    def outputpurplestructure(self, type, name):
        name = name + "_ID"
        self.functiontype = "%s*" % type[0]
        self.decls.append("int %s = 0;" % name)
        self.outputparams.append(("G_TYPE_INT", "%s" % name))
        self.returncode.append("return (%s*) GINT_TO_POINTER(%s);" % (type[0], name));
        self.definepurplestructure(type)

    def outputlist(self, type, name):
        self.functiontype = "%s*" % type[0]
        self.decls.append("GArray *%s;" % name)
        self.outputparams.append(('dbus_g_type_get_collection("GArray", G_TYPE_INT)', name))
        self.returncode.append("return garray_int_to_%s(%s);" %
                               (type[0].lower(), name));

 
class ServerBinding (Binding):
    def __init__(self, functiontext, paramtexts):
        Binding.__init__(self, functiontext, paramtexts)
        self.dparams = ""
        self.cparams = []
        self.cdecls  = []
        self.ccode  = []
        self.cparamsout = []
        self.ccodeout = []
        self.argfunc = "dbus_message_get_args"

    def flush(self):
        print "static DBusMessage*"
        print "%s_DBUS(DBusMessage *message_DBUS, DBusError *error_DBUS) {" % \
              self.function.name
        
        print "\tDBusMessage *reply_DBUS;"

        for decl in self.cdecls:
            print decl

        print "\t%s(message_DBUS, error_DBUS," % self.argfunc,
        for param in self.cparams:
            print "DBUS_TYPE_%s, &%s," % param,
        print "DBUS_TYPE_INVALID);"

        print "\tCHECK_ERROR(error_DBUS);"

        for code in self.ccode:
            print code

        print "\treply_DBUS = dbus_message_new_method_return (message_DBUS);"

        print "\tdbus_message_append_args(reply_DBUS,",
        for param in self.cparamsout:
            if type(param) is str:
                print "%s," % param,
            else:
                print "DBUS_TYPE_%s, &%s," % param,
        print "DBUS_TYPE_INVALID);"

        for code in self.ccodeout:
            print code

        print "\treturn reply_DBUS;\n}\n"


    def addstring(self, *items):
        for item in items:
            self.dparams += item + r"\0"

    def addintype(self, type, name):
        self.addstring("in", type, name)

    def addouttype(self, type, name):
        self.addstring("out", type, name)


    # input parameters

    def inputsimple(self, type, name, us):
        if us:
            self.cdecls.append("\tdbus_int32_t %s;" % name)
            self.cparams.append(("INT32", name))
            self.addintype("i", name)
        else:
            self.cdecls.append("\tdbus_uint32_t %s;" % name)
            self.cparams.append(("UINT32", name))
            self.addintype("u", name)

    def inputstring(self, type, name, us):
        if us:
            self.cdecls.append("\tconst unsigned char *%s;" % name)
        else:
            self.cdecls.append("\tconst char *%s;" % name)
        self.cparams.append(("STRING", name))
        self.ccode.append("\t%s = (%s && %s[0]) ? %s : NULL;" % (name,name,name,name))
        self.addintype("s", name)

    def inputhash(self, type, name):
        self.argfunc = "purple_dbus_message_get_args"
        self.cdecls.append("\tDBusMessageIter %s_ITER;" % name)
        self.cdecls.append("\tGHashTable *%s;" % name)
        self.cparams.append(("ARRAY", "%s_ITER" % name))
        self.ccode.append("\t%s = purple_dbus_iter_hash_table(&%s_ITER, error_DBUS);" \
                     % (name, name))
        self.ccode.append("\tCHECK_ERROR(error_DBUS);")
        self.ccodeout.append("\tg_hash_table_destroy(%s);" % name)
        self.addintype("a{ss}", name)

    def inputpurplestructure(self, type, name):
        self.cdecls.append("\tdbus_int32_t %s_ID;" %  name)
        self.cdecls.append("\t%s *%s;" % (type[0], name))
        self.cparams.append(("INT32", name + "_ID"))
        self.ccode.append("\tPURPLE_DBUS_ID_TO_POINTER(%s, %s_ID, %s, error_DBUS);"  % \
                       (name, name, type[0]))
        self.addintype("i", name)

    def inputpointer(self, type, name):
        self.cdecls.append("\tdbus_int32_t %s_NULL;" %  name)
        self.cdecls .append("\t%s *%s;" % (type[0], name))
        self.cparams.append(("INT32", name + "_NULL"))
        self.ccode  .append("\t%s = NULL;" % name)
        self.addintype("i", name)

    # output parameters

    def outputvoid(self, type, name):
        self.ccode.append("\t%s;" % self.call) # just call the function

    def outputstring(self, type, name, const):
        if const:
            self.cdecls.append("\tconst char *%s;" % name)
        else:
            self.cdecls.append("\tchar *%s;" % name)
        self.ccode.append("\tif ((%s = %s) == NULL)" % (name, self.call))
        self.ccode.append("\t\t%s = \"\";" % (name))
        self.cparamsout.append(("STRING", name))
        self.addouttype("s", name)
        if not const:
            self.ccodeout.append("\tg_free(%s);" % name)

    def outputsimple(self, type, name):
        self.cdecls.append("\tdbus_int32_t %s;" % name)
        self.ccode.append("\t%s = %s;" % (name, self.call))
        self.cparamsout.append(("INT32", name))
        self.addouttype("i", name)

    def outputpurplestructure(self, type, name):
        self.cdecls.append("\tdbus_int32_t %s;" % name)
        self.ccode .append("\tPURPLE_DBUS_POINTER_TO_ID(%s, %s, error_DBUS);" % (name, self.call))
        self.cparamsout.append(("INT32", name))
        self.addouttype("i", name)

    # GList*, GSList*, assume that list is a list of objects
    # unless the function is in stringlists
    def outputlist(self, type, name):
        self.cdecls.append("\tdbus_int32_t %s_LEN;" % name)
        self.ccodeout.append("\tg_free(%s);" % name)

        self.cdecls.append("\t%s *list;" % type[0]);

        if self.function.name in stringlists:
            self.cdecls.append("\tchar **%s;" % name)
            self.ccode.append("\tlist = %s;" % self.call)
            self.ccode.append("\t%s = (char **)purple_%s_to_array(list, FALSE, &%s_LEN);" % \
                         (name, type[0], name))
            self.cparamsout.append("DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &%s, %s_LEN" \
                          % (name, name))
            if (not (self.function.name in constlists)):
                type_name = type[0].lower()[1:]
                self.ccodeout.append("\tg_%s_foreach(list, (GFunc)g_free, NULL);" % type_name)
                self.ccodeout.append("\tg_%s_free(list);" % type_name)
            self.addouttype("as", name)
        else:
            self.cdecls.append("\tdbus_int32_t *%s;" % name)
            self.ccode.append("\tlist = %s;" % self.call)
            self.ccode.append("\t%s = purple_dbusify_%s(list, FALSE, &%s_LEN);" % \
                         (name, type[0], name))
            if (not (self.function.name in constlists)):
                self.ccode.append("\tg_%s_free(list);" % type[0].lower()[1:])
            self.cparamsout.append("DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &%s, %s_LEN" \
                              % (name, name))
            self.addouttype("ai", name)


class BindingSet:
    regexp = r"^(\w[^()]*)\(([^()]*)\)\s*;\s*$";

    def __init__(self, inputfile, fprefix):
        self.inputiter = iter(inputfile)
        self.functionregexp = \
             re.compile("^%s(\w[^()]*)\(([^()]*)\)\s*;\s*$" % fprefix)    


                
    def process(self):
        print "/* Generated by %s.  Do not edit! */" % sys.argv[0]

        for line in self.inputiter:
            words = line.split()
            if len(words) == 0:             # empty line
                continue
            if line[0] == "#":              # preprocessor directive
                continue
            if words[0] in ["typedef", "struct", "enum", "static"]:
                continue

            # accumulate lines until the parentheses are balance or an
            # empty line has been encountered
            myline = line.strip()
            while myline.count("(") > myline.count(")"):
                newline = self.inputiter.next().strip()
                if len(newline) == 0:
                    break
                myline += " " + newline

            # is this a function declaration?
            thematch = self.functionregexp.match(
                myline.replace("*", " " + pointer + " "))

            if thematch is None:
                continue

            functiontext = thematch.group(1)
            paramstext = thematch.group(2).strip()

            if (paramstext == "void") or (paramstext == ""):
                paramtexts = []
            else:
                paramtexts = paramstext.split(",")

            try:
                self.processfunction(functiontext, paramtexts)
            except myexception:
                sys.stderr.write(myline + "\n")
            except:
                sys.stderr.write(myline + "\n")
                raise

        self.flush()

class ServerBindingSet (BindingSet):
    def __init__(self, inputfile, fprefix):
        BindingSet.__init__(self, inputfile, fprefix)
        self.functions = []


    def processfunction(self, functiontext, paramtexts):
        binding = ServerBinding(functiontext, paramtexts)
        binding.process()
        self.functions.append((binding.function.name, binding.dparams))
        
    def flush(self):
        print "static PurpleDBusBinding bindings_DBUS[] = { "
        for function, params in self.functions:
            print '{"%s", "%s", %s_DBUS},' % \
                  (ctopascal(function), params, function)

        print "{NULL, NULL, NULL}"
        print "};"

        print "#define PURPLE_DBUS_REGISTER_BINDINGS(handle) purple_dbus_register_bindings(handle, bindings_DBUS)"
        
class ClientBindingSet (BindingSet):
    def __init__(self, inputfile, fprefix, headersonly):
        BindingSet.__init__(self, inputfile, fprefix)
        self.functions = []
        self.knowntypes = []
        self.headersonly = headersonly

    def processfunction(self, functiontext, paramtexts):
        binding = ClientBinding(functiontext, paramtexts, self.knowntypes, self.headersonly)
        binding.process()

    def flush(self):
        pass

# Main program

options = {}

for arg in sys.argv[1:]:
    if arg[0:2] == "--":
        mylist = arg[2:].split("=",1)
        command = mylist[0]
        if len(mylist) > 1:
            options[command] = mylist[1]
        else:
            options[command] = None

if "export-only" in options:
    fprefix = "DBUS_EXPORT\s+"
else:
    fprefix = ""

sys.stderr.write("%s: Functions not exported:\n" % sys.argv[0])

if "client" in options:
    bindings = ClientBindingSet(sys.stdin, fprefix,
                                options.has_key("headers"))
else:
    bindings = ServerBindingSet(sys.stdin, fprefix)
bindings.process()