11.3.9 ask_query/4   hookable

Synopsis

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

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.

Arguments

QueryClass

term, must be nonvar

Determines the allowed values for the atom Answer.

Query

term

A message term.

Help

term

A message term.

Answer

term

See QueryClass

Description

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.

Exceptions

instantiation_error

QueryClass, Query, or Help uninstantiated.

type_error

QueryClass not an atom.

domain_error

QueryClass not a valid query class.

See Also

Query Processing.