[pyddr-discuss] Query setup

[Frank Foeth]

Hi Pavel,

I made somewhat detailed notes on how we could do the query. If you
don't react, I'll probably implement the structural parts, as I expect
I'll need them anyway.

Yours,

Frank
-------------- next part --------------
Basic query design

Problem: Design a query structure

Angles:
1. Suitable for interfacing from / in the style of  pydance.
2. Queries have to be editable.
3. Queries have to be useful for both developers and players.
4. The user should not be confronted with parameter level data every time he uses
   a query.
5. As it would be advantageous to run an inbetween version of the query to count
   the resulting number of dances or songs while editing, 
   queries should run quite quickly.
6. Queries should support all song and dance weeding functionality in the program.
7. Every parameter is unique, every song and dance has at most one value for each
   parameter.

Queries also should be copyable or cloneable.

Main obstacle:
To make queries useful to developers, they should support complex logic structures.
To build a clear interface, they should NOT support complex logic structures.

My way around this:
1. A query should be reuseable in other queries.
2. A query should consist of three levels:
   - OR-level, this is the top level,
     test given queries and AND-level results in ... OR ... OR ... fashion.
   - AND-level, 
     test given queries and statements results in ... AND ... AND ... fashion.
   - Statements, which test equalities or being in a range depending on the 
     parameters. (In practice this will be a bit more complex.)
3. NOT should be allowed to precede any statement or query.

The above allows full first order logic above statement level, that is if you take the trouble to define a multitude of named queries.

Unfortunately, this is where the query problem stops to be easy.

QUERIES

To prevent and internal endless loops (Query A requires results from B and visa versa), "parents" of queries should not be able to call on their "children" (where parent is part of the child).

Queries should have a descriptor:
System - queries that a user should not get access to.
Fixed  - special queries that cannot be changed with the user's interface.
Default- queries that can be edited, but not deleted, instead they return to a 
         default state.
Custom - user is free to make, edit and delete these at will.

In order to reuse queries they need to be named.
In order for a player to use them effectively they need a description.

A user cannot assign a name to a query which is already taken by a system parameter.

STATEMENTS

To make queries execute fast, statements should be tagged, so they can be executed in an advantageous order. Perhaps the query should execute at a level anyway.
Levels:
System - the user should not be aware of their existence (e.g. game, mode)
Song   - basically data in SongItems
Dance  - data at dance level (like # jumps, etc.)
(Dance level info is currently not available)

If information is available on likely song/dance item quantities remaining after executing a statement, this could be used to speed up the query evaluation. As statements results are evaluated at AND level, the statements with most false evaluations should come first.

Allow only one statement per parameter (this means the statement can use the parameter's id). This also means the statement should have the following states:
USE    - return evaluation result on execution
NEGATE - return NOT (evaluation result)
IGNORE - return true (in fact, these should be removed from the evaluation list.)

A specialised statement class could be used to wrap query results, so NOT query is possible (and 'ignore' too). 

Possible statements for the various parameter classes, see parameters.

PARAMETERS

To describe dance complexity both difficulty and level are used, so complexity is in fact a compound parameter.
So insert a special parameter class called Compound. Compounds should be evaluated before ordinary parameters, but their contents should appear in the interface as the individual parameters of which it consists.

Parameters should have a help text attached.

Parameters come in three (possibly two) classes:
- UNSTRUCTURED, these cannot be sorted, yet although countable, they may not have 
                a finite number of values.
- NUMERICAL,    trivial.
- SORTABLE,     values are countable, sortable, may not be finite. 
                Specified sorting key is needed though.

For unstructured data the only possible statements are equality and IN SET. To limit the number of statements to one, the latter should be used.

As in a computer all sane values (so don't include INF, etc.) are bounded, all evaluations in sorted data can be expressed as min <= x.parameter <= max . So only one statement is necessary per parameter.

INTERFACE

At the application level of what is now gameselect, the user should be allowed to execute one (locally) chosen query when moving to songselect, endless, etc. This query is always executed at DANCE level.

In a separate window (akin to the song config options interface) the user should be allowed to either:
1. name a new query and start composing it from scratch
2. edit an existing query
3. copy a query to a new name
4. delete a query
(In the first version I propose to force stupid names like CUSTOM12.)
This window is the EDIT-MENU

The user should be allowed to see how many songs/dances remain after his query is executed while editing the query.

To limit the size of the collection of songs/dances quickly, and to promote use of known queries, the user should first define the OR list. (OR-WINDOW)