Did you know ... Search Documentation:
Predicate phrase/3
Availability:built-in
Sourcephrase(:DCGBody, ?List, ?Rest)
True when DCGBody applies to the difference List/Rest. Although DCGBody is typically a callable term that denotes a grammar rule, it can be any term that is valid as the body of a DCG rule.

The example below calls the rule set integer//1 defined in section 4.13 and available from library(library(dcg/basics)), binding Rest to the remainder of the input after matching the integer. 

?- [library(dcg/basics)].
?- atom_codes('42 times', Codes),
   phrase(integer(X), Codes, Rest).
X = 42
Rest = [32, 116, 105, 109, 101, 115]

The next example exploits a complete body. Given the following definition of digit_weight//1 , we can pose the query below. 

digit_weight(W) -->
        [D],
        { code_type(D, digit(W)) }.
?- atom_codes('Version 3.4', Codes),
   phrase(("Version ",
           digit_weight(Major),".",digit_weight(Minor)),
          Codes).
Major = 3,
Minor = 4.

The SWI-Prolog implementation of phrase/3 verifies that the List and Rest arguments are unbound, bound to the empty list or a list cons cell. Other values raise a type error.85The ISO standard allows for both raising a type error and accepting any term as input and output. Note the tail of the list is not checked for performance reasons. The predicate call_dcg/3 is provided to use grammar rules with terms that are not lists.

Note that the syntax for lists of codes changed in SWI-Prolog version 7 (see section 5.2). If a DCG body is translated, both "text" and `text` is a valid code-list literal in version 7. A version 7 string ("text") is not acceptable for the second and third arguments of phrase/3. This is typically not a problem for applications as the input of a DCG rarely appears in the source code. For testing in the toplevel, one must use double quoted text in versions prior to 7 and back quoted text in version 7 or later.

See also portray_text/1, which can be used to print lists of character codes as a string to the top level and debugger to facilitate debugging DCGs that process character codes. The library library(apply_macros) compiles phrase/3 if the argument is sufficiently instantiated, eliminating the runtime overhead of translating DCGBody and meta-calling.

Tags are associated to your profile if you are logged in
Tags:
LogicalCaptain said (2020-07-01T09:09:08):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

Example

:- use_module(library(dcg/basics)).
:- begin_tests(dcg).

% Parsing the (unicode) codepoints in "Codes" with the callable
% integer(X) which actually resolves to predicate integer/3, taking
% itself "Codes" and "Rest" in addition to "X". After the call, leftover
% character codes from "Codes" are in "Rest".

test(parsing, [true(ResultCmp)] ) :-
   atom_codes('42 times', Codes),
   phrase(integer(X), Codes, Rest),
   atom_codes(RestAtom, Rest),
   ResultCmp = (result(X,RestAtom) == result(42,' times')).

% Generating the (unicode) codepoints in "Codes" based on an integer
% passed to the callable integer(X) and a suffix of codepoints in "Rest".
% After the call, the "Rest", prefixed with whatever integer(42) as
% generated, can be found in "Codes".
      
test(generating, [true(ResultCmp)] ) :-
   atom_codes(' times', Rest),
   phrase(integer(42), Codes, Rest),
   atom_codes(CodesAtom, Codes),
   ResultCmp = (CodesAtom == '42 times').
   
:- end_tests(dcg).

rt(dcg) :- run_tests(dcg).

How does integer//1 from library(dcg/basics) looks like?

(note the two // to indicate that this a DCG-processing predicate. In the same away as integer/1 is called a "predicate indicator", integer//1 is called a "non-terminal indicator")

It is actually an integer/3 (although one should not rely on what the compiler generates from integer//1)

?- listing(integer//1).
integer(I, A, B) :-
    digit(D0, A, C),
    digits(D, C, E),
    number_codes(I, [D0|D]),
    B=E.

true.