## IAnjutaSymbolQuery

IAnjutaSymbolQuery — Source code symbol query interface

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/interfaces/ianjuta-symbol-query.h>

    #define             IANJUTA_TYPE_SYMBOL_QUERY_DB
    #define             IANJUTA_TYPE_SYMBOL_QUERY_FILE_SCOPE
    #define             IANJUTA_TYPE_SYMBOL_QUERY_MODE
    #define             IANJUTA_TYPE_SYMBOL_QUERY_NAME
    #define             IANJUTA_SYMBOL_QUERY_ERROR
                        IAnjutaSymbolQuery;
                        IAnjutaSymbolQueryIface;
    enum                IAnjutaSymbolQueryDb;
    enum                IAnjutaSymbolQueryFileScope;
    enum                IAnjutaSymbolQueryMode;
    enum                IAnjutaSymbolQueryName;
    GType               ianjuta_symbol_query_file_scope_get_type
                                                            (void);
    GType               ianjuta_symbol_query_mode_get_type  (void);
    GType               ianjuta_symbol_query_name_get_type  (void);
    GQuark              ianjuta_symbol_query_error_quark    (void);
    GType               ianjuta_symbol_query_get_type       (void);
    void                ianjuta_symbol_query_cancel         (IAnjutaSymbolQuery *obj,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search         (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_all     (IAnjutaSymbolQuery *obj,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_class_parents
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_file    (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             const GFile *file,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_id      (IAnjutaSymbolQuery *obj,
                                                             gint symbol_id,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_in_scope
                                                            (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             IAnjutaSymbol *scope,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_members (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_parent_scope
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_parent_scope_file
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             const gchar *file_path,
                                                             GError **err);
    IAnjutaIterable*    ianjuta_symbol_query_search_scope   (IAnjutaSymbolQuery *obj,
                                                             const gchar *file_path,
                                                             gint line,
                                                             GError **err);
    void                ianjuta_symbol_query_set_fields     (IAnjutaSymbolQuery *obj,
                                                             gint n_fields,
                                                             IAnjutaSymbolField *fields,
                                                             GError **err);
    void                ianjuta_symbol_query_set_file_scope (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolQueryFileScope filescope_search,
                                                             GError **err);
    void                ianjuta_symbol_query_set_filters    (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolType filters,
                                                             gboolean includes_types,
                                                             GError **err);
    void                ianjuta_symbol_query_set_group_by   (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolField field,
                                                             GError **err);
    void                ianjuta_symbol_query_set_limit      (IAnjutaSymbolQuery *obj,
                                                             gint limit,
                                                             GError **err);
    void                ianjuta_symbol_query_set_mode       (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolQueryMode mode,
                                                             GError **err);
    void                ianjuta_symbol_query_set_offset     (IAnjutaSymbolQuery *obj,
                                                             gint offset,
                                                             GError **err);
    void                ianjuta_symbol_query_set_order_by   (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolField field,
                                                             GError **err);

## Object Hierarchy

      GInterface
       +----IAnjutaSymbolQuery

## Prerequisites

IAnjutaSymbolQuery requires GObject.

## Signals

      "async-result"                                   : Run Last

## Description

A query object will have this interface that allows to tweak various query parameters. Except for the IAnjutaSymbolQueryName and IAnjutaSymbolQueryDb parameters, everything else is changable post-creation.

Note that chaning a query parameter, except for limit and offset will result in re-preparing the query the next time it is executed, so it is not advisable to change it each time the query is executed. For such cases, create different queries with different parameters.

A query is signified by a name enumeration (IAnjutaSymbolQueryName) which practically determines the query type and its execution condition. Each query name is assigned to pre-defined query statement and can only be set during creation time. Then only its specific ianjuta_symbol_query_search_*() can be used to execute the query. These specific execution methods are provided to make it convenient to pass query parameters easily and to ensure all the needed parameters are given.

A query can run in different modes, defined by IAnjutaSymbolQueryMode, by default it is executed in synchrounous mode IANJUTA_SYMBOL_QUERY_MODE_SYNC and can be changed using `ianjuta_symbol_query_set_mode()`. IANJUTA_SYMBOL_QUERY_MODE_ASYNC runs it in asynchronous mode in a separate thread and can be canceled with `ianjuta_symbol_query_cancel()`.

A query runs on a database, defined by IAnjutaSymbolQueryDb, and can be only selected at creatation time.

In addition, there are many other filters that can be set to the query to refine the query results. For example, `ianjuta_symbol_query_set_fields()` is used to set the needed symbol fields to retrieve, `ianjuta_symbol_query_set_filters()` is used to filter the results with symbol types, `ianjuta_symbol_query_set_file_scope()` limits the results to either public or private scope within the source file, `ianjuta_symbol_query_set_group_by()` is used to group the results on a given field, ianjuta_symbol_query_set_order_by is used to order the results on a given field.

`ianjuta_symbol_query_set_limit()` and `ianjuta_symbol_query_set_offset()` are used to change limit and offset of the resultset. Note again that these parameters do not require re-preparation of query, so can be safely used any time without performance hit.

## Details

### IANJUTA_TYPE_SYMBOL_QUERY_DB

    #define IANJUTA_TYPE_SYMBOL_QUERY_DB (ianjuta_symbol_query_db_get_type())

### IANJUTA_TYPE_SYMBOL_QUERY_FILE_SCOPE

    #define IANJUTA_TYPE_SYMBOL_QUERY_FILE_SCOPE (ianjuta_symbol_query_file_scope_get_type())

### IANJUTA_TYPE_SYMBOL_QUERY_MODE

    #define IANJUTA_TYPE_SYMBOL_QUERY_MODE (ianjuta_symbol_query_mode_get_type())

### IANJUTA_TYPE_SYMBOL_QUERY_NAME

    #define IANJUTA_TYPE_SYMBOL_QUERY_NAME (ianjuta_symbol_query_name_get_type())

### IANJUTA_SYMBOL_QUERY_ERROR

    #define IANJUTA_SYMBOL_QUERY_ERROR ianjuta_symbol_query_error_quark()

### IAnjutaSymbolQuery

    typedef struct _IAnjutaSymbolQuery IAnjutaSymbolQuery;

### IAnjutaSymbolQueryIface

    typedef struct {
    	GTypeInterface g_iface;

    	/* Signal */
    	void (*async_result) (IAnjutaSymbolQuery *obj, GObject* result);

    	void (*cancel) (IAnjutaSymbolQuery *obj, GError **err);
    	IAnjutaIterable* (*search) (IAnjutaSymbolQuery *obj, const gchar *pattern, GError **err);
    	IAnjutaIterable* (*search_all) (IAnjutaSymbolQuery *obj, GError **err);
    	IAnjutaIterable* (*search_class_parents) (IAnjutaSymbolQuery *obj, IAnjutaSymbol *symbol, GError **err);
    	IAnjutaIterable* (*search_file) (IAnjutaSymbolQuery *obj, const gchar *pattern,  const GFile *file, GError **err);
    	IAnjutaIterable* (*search_id) (IAnjutaSymbolQuery *obj, gint symbol_id, GError **err);
    	IAnjutaIterable* (*search_in_scope) (IAnjutaSymbolQuery *obj, const gchar *pattern,  IAnjutaSymbol *scope, GError **err);
    	IAnjutaIterable* (*search_members) (IAnjutaSymbolQuery *obj, IAnjutaSymbol *symbol, GError **err);
    	IAnjutaIterable* (*search_parent_scope) (IAnjutaSymbolQuery *obj, IAnjutaSymbol *symbol, GError **err);
    	IAnjutaIterable* (*search_parent_scope_file) (IAnjutaSymbolQuery *obj, IAnjutaSymbol *symbol,  const gchar *file_path, GError **err);
    	IAnjutaIterable* (*search_scope) (IAnjutaSymbolQuery *obj, const gchar *file_path,  gint line, GError **err);
    	void (*set_fields) (IAnjutaSymbolQuery *obj, gint n_fields,  IAnjutaSymbolField *fields, GError **err);
    	void (*set_file_scope) (IAnjutaSymbolQuery *obj, IAnjutaSymbolQueryFileScope filescope_search, GError **err);
    	void (*set_filters) (IAnjutaSymbolQuery *obj, IAnjutaSymbolType filters,  gboolean includes_types, GError **err);
    	void (*set_group_by) (IAnjutaSymbolQuery *obj, IAnjutaSymbolField field, GError **err);
    	void (*set_limit) (IAnjutaSymbolQuery *obj, gint limit, GError **err);
    	void (*set_mode) (IAnjutaSymbolQuery *obj, IAnjutaSymbolQueryMode mode, GError **err);
    	void (*set_offset) (IAnjutaSymbolQuery *obj, gint offset, GError **err);
    	void (*set_order_by) (IAnjutaSymbolQuery *obj, IAnjutaSymbolField field, GError **err);
    } IAnjutaSymbolQueryIface;

### enum IAnjutaSymbolQueryDb

    typedef enum {
    	IANJUTA_SYMBOL_QUERY_DB_PROJECT,
    	IANJUTA_SYMBOL_QUERY_DB_SYSTEM
    } IAnjutaSymbolQueryDb;

Sets the database to use for the query. System database is where all system library symbols are found. While project database is where currently open project's symbols are found.

`IANJUTA_SYMBOL_QUERY_DB_PROJECT` | Select project database.
`IANJUTA_SYMBOL_QUERY_DB_SYSTEM` | Select system database.

### enum IAnjutaSymbolQueryFileScope

    typedef enum {
    	IANJUTA_SYMBOL_QUERY_SEARCH_FS_IGNORE,
    	IANJUTA_SYMBOL_QUERY_SEARCH_FS_PUBLIC,
    	IANJUTA_SYMBOL_QUERY_SEARCH_FS_PRIVATE
    } IAnjutaSymbolQueryFileScope;

Defines file scope of symbols to query.

`IANJUTA_SYMBOL_QUERY_SEARCH_FS_IGNORE` | Ignore file scope
`IANJUTA_SYMBOL_QUERY_SEARCH_FS_PUBLIC` | Only public symbols visible to rest of project.
`IANJUTA_SYMBOL_QUERY_SEARCH_FS_PRIVATE` | Only private symbols visible inside a file.

### enum IAnjutaSymbolQueryMode

    typedef enum {
    	IANJUTA_SYMBOL_QUERY_MODE_SYNC,
    	IANJUTA_SYMBOL_QUERY_MODE_ASYNC,
    	IANJUTA_SYMBOL_QUERY_MODE_QUEUED
    } IAnjutaSymbolQueryMode;

This parameter determines the mode of query execution. By default, IANJUTA_SYMBOL_QUERY_MODE_SYNC is selected.

`IANJUTA_SYMBOL_QUERY_MODE_SYNC` | Syncronous query. The result is immediately available as retrun value of search call.
`IANJUTA_SYMBOL_QUERY_MODE_ASYNC` | Asynchronous query. The search call return immediately and result delievered as a signal later. The actual query is done in a separate thread.
`IANJUTA_SYMBOL_QUERY_MODE_QUEUED` | If the database is busy scanning, then the query is performed later when database is ready. It returns NULL and result is delivered through async-result signal. Only query can stay queued, so calling search multiple times would result in only the last one being active.

### enum IAnjutaSymbolQueryName

    typedef enum {
    	IANJUTA_SYMBOL_QUERY_SEARCH,
    	IANJUTA_SYMBOL_QUERY_SEARCH_ALL,
    	IANJUTA_SYMBOL_QUERY_SEARCH_FILE,
    	IANJUTA_SYMBOL_QUERY_SEARCH_IN_SCOPE,
    	IANJUTA_SYMBOL_QUERY_SEARCH_ID,
    	IANJUTA_SYMBOL_QUERY_SEARCH_MEMBERS,
    	IANJUTA_SYMBOL_QUERY_SEARCH_CLASS_PARENTS,
    	IANJUTA_SYMBOL_QUERY_SEARCH_SCOPE,
    	IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE,
    	IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE_FILE
    } IAnjutaSymbolQueryName;

Names of query that defined what kind of query it is.

`IANJUTA_SYMBOL_QUERY_SEARCH` | Query to perform basic substring search.
`IANJUTA_SYMBOL_QUERY_SEARCH_ALL` | Query to get all symbols
`IANJUTA_SYMBOL_QUERY_SEARCH_FILE` | Query to perform substring search in a file.
`IANJUTA_SYMBOL_QUERY_SEARCH_IN_SCOPE` | Query to perform substring search in a scope.
`IANJUTA_SYMBOL_QUERY_SEARCH_ID` | Query to find the symbol of given ID.
`IANJUTA_SYMBOL_QUERY_SEARCH_MEMBERS` | Query to find members of a scope (eg. class).
`IANJUTA_SYMBOL_QUERY_SEARCH_CLASS_PARENTS` | Query to get parents of a class.
`IANJUTA_SYMBOL_QUERY_SEARCH_SCOPE` | Query to find scope name of a file position.
`IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE` | Query to get the parent scope of a symbol.
`IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE_FILE` | Query to get the parent scope of a symbol in the file.

### ianjuta_symbol_query_file_scope_get_type ()

    GType               ianjuta_symbol_query_file_scope_get_type
                                                            (void);

Returns : |

### ianjuta_symbol_query_mode_get_type ()

    GType               ianjuta_symbol_query_mode_get_type  (void);

Returns : |

### ianjuta_symbol_query_name_get_type ()

    GType               ianjuta_symbol_query_name_get_type  (void);

Returns : |

### ianjuta_symbol_query_error_quark ()

    GQuark              ianjuta_symbol_query_error_quark    (void);

Returns : |

### ianjuta_symbol_query_get_type ()

    GType               ianjuta_symbol_query_get_type       (void);

Returns : |

### ianjuta_symbol_query_cancel ()

    void                ianjuta_symbol_query_cancel         (IAnjutaSymbolQuery *obj,
                                                             GError **err);

`obj` : |
`err` : |

### ianjuta_symbol_query_search ()

    IAnjutaIterable*    ianjuta_symbol_query_search         (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH query.

`obj` : | Self
`pattern` : | Search pattern in compliance with SQL LIKE syntax
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_all ()

    IAnjutaIterable*    ianjuta_symbol_query_search_all     (IAnjutaSymbolQuery *obj,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_ALL query.

`obj` : | Self
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_class_parents ()

    IAnjutaIterable*    ianjuta_symbol_query_search_class_parents
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_CLASS_PARENTS query.

`obj` : | Self
`symbol` : | The class symbol whose parents to get.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_file ()

    IAnjutaIterable*    ianjuta_symbol_query_search_file    (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             const GFile *file,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_FILE query.

`obj` : | Self
`pattern` : | Search pattern in compliance with SQL LIKE syntax
`file` : | The file whose symbols are searched.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_id ()

    IAnjutaIterable*    ianjuta_symbol_query_search_id      (IAnjutaSymbolQuery *obj,
                                                             gint symbol_id,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_ID query.

`obj` : | Self
`symbol_id` : |
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_in_scope ()

    IAnjutaIterable*    ianjuta_symbol_query_search_in_scope
                                                            (IAnjutaSymbolQuery *obj,
                                                             const gchar *pattern,
                                                             IAnjutaSymbol *scope,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_IN_SCOPE query.

`obj` : | Self
`pattern` : | Search pattern in compliance with SQL LIKE syntax
`scope` : | The scope inside which symbols are searched.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_members ()

    IAnjutaIterable*    ianjuta_symbol_query_search_members (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_MEMBERS query.

`obj` : | Self
`symbol` : | The symbol whose members to get.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_parent_scope ()

    IAnjutaIterable*    ianjuta_symbol_query_search_parent_scope
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE query.

`obj` : | Self
`symbol` : | The symbol whose parent scope is to be found.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_parent_scope_file ()

    IAnjutaIterable*    ianjuta_symbol_query_search_parent_scope_file
                                                            (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbol *symbol,
                                                             const gchar *file_path,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_PARENT_SCOPE_FILE query.

`obj` : | Self
`symbol` : | The symbol whose parent scope is to be found.
`file_path` : | The file where the parent scope is to be found.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_search_scope ()

    IAnjutaIterable*    ianjuta_symbol_query_search_scope   (IAnjutaSymbolQuery *obj,
                                                             const gchar *file_path,
                                                             gint line,
                                                             GError **err);

Executes IANJUTA_SYMBOL_QUERY_SEARCH_SCOPE query.

`obj` : | Self
`file_path` : | The file where the scope is.
`line` : | The line where the scope is.
`err` : | Error propagation and reporting.
Returns : |

### ianjuta_symbol_query_set_fields ()

    void                ianjuta_symbol_query_set_fields     (IAnjutaSymbolQuery *obj,
                                                             gint n_fields,
                                                             IAnjutaSymbolField *fields,
                                                             GError **err);

Sets the fields of Query.

`obj` : | Self
`n_fields` : | Then number of fields to retrieve.
`fields` : | The fields to retrieve in the query. The array length must be `n_fields`.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_file_scope ()

    void                ianjuta_symbol_query_set_file_scope (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolQueryFileScope filescope_search,
                                                             GError **err);

Sets the filescope search of Query.

`obj` : | Self
`filescope_search` : | The filescope to search.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_filters ()

    void                ianjuta_symbol_query_set_filters    (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolType filters,
                                                             gboolean includes_types,
                                                             GError **err);

Sets the bit mask of symbol type filters. if `include_types` is TRUE, symbols satisfying the given symbol types are selected, otherwise they are excluded.

`obj` : | Self
`filters` : | The mode of query.
`includes_types` : |
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_group_by ()

    void                ianjuta_symbol_query_set_group_by   (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolField field,
                                                             GError **err);

Sets the field with which result of query is grouped. As a result there will be no duplicates of with this field.

`obj` : | Self
`field` : | The field to group results.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_limit ()

    void                ianjuta_symbol_query_set_limit      (IAnjutaSymbolQuery *obj,
                                                             gint limit,
                                                             GError **err);

Sets the limit of Query results. No more than `limit` results are returned.

`obj` : | Self
`limit` : | The limit of query.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_mode ()

    void                ianjuta_symbol_query_set_mode       (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolQueryMode mode,
                                                             GError **err);

Sets the mode of Query.

`obj` : | Self
`mode` : | The mode of query.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_offset ()

    void                ianjuta_symbol_query_set_offset     (IAnjutaSymbolQuery *obj,
                                                             gint offset,
                                                             GError **err);

Sets the offset index of Query results.

`obj` : | Self
`offset` : | Offset of the resultset.
`err` : | Error propagation and reporting.

### ianjuta_symbol_query_set_order_by ()

    void                ianjuta_symbol_query_set_order_by   (IAnjutaSymbolQuery *obj,
                                                             IAnjutaSymbolField field,
                                                             GError **err);

Sets the field with which result of query is ordered.

`obj` : | Self
`field` : | The field to order the result.
`err` : | Error propagation and reporting.

## Signal Details

### The `"async-result"` signal

    void                user_function                      (IAnjutaSymbolQuery *ianjutasymbolquery,
                                                            GObject            *arg1,
                                                            gpointer            user_data)               : Run Last

`ianjutasymbolquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

IAnjutaSymbolManager, IAnjutaSymbol