8.13.4 Query Handling Predicates

ask_query(+QueryClass, +Query, +Help, -Answer) hookable

Prints the question Query, then reads and processes user input according to QueryClass, and returns the result of the processing, the abstract answer term Answer. The Help message may be printed in case of invalid input.

All queries made by the system are handled by calling this predicate.

First ask_query/4 calls query_hook/6 with the same arguments plus the Query and Help arguments converted to format-command lines. If this call succeeds, then it overrides all further processing done by ask_query/4. Otherwise, the query is processed in the following way:

• Preparation phase: The parameters of the query processing, defined by QueryClass (Prompt, InputMethod, MapMethod and FailureMode) are retrieved using the four step procedure described above. That is, the following alternatives are tried:
  • user:query_class_hook/5;
  • 'SU_messages':query_class/5;
  • the built-in copy of query_class/5.
• Input phase: The user is prompted with Prompt, input is read according to InputMethod, and the result is returned in RawInput.

  The four step procedure is used for performing this phase, the predicates tried are the following:

  • user:query_input_hook/3;
  • 'SU_messages':query_input/3;
  • the built-in copy of query_input/3.
• Mapping phase: The RawInput returned by the input phase is mapped to the Answer of the query. This mapping is defined by the MapMethod parameter, and the result of the conversion is returned in Result, which can be:
  • success—the mapping was successful, Answer is valid;
  • failure—the mapping was unsuccessful, the query has to be repeated;
  • failure(Warning)—same as failure, but first the given warning message has to be printed.

  The four step procedure is used for performing this phase, the predicates tried are the following:

  • user:query_map_hook/4;
  • 'SU_messages':query_map/4;
  • the built-in copy of query_map/4.

  If the mapping phase succeeds, then ask_query/4 returns with the Answer delivered by this phase.

• If the mapping does not succeed, then the query has to be repeated. If the Result returned by the mapping contains a warning message, then it is printed using print_message/2. FailureMode specifies whether to print the help message and whether to re-print the query text. Subsequently, the input and mapping phases are called again, and this is repeated until the mapping is successful.

query_hook(+QueryClass, +Query, +QueryLines, +Help, +HelpLines, -Answer) hook

user:query_hook(+QueryClass, +Query, +QueryLines, +Help, +HelpLines, -Answer)

Called by ask_query/4 before processing the query. If this predicate succeeds, it is assumed that the query has been processed and nothing further is done.

query_class_hook(+QueryClass, -Prompt, -InputMethod, -MapMethod, -FailureMode) hook

user:query_class_hook(+QueryClass, -Prompt, -InputMethod, -MapMethod, -FailureMode)

Provides the user with a method of overriding the call to 'SU_messages':query_class/5 in the preparation phase of query processing. This way the default query class characteristics can be changed.

'SU_messages':query_class(+QueryClass, -Prompt, -InputMethod, -MapMethod, -FailureMode) extendible

Returns the parameters of the given QueryClass:

• Prompt - an atom to be used as prompt;
• InputMethod - a ground term, which specifies how to obtain input from the user;
• MapMethod - a ground term, which specifies how to process the input to get the abstract answer to the query;
• FailureMode - an atom determining what to print in case of an input error, before re-querying the user. Possible values are:
  • help_query - print the help message and print the query text again;
  • help - only print the help message;
  • query - only print the query text;
  • none - do not print anything.

For the list of default input- and map methods, see the “Default Input Methods” and “Default Map Methods” subsections in Query Processing.

'SU_messages':query_abbreviation(+QueryClass, -Prompt, -Pairs) extendible

This extendible predicate provides a shortcut for defining query classes with some fixed characteristics, where

• QueryClass is the query class being defined;
• Prompt is the prompt to be used;
• Pairs is the list of pairs defining the characters accepted and the corresponding abstract answers.

This defines a query class with the given prompt, the line input method, the char(Pairs) map method and help_query failure mode. The predicate is actually implemented by the first clause of 'SU_messages':query_class/5:

          query_class(QueryClass, Prompt, line,
                      char(Pairs), help_query) :-
                  query_abbreviation(QueryClass, Prompt, Pairs), !.
     

query_input_hook(+InputMethod, +Prompt, -RawInput) hook

user:query_input_hook(+InputMethod, +Prompt, -RawInput)

Provides the user with a method of overriding the call to 'SU_messages':query_input/3 in the input phase of query processing. This way the implementation of the default input methods can be changed.

'SU_messages':query_input(+InputMethod, +Prompt, -RawInput) extendible

Implements the input phase of query processing. The user is prompted with Prompt, input is read according to InputMethod, and the result is returned in RawInput.

See Query Processing, for details.

query_map_hook(+MapMethod, +RawInput, -Result, -Answer) hook

user:query_map_hook(+MapMethod, +RawInput, -Result, -Answer)

Provides the user with a method of overriding the call to 'SU_messages':query_map/4 in the mapping phase of query processing. This way the implementation of the default map methods can be changed.

'SU_messages':query_map(+MapMethod, +RawInput, -Result, -Answer) extendible

Implements the mapping phase of query processing. The RawInput, received from query_input/3, is mapped to the abstract answer term Answer. The mapping is defined by the MapMethod parameter, and one of the terms success, failure and failure(Warning), describing the result of the conversion is returned in Result.

See Query Processing, for details.