query_system.docbook

linux下的sourceinsight

<sect1 id="queries">
<title>The Query System</title>

<para>
The most important task of &kapp; is to execute <application>Cscope</application> queries and display their results. Queries are always performed on the cross-reference database of the active project.
</para>
<para>
&kapp; currently supports the following query types:
<itemizedlist>
<listitem><para>Find all references to a symbol</para></listitem>
<listitem><para>Find a symbol's global definition</para></listitem>
<listitem><para>Find all functions called by a given function</para></listitem>
<listitem><para>Find all functions calling a given function</para></listitem>
<listitem><para>Find a text string</para></listitem>
<listitem><para>Find an EGrep pattern (regular expression)</para></listitem>
<listitem><para>Find a file's path by its name</para></listitem>
<listitem><para>Find all files including a given file</para></listitem>
<listitem><para>Display a call-tree for a given function</para></listitem>
</itemizedlist>
A symbol, as referred to in the above list, may be a function, a global variable, a structure, a union or a type definition.
</para>

<para>
The cross-reference database may become obsolete when source files are modified, resulting in inaccurate (or simply wrong) query results. &kapp; has two ways for refreshing the database, manual and automatic. Manual database rebuilds are available through the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Rebuild Database</guimenuitem></menuchoice> menu command. Selecting this command will instruct Cscope to immediately rebuild the cross-reference database.
</para>

<para>
Automatic database rebuilds are enabled per-project, an option controlled by the <guilabel>Project Properties</guilabel> dialogue. Since a database rebuild may be a time and resource-consuming operation, &kapp; does not invoke this procedure after every change to the source code. Instead, changes to the code initiate a timer (whose value is determined by the user in the <guilabel>Project Properties</guilabel> dialogue). Once this timer elapses, &kapp; instructs Cscope to rebuild the database. Code modifications that occur while the timer is running reset its value.
</para>

<para>
A project's database is also updated whenever that project is opened.
</para>

<sect2 id="query-run">
<title>Running a Query</title>

<para>
A query can be started in one of three ways:
<orderedlist>
<listitem><para>The main menu</para></listitem>
<listitem><para>Keyboard shortcuts</para></listitem>
<listitem><para>The editor's context-menu</para></listitem>
</orderedlist>
</para>

<para>
To start a query from the main menu, select the desired query type from the <guimenu>Cscope</guimenu> menu. This will display a dialogue box prompting you for the query's text. The text to enter depends upon the query's type.
<screenshot>
<screeninfo>The query dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="query_dlg.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The query dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<variablelist>
<varlistentry>
<term><guilabel>Type</guilabel></term>
<listitem><para>The type of query to perform. This value defaults to the requested type, by can be changed by selecting a different entry in the list.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Symbol</guibutton></term>
<listitem><para>Enter the symbol to query in this box. The default value is the symbol currently under the editor's cursor (if any).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Search for a Sub-String</guilabel></term>
<listitem><para>Mark this check-box to treat the entered text as part of a symbol (will query all symbols containing the entered text as a sub-string).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para><action>Runs the query.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Hint</guibutton></term>
<listitem><para><action>Provides a list of possible matches to the entered symbol.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without running the query.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Suggested Symbols</guilabel></term>
<listitem><para>A list of known symbols matching the text in the symbol box.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hint Options</guilabel></term>
<listitem><para>These buttons affect the way text in the symbol box is matched to fill the suggested symbols list.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Symbols Beginning With...</guilabel></term>
<listitem><para>Choose this option to match symbols starting with the given text.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Symbols Containing...</guilabel></term>
<listitem><para>Choose this option to match symbols containing the given text.</para></listitem>
</varlistentry>
</variablelist>

<para>
Any text selected in the editor when a query is requested will be automatically copied to the query dialogue. If no text is selected, KScope attempts to guess the requested symbol from the current location of the cursor.
</para>

<para>
Each menu item is associated with a keyboard shortcut. These shortcuts follow the convention of using the <keycap>Ctrl</keycap> key, together with the numeric query index used by <application>Cscope</application> (this should allow experienced <application>Cscope</application> users to get quickly acquainted with &kapp;). For example, use <keycombo><keycap>Ctrl</keycap><keycap>1</keycap></keycombo> to look-up a symbol's definition. The call-tree is an exception to this convention (as it is not a native <application>Cscope</application> query). See the <link linkend="commands">Command Reference</link> for a complete listing of all menu and shortcut options.
</para>

<note>
<para>
The EGrep query is invoked using <keycombo><keycap>Ctrl</keycap><keycap>5</keycap></keycombo>, as <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo> is already used by &kate;.
</para>
</note>

<para>
The third way of starting a query is by right-clicking inside an editor window. This invokes the context-menu, that displays the same options as in the <guimenu>Cscope</guimenu> section of the main menu. Using a context-menu is easy when combined with a symbol selection in the editor: position the text cursor inside a symbol, and then right click to display the context-menu.
</para>

<para>
A query may take some time to complete, depending on its type and the size of the project. &kapp; displays a progress indicator during long queries. If <application>Cscope</application>'s <option>-v</option> command line option is used, this progress indication is accurate, and displays the percentage of files already searched in. In case this option was omitted (e.g., if working with a version of <application>Cscope</application> prior to 15.5), &kapp; will present a dummy progress bar, used simply to indicate that a query is running, and that &kapp; has not frozen. Please refer to the section <link linkend="configuration">Configuring &kapp;</link> for more information.
</para>

</sect2>

<sect2 id="query-window">
<title>The Query Results Window</title>

<para>
When a query has terminated, its output is displayed in the query window, at the bottom of &kapp;'s main window. This window can manage several result pages simultaneously, with each page holding the results of a different query. Each page is associated with a tab that displays a summary of the query that generated these results. This tab is used to bring the results page forward, and is also associated with several page operations through a close button and a context menu.
</para>

<para>
By default, query results are displayed in the currently active page, overriding any prior contents. To keep a results page unchanged, the page needs to be "locked". Locked query pages are never overridden. The contents of these pages are also saved when the project is closed, and are restored when the project is reopened. To lock a project, either click the <guibutton>Lock/Unlock Query</guibutton> toggle button to the right of the query window, or use the context menu (available by right-clicking the page's tab.) The same methods can also be used to unlock a query.
</para>

<para>
New query pages can also be created explicitly, by using either the <guibutton>New Query</guibutton> button to the right of the query window, or the context menu available by right-clicking the tab area of the query window.
</para>

<para>
Each entry in a query results page represents a symbol or text string that complies to the search criteria. The entry is composed of four sections:
<itemizedlist>
<listitem><para>The path of the file in which the symbol or string were found</para></listitem>
<listitem><para>The name of the function containing the symbol or text string</para></listitem>
<listitem><para>The line number in this file</para></listitem>
<listitem><para>The text of this line</para></listitem>
</itemizedlist>
</para>

<para>
By default, results are sorted according to the file name. This can be changed by clicking the column headers of the results list.
</para>

<para>
The entries in a query results page can be used as shortcuts to editing the line in which the symbol or text string were found (or lines in that vicinity.) This is done by either double-clicking a result entry, or by selecting this entry and hitting the <keycap>Enter</keycap> key. As a result, &kapp; will open an editor window displaying the file referred to in the selected entry, and set the cursor to the beginning of the appropriate line.
</para>

<para>
If a query results in a single entry, this entry is automatically selected for display.
</para>

<para>
The results of a query can be refreshed by clicking the <guibutton>Refresh Query</guibutton> button to the right of the query window, or by using the context menu. This command is useful to rerun queries after the database has changed (such as after a <guimenuitem>Rebuild Database</guimenuitem> command had been issued).
</para>

<para>
Query results pages can be closed by either clicking the icon on their tab, by clicking on the <guibutton>Close Query</guibutton> button to the right of the query window, by using the context menu (available by right-clicking the page's tab), or by selecting the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Close Query</guimenuitem></menuchoice> main-menu command.
</para>

<para>
If the query window is not visible when a query is executed, it is temporarily displayed, and then re-hidden when the user selects an entry for viewing.
</para>

</sect2>

<sect2 id="result-options">
<title>Query Results Options</title>

<para>
Right-clicking a query result in either a query window or a call-tree dialogue displays a context menu. This menu includes several actions that can be used to either extract information or fine tune these results.
</para>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy File</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the file path part of a result record to the clipboard</action> (the copy commands are available depending on the position of the mouse cursor).</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Function</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Line</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the line number part of a result record.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Text</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Filter...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the Filter Query Results dialogue.</action> See the section <link linkend="filter-results">Filtering Query Results</link> for a detailed description of this option.</para></listitem>