% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(dcg/basics): Various general DCG utilities}

\label{sec:basics}

\begin{tags}
    \tag{To be done}
This is just a starting point. We need a comprehensive set of
generally useful DCG primitives.
\end{tags}

This library provides various commonly used DCG primitives acting on
list of character \textbf{codes}. Character classification is based on
\predref{code_type}{2}.

This module started its life as \file{library(http/dcg_basics)} to support the
HTTP protocol. Since then, it was increasingly used in code that has no
relation to HTTP and therefore this library was moved to the core
library.\vspace{0.7cm}

\begin{description}
    \dcg[det]{string_without}{2}{+EndCodes, -Codes}
Take as many codes from the input until the next character code
appears in the list \arg{EndCodes}. The terminating code itself is
left on the input. Typical use is to read upto a defined
delimiter such as a newline or other reserved character. For
example:

\begin{code}
    ...,
    string_without("\n", RestOfLine)
\end{code}

\begin{arguments}
\arg{EndCodes} & is a list of character codes. \\
\end{arguments}

\begin{tags}
    \tag{See also}
\dcgref{string}{1}.
\end{tags}

    \dcg[nondet]{string}{1}{-Codes}
Take as few as possible tokens from the input, taking one more
each time on backtracking. This code is normally followed by a
test for a delimiter. For example:

\begin{code}
upto_colon(Atom) -->
        string(Codes), ":", !,
        { atom_codes(Atom, Codes) }.
\end{code}

\begin{tags}
    \tag{See also}
\dcgref{string_without}{2}.
\end{tags}

    \dcg[det]{blanks}{0}{}
Skip zero or more white-space characters.

    \dcg[semidet]{blank}{0}{}
Take next \const{space} character from input. Space characters include
newline.

\begin{tags}
    \tag{See also}
\dcgref{white}{0}
\end{tags}

    \dcg[det]{nonblanks}{1}{-Codes}
Take all \const{graph} characters

    \dcg[semidet]{nonblank}{1}{-Code}
\arg{Code} is the next non-blank (\const{graph}) character.

    \dcg[semidet]{blanks_to_nl}{0}{}
Take a sequence of \dcgref{blank}{0} codes if blanks are followed by a
newline or end of the input.

    \dcg[det]{whites}{0}{}
Skip white space \textit{inside} a line.

\begin{tags}
    \tag{See also}
\dcgref{blanks}{0} also skips newlines.
\end{tags}

    \dcg[semidet]{white}{0}{}
Take next \const{white} character from input. White characters do
\textit{not} include newline.

    \dcg[semidet]{alpha_to_lower}{1}{?C}
Read a letter (class \const{alpha}) and return it as a lowercase
letter. If \arg{C} is instantiated and the DCG list is already bound,
\arg{C} must be \const{lower} and matches both a lower and uppercase letter.
If the output list is unbound, its first element is bound to \arg{C}.
For example:

\begin{code}
?- alpha_to_lower(0'a, `AB`, R).
R = [66].
?- alpha_to_lower(C, `AB`, R).
C = 97, R = [66].
?- alpha_to_lower(0'a, L, R).
L = [97|R].
\end{code}

    \dcg[det]{digits}{1}{?Chars}
\nodescription
    \dcg[det]{digit}{1}{?Char}
\nodescription
    \dcg[det]{integer}{1}{?Integer}
Number processing. The predicate \dcgref{digits}{1} matches a possibly
empty set of digits, \dcgref{digit}{1} processes a single digit and
integer processes an optional sign followed by a non-empty
sequence of digits into an integer.

    \dcg[det]{float}{1}{?Float}
Process a floating point number. The actual conversion is
controlled by \predref{number_codes}{2}.

    \dcg[det]{number}{1}{+Number}
\nodescription
    \dcg[semidet]{number}{1}{-Number}
Generate extract a number. Handles both integers and floating
point numbers.

    \dcg[det]{xinteger}{1}{+Integer}
\nodescription
    \dcg[semidet]{xinteger}{1}{-Integer}
Generate or extract an integer from a sequence of hexadecimal
digits. Hexadecimal characters include both uppercase (A-F) and
lowercase (a-f) letters. The value may be preceded by a sign
(+/-)

    \dcg[semidet]{xdigit}{1}{-Weight}
True if the next code is a hexdecimal digit with \arg{Weight}. \arg{Weight}
is between 0 and 15. Hexadecimal characters include both
uppercase (A-F) and lowercase (a-f) letters.

    \dcg[det]{xdigits}{1}{-WeightList}
List of weights of a sequence of hexadecimal codes. \arg{WeightList}
may be empty. Hexadecimal characters include both uppercase
(A-F) and lowercase (a-f) letters.

    \dcg{eol}{0}{}
Matches end-of-line. Matching \bsl{}r\bsl{}n, \Bn{} or end of input (\dcgref{eos}{0}).

    \dcg{eos}{0}{}
Matches end-of-input. The implementation behaves as the
following portable implementation:

\begin{code}
eos --> call(eos_).
eos_([], []).
\end{code}

\begin{tags}
    \tag{To be done}
This is a difficult concept and violates the \textit{context free}
property of DCGs. Explain the exact problems.
\end{tags}

    \dcg{remainder}{1}{-List}
Unify \arg{List} with the remainder of the input.

    \dcg[semidet]{prolog_var_name}{1}{-Name:atom}
Matches a Prolog variable name. Primarily intended to deal with
quasi quotations that embed Prolog variables.

    \dcg[semidet]{csym}{1}{?Symbol:atom}
Recognise a C symbol according to the \const{csymf} and \const{csym} code
type classification provided by the C library.

    \dcg[det]{atom}{1}{++Atom}
Generate codes of \arg{Atom}. Current implementation uses \predref{write}{1},
dealing with any Prolog term. \arg{Atom} must be ground though.
\end{description}