Solar Car Power Management

Query Language

© 1996
Paul Vincent Craven
All Rights Reserved


Originally the Power Management System was designed to have many available graphs and tables hard-coded into the program. Unfortunately it is impossible to foresee every possible need that the user would have in viewing data. Therefore confining the user to predefined tables and graphs is unwise. In order to give to the user the analytical power that he or she needs, the power management system needs to be able to create the graph dynamically. The UMR Power Management System provides this by including a query language.

The query language for the data windows is built upon a Context Free Grammar (CFG). A CFGCFG is a formal syntax specification for a language. With the rules defined by the CFG, one may determine if a given input is valid by whether or not it can be created by the CFG.

Lexical analysis of the code is done by a tool called FlexFlex, made publicly available by the GNUGNU General Public License, courtesy of the Free Software Foundation. Flex is an improvement on a tool originally known as lex, which performed the same function. One of the largest improvements of Flex was good documentation [9]. Originally lex had little, if any, documentation. Documentation for this tool and yacc is also available from O'Reilly & Associates [3]. Most of the understanding of theory of how a parser and lexer work I got from the textbook for our compiler's class [2].

FlexFlex takes the input stream, in this case the text from the query dialog, and searches for tokens. A token is one of the keywords in the query specification held in the query.l file. Flex takes this file and creates C code to do the lexical analysis. Tokens are matched without respect to case sensitivity. For instance, "CReATe GRapH" returns the same two tokens (CREATE and GRAPH, respectively) as "create graph" does.

Code to parse the query is created using a program from GNUGNU called BisonBison. Bison is an enhancement of a program called YACC, which has been in the software world for a relatively long time. YACC stands for Yet Another Compiler Compiler. Both of these tools take a CFGCFG and create C code that can parse it. Bison is a very useful tool when creating source code that interprets or translates other source code. It also includes good documentation [10].

BisonBison works in conjunction with FlexFlex. Flex searches through the text, matches tokens, and converts token values such as strings and integers into a native format. Bison repetitively calls the yylex( ) function defined by the Flex tool, which returns a token value. A typical example of the first five calls to yylex( ) would return CREATE, GRAPH, WITH, ATTRIBUTES, and finally a ":". The colon, equals, number values, string values, and color values are all tokens in themselves. Figure 17 shows an example query dialog box, a full example query specification and the resulting graph are shown in figures 19 and 21 respectively.

Figure 18 shows an abbreviated specification of the data structure that holds the graph information. This structure is created when the user's code is interpreted by yyparse( ). Once the user's input is fully parsed and the data structure is filled out, a graph object is created with a reference to the new data structure. The graph uses the information in the data structure to create the graph, and does not do any parsing itself.

Displayed in figure 20, is a shortened specification of the grammar used in the creation of the graph. This is the grammar that is given to Bison, which creates the C code to parse it. Most of the grammar has been omitted in this figure for reasons of space, and because it is quite repetitive.



Figure 17: Query Dialog


Bison creates code based on the grammar and actions specified in the query.y file. This code then scans tokens and performs the actions, Bison's specifications are a CFG, which can have C code attached to each rule. So when the CFG matches the rule MAINATTRIBUTES TITLE_LABEL '=' STRING with the following input:

title_label = "Total solar power"

BisonBison knows to create a character string with "Total Solar Power" in it, and assign the character pointer in the graph structure to that string. It knows that it is incorrect to assign an integer to a title label, since we specify a string in the rule.

To take the data specified in the query and actually create the table or graph, we fill in a data structure that specifies how the window should look. The data structure is created with a set of default values which the query can override. The data structure has a set of attributes for the main data window, and then a chain of structures that specify how each data item should appear.

SPECIFICATIONS OF THE POWER MANAGEMENT QUERY LANGUAGE CONSTRUCTION:

Create: This command creates a graph window or table window. It is necessary to follow the create command with either "table" or "window" depending on which the user wants to create.

With: This command must follow "create", which is defined above. By specifying "with attributes:" the user can change the default attributes on the graph. Specifying "with data:" adds more data items to the graph or table being created.

VALUE TYPES:

Integers: Integers are numbers with no decimal points, and can be of any value.

Float: Floating point numbers.

String: String of characters, enclosed by quotation marks.

Color: Color value in a red, green blue format. This is specified in the form: R[0-255]G[0-255]B[0-255]. Example: R255G255B255 is white, and R0G0B0 is black.

Style: Possible values are: normal, bold, italic, bold_italic, and underline.

WINDOW ATTRIBUTE OPTIONS:

Window_title: string. Allows the user to specify the text that appears in the title bar of the data window. Default value is "Generic Window Title".

Pen_size: integer. Default pen size for window drawing. Controls axis width and table dividing line width. Default is a width of one.

Title_label: string. Label displayed at the top of the graph. Default is no label.

Title_font: string. Font name used to draw the title. Default is "Arial".

Title_size: integer. Size of the font used to draw the title. Default is 12.

Title_style: style. Style of the font used to draw the title. Default is Normal.

Title_color: color. Color of the font used to draw the title. Default is black.

Title_top: integer. Pixel value of where to start the title. Pixel origin is the upper left corner.

Title_left: integer. Pixel value of where to start the title. Default is 0.

Title_right: integer. Pixel value of where to end the title. Default is 100.

Title_bottom: integer. Pixel value of where to end the title. Default is 15.

Xunit_font: string. Font name used to draw the numbers on the x-axis. Default is "Arial".

Xunit_size: integer. Size of the font used to draw the numbers on the x-axis. Default is 10.

Xunit_style: style. Style of the font used to draw the numbers on the x-axis. Default is Normal.

Xunit_color: color. Color of the font used to draw the numbers on the x-axis. The default is black.

Yunit_font: string. Font name used to draw the numbers on the y-axis. The default is "Arial"

Yunit_size: integer. Size of the font used to draw the numbers on the y-axis. Default is 10.

Yunit_style: style. Style of the font used to draw the numbers on the y-axis. Default is Normal.

Yunit_color: color. Color of the font used to draw the numbers on the y-axis. Default is black.

Margin_top: integer. Top margin in pixels. Default of 10.

Margin_left: integer. Left margin. Default of 40.

Margin_right: integer. Right margin. Default of 10.

Margin_bottom: integer. Bottom margin. Default of 20.

Yaxis_label: string. Label displayed along the y-axis. Default is no label.

Yaxis_font: string. Font name used to draw the label on the y-axis. Default is "Arial".

Yaxis_size: integer. Size of the font used to draw the y-axis. Default size is 12.

Yaxis_style: style. Style of the font used to draw the y-axis. Default is Normal.

Yaxis_color: color. Color of the font used to draw the y-axis. Default is black.

Yaxis_top: integer. Pixel value of where to start the y-axis label. Pixel origin is the upper left corner.

Yaxis_left: integer. Pixel value of where to start the y-axis.

Yaxis_right: integer. Pixel value of where to end the y-axis.

Yaxis_bottom: integer. Pixel value of where to end the y-axis.

Yaxis_label: string. Label displayed along the y-axis. Default is no label.

Xaxis_font: string. Font name used to draw the label on the x-axis. Default is "Arial".

Xaxis_size: integer. Size of the font used to draw the x-axis.

Xaxis_style: style. Style of the font used to draw the x-axis.

Xaxis_color: color. Color of the font used to draw the x-axis.

Xaxis_top: integer. Pixel value of where to start the x-axis label. Pixel origin is the lower left corner.

Xaxis_left: integer. Pixel value of where to start the x-axis.

Xaxis_right: integer. Pixel value of where to end the x-axis.

Xaxis_bottom: integer. Pixel value of where to end the x-axis.

Auto_scale: integer. Set to true or false (they are converted into proper integer values). If true, the graph will automatically adjust the minimum and maximum Y values of the graph to fit all data. Default is true.

Min_y: integer/float. Applicable only to graphs. Minimum y value of the graph, can be overridden by the program if the auto scale value is set to true. Default value is 0.

Max_y: integer/float. Applicable only to graphs. Maximum y value of the graph. Default value is 10.

  1. DATA ITEM OPTIONS:

Label: string. Used with data items. Specifies the label for the data element. This label is used as the descriptor in tables, and in the legend of graphs, if applicable.

Color: color. Color of the current data item. Used to color the line in a graph or the font and value in a table.

Pen_size: integer. Thickness of the data item's line in a graph.

Function: string. This string is passed to the graphing class. Currently the graphing class supports input in the form of numbers which represent the placement of the data in the data packet, starting from 0. Default value is "1", or displaying the second data packet value.


/* Information for a Data set */

struct query_data_struct {

        query_data_struct *next;

        char            *label;
        char            *function; /* Function Expression */
        color_struct    color;  /* RGB format */
        int             pen_size;
};


struct query_struct {

        query_data_struct *first_data_set;

        int            type;    /* Graph or Table */

        color_struct   color_bg;/* RGB format */
        color_struct   color_fg;

        char          *window_label;

        char            *title_label;
        char            *title_font;
        int              title_size;
        FontStyles     title_style;
        color_struct   title_color;
        int            title_top;
        int            title_bottom;
        int            title_left;
        int            title_right;

        char            *xaxis_label;

        [Etc, etc.]
        int            time_width;
        time_t         ending_time;
        time_t         last_time;

        int            auto_update;
        int            pen_size;

        int            left_margin;
        int            bottom_margin;
        int            top_margin;
        int            right_margin;

        /* Applicable to graphs only */
        double         min_y;
        double         max_y;
        int            auto_scale;

        int            scroll_rate;
        int            time_gap;

};

};


Figure 18: Data Structure

/* Information for a Data set */

struct query_data_struct {

        query_data_struct *next;

        char            *label;
        char            *function; /* Function Expression */
        color_struct    color;  /* RGB format */
        int             pen_size;
};


struct query_struct {

        query_data_struct *first_data_set;

        int            type;    /* Graph or Table */

        color_struct   color_bg;/* RGB format */
        color_struct   color_fg;

        char          *window_label;

        char            *title_label;
        char            *title_font;
        int              title_size;
        FontStyles     title_style;
        color_struct   title_color;
        int            title_top;
        int            title_bottom;
        int            title_left;
        int            title_right;

        char            *xaxis_label;

        [Etc, etc.]
        int            time_width;
        time_t         ending_time;
        time_t         last_time;

        int            auto_update;
        int            pen_size;

        int            left_margin;
        int            bottom_margin;
        int            top_margin;
        int            right_margin;

        /* Applicable to graphs only */
        double         min_y;
        double         max_y;
        int            auto_scale;

        int            scroll_rate;
        int            time_gap;

};


Figure 19: Example Query

Figure 21: Output of sample query