Introduction

xmbase-grok was born as ``grok'', but the name was changed later to this more descriptive variation. It is a simple desktop database manager, intended to manage small databases such as phone lists, diaries, todo lists, URL lists, etc. A user interface builder is integrated in grok to allow customization of the presentation of the data in the main window. A variety of user interface elements such as text entry fields, checkbuttons, function buttons, and bar charts ca be placed in the database-dependent part of the main window, called the card. grok comes with a selection of pre-built applications.

The database itself is organized in a table with rows and columns of strings. A card presents one row of the database. For example, the phone list stores one person per row, with various columns for name, address, phone number, and so on.

In addition top the card, the main window also displays a scrollable summary listing containing one line per card, allowing fast lookup of cards. Pressing on a line in the summary puts the corresponding row into the card part of the window. The main window also contains controls for searching of cards, and for adding and deleting cards. There are several methods for searching: by keyword, using the built-in query language, or using customizable standard queries.

From the command line, grok can be started as grok with no arguments. This will bring up an empty card; a database must then be chosen from the Database pulldown. The database to load can be specified on the command line, such as grok phone.

The -t, -T, and -p options allow queries printed to stdout, without starting the interactive graphical user interface. Queries may use simple keyword lookups, or may use the query language:

     grok -t phone thomas
     grok -t todo '({_status == "t"} && {_assigned == user})'

For details on the query language used in the second example, refer to the ``Expression Grammar'' chapter. The first example looks for the given keyword; case distinctions are ignored. The author of the application controls which columns of the database are searched for keywords. Note the single quotes enclosing the query to protect blanks, parentheses, and double quotes from the shell.

grok supports the following command-line options: grok [options] [database ['query']]

• -h
  print a short usage message listing the available options.

• -d
  print the default X resources to stdout and exit. The output can be appended to the local ~/.Xdefaults file or other resource files, after changes to customize grok's behavior.

• -v
  
  print the version number of grok.

• -t
  Perform query and print the matching cards to stdout. If query is missing, print all cards. The database argument is mandatory for -t and -T.

• -T
  Same as -t, but omit the header line. This is useful when the result is piped to other Unix utilities.

• -p
  Perform query and print the matching cards to stdout, in a format understood by the plan calendar program, version 1.9 or higher. If query is missing, use the Shown in calendar if expression defined by the database's form editor. If that expression is undefined too, print all cards. The database argument is mandatory for -p.
• -f
  Do not fork on startup. This is mainly a debugging tool; it prevents grok from putting itself into the background.

• -r
  Restricted grok. The form editor is disabled to prevent inexperienced users from inadvertently starting the user interface builder (called the ``form editor'') and modifying the current database format. The same effect can be achieved by linking grok to rgrok; running rgrok has the same effect as running grok -r.

The Main Window

When grok is started, it presents a four-part window: a search area for entering keywords and query expressions, the summary, the card, and a row of buttons for creating, deleting, and modifying cards. There is also a menu bar with pulldown menus.

When grok is started up without arguments, it is first necessary to choose the database to display from the Database pulldown. This pulldown presents all files in the ~/.grok directory that end with the extension .gf, with the extension removed. (If a new database is created, it is not necessary to choose a database, see next chapter.) Sometimes, the Database pulldown shows some databases more than once. The reason is usually that the database is found in two different places or using different paths; the duplicates can be eliminated by enabling the ``Don't show duplicate databases'' in the preferences menu available under the ``File'' pulldown.

The next step is choosing a section of the database. Not all databases have section; if the Section pulldown in the menu bar is grayed out, this step can be omitted. grok normally loads its string table containing the cards from a file ending with the extension .db, usually with the same directory and root name as the .gf file. If this .db file is a directory, grok recursively loads all files ending with .db in this directory, and combines them into one database in memory. Each file becomes a section. By default, all sections are displayed after loading a database, but the Section pulldown allows restricting the summary listing to a single section (file). To create a new section, choose ``New...'' in the Section pulldown; if the database did not have sections until now all its cards are put into the new section. Otherwise, the new section is created empty. There is no way to delete sections, other than using a shell to delete the file named sectionname.db in the database directory.

The main window now displays all cards in the chosen database, or section of the database if chosen, in the summary listing. To display any card listed in the summary, press on this line. The card appears in the bottom part of the window and can now be edited (unless the database file was read-only, or the application author has restricted write access). Text entry fields normally have a pink background; read-only text fields have a gray background.

There is a special multi-line version of text entry field called a note, which always has a gray background regardless of its writable status. On some systems it is necessary to press in the upper left corner of the inset area, or on already existing text to get a cursor.

Below the card, there are buttons to skip to the next or previous card, to create a new card (New), to duplicate the currently displayed card, or to delete the currently displayed card. New cards may be created with defaults specified by the application designer. If the database has sections, there is an additional buttons that moves the card into a different section.

The Search text entry field near the top of the window allows entry of a search string. Case is not significant. The entire string is searched for; the number of blanks and punctuation is significant. The search string is not a sequence of keywords. This type of search is equivalent to what the Unix command fgrep -i does.

More sophisticated queries can be performed by entering a query expression beginning with ( or {. For a description of the syntax and the difference between parenthesized and braced expressions, the the ``Expression Grammar'' chapter. To get a feel for expressions, enable ``Show query search expressions'' in the preferences menu and choose a canned query from the ``Query'' pulldown. The query expression will be shown in the Search text field and can then be edited there.

The Query pulldown always begins with the ``All'' choice that puts all cards in the database, or all cards in the current section if one was selected with the Section pulldown, into the summary listing. The application designer may predefine canned queries (using the ``Queries'' button in the form editor) that appear in the Query pulldown.

The File pulldown has a ``Print...'' choice that pops up the printing menu. It allows selecting the cards to print, the output format, the output quality, and the output device. Medium quality uses overstrike Ascii to simulate boldfacing and underlining as supported by many programs such as more and most printer drivers. It uses character-backspace-character or underbar-backspace-character sequences to highlight field names and header lines.

When a database is changed, the changes are not immediately written to the database file (with the .db extension). It is written when ``Save'' or ``Quit'' in the File pulldown is chosen, or when a new database is chosen from the Database pulldown. Under mwm-based window managers, double-clicking the top left corner button in the window decoration also saves, but there may be window managers that do not support the necessary WM protocols for this. The status line below the search text field displays ``(modified)'' if the database has been changed but not written back.

Note that grok does not attempt to sequence database accesses. It does not protect databases against simultaneous accesses. Although standard file locking is used during read and write operations (which may or may not work across NFS), nobody stops two users from reading the same file, then both modifying it, and writing it back; one of the two changes will be lost.

A useful feature is the ``Current database'' choice in the Help pulldown. It lists all known information about the current database, including the names and paths of all loaded files and their sizes.

In case of trouble, it is strongly recommended to read the other help texts available under the Help pulldown, especially the ``Troubleshooting'' section. The Help pulldown will only work if the grok.hlp file is installed in the directory specified in the GLIB macro in the Makefile (Imakefile, or Makefile.alt), by default /usr/local/lib.