This module provides predicates for working with GraphQL, a query language for HTTP-based APIs.

 graphql_execute_document(+URI, +Document, -Result, +Options) is det

Send GraphQL document Document to be executed by the GraphQL endpoint at URI.

Document is a Prolog term representing the abstract syntax tree of the GraphQL document, as obtained from e.g. graphql_read_document/3 or graphql/4 quasi-quotation. Result is unified with a dict representing the JSON formatted response received from the server.

The following example shows how graphql_execute_document/4 can be used to expose a simple GraphQL interface to Prolog:

sourcehut_repository_description(Owner, Repo, Desc) :-
    graphql_execute_document("https://git.sr.ht/query",
                             {| graphql(Owner, Repo) ||
                                { user(username: <Owner>)
                                  { repository(name: <Repo>)
                                    { description } } } |},
                             Dict,
                             [token(...)]),
    Desc = Dict.get(data/user/repository/description).


?- sourcehut_repository_description("eshel", "sourcehut.pl", Desc).
Desc = "SWI-Prolog package implementing a SourceHut GraphQL API client.".

Options is a list whose elemenets are one of the following:

token(+Token)

Token is string that will be used as an OAuth2.0 token. See also graphql_auth_token_hook/2.

variables(+Variables)

Variables is a dict with keys corresponding to GraphQL variables that occur in Document as $key. Variables is sent to the remote to the GraphQL endpoint in JSON format for server-side interpolation. For more information about GraphQL variables, see https://spec.graphql.org/draft/#sec-Language.

 graphql_auth_token_hook(+URI, -Token) is nondet[multifile]

Multifile, dynamic hook. graphql_execute_document/4 consults this hook to set authorization token for the GraphQL endpoint at URI.

 graphql(+Content, +Args, -VariableNames, -Result) is det

Quasi-quotation syntax for embedding GraphQL in Prolog text. Prolog variables can be incorporated in the quasi-quotation using the special lexical construct "<VarName>" where VarName is the name of a variable that is an element of Args. See also option variable_names(+VarNames) in graphql_read_document/3.

Result is a term representing the given GraphQL document in the same format as used by graphql_read_document/3.

 graphql_read_document(+Source, -Document, +Options) is semidet

True when Document is a term representing the abstract syntax tree obtained from parsing Source as a GraphQL executable document.

Document is a list of terms representing GraphQL executable definitions, each being one of:

operation(Type, Name, VariableDefinitions, Directives, SelectionSet)

Type is one of the atoms query, mutation or subscription. Name is either the atom null or a string denoting the name given to this specific operation.

VariableDefinitions is a list of terms of the form variable_definition(VarName, VarType, VarDefault, VarDirs) where VarName is a string denoting the name of the variable, VarType is a term denoting the GraphQL type of the defined variable in the format described below, VarDefault is a term denoting a default GraphQL value associated with the defined variable, and VarDirs is a possibly empty list of GraphQL directives, each of which a term DirName-DirArgs where DirName is the string name of the directive and DirArgs is a Prolog dict denoting the directive arguments.

Directives is a possibly empty list of GraphQL directives associated with the given GraphQL operation.

SelectionSet is a list of GraphQL selections, each selection is one of field(FieldAlias, FieldName, FieldArgs, FieldDirs, FieldSelection), in which case FieldAlias is either null or a string denoting the alias of the field, FieldName is a string denoting the name of the field, FieldArgs is a dict denoting the field arguments, FieldDirs is a list of GraphQL directives and FieldSelection is a list of GraphQL selections nested below the given field. Otherwise, each selection can have the from fragment_spread(FragName, FragDirs) where FragName is a string denoting the name of the fragment and FragDirs is a possibly empty list of GraphQL directives. Lastly, each selection can have the form inline_fragment(IFragTypeCondition, IFragDirs, IFragSelectionSet) where IFragTypeCondition is a string denoting a type condition associated with the inline fragment, IFragDirs denotes GraphQL directives associated with it, and IFragSelectionSet is a list of GraphQL selections specified by the fragment.

fragment(Name, Type, Directives, SelectionSet)

Where Name is a string denoting the name of the fragment, Type is a GraphQL type term, directives is possibly empty list of GraphQL directives, and SelectionSet is a list of GraphQL selections associated with the fragment.

A GraphQL type is represented as one of:

named_type(Name)

Where Name is a string denoting the name of the type.

list_type(Type)

Where Type is a GraphQL type.

non_null_type(Type)

Where Type is a GraphQL type.

A GraphQL value is represented as one of:

true

Represents the GraphQL true value.

false

Represents the GraphQL false value.

null

Represents the GraphQL null value.

enum(E)

Represents the GraphQL enum corresponding to the string E.

String

A Prolog string String represents the same GraphQL string.

Integer

A Prolog integer Integer represents the same GraphQL integer.

Float

A Prolog float Float represents the same GraphQL float.

ListOfValues

A Prolog list ListOfValues whose elements are GraphQL values represents the GraphQL list value whose elements are represented by the elements of ListOfValues.

DictOfValues

A Prolog dict DictOfValues with GraphQL values for values represents the GraphQL object value whose fields are represented by the key-value pairs of DictOfValues.

Source can be one of:

codes(+Codes, -Rest)

Codes is a list of codes representing the source GraphQL text. Rest is unified with the list of trailing codes starting from the first code that was not recognized as part of a valid GraphQL token.

codes(+Codes)

Same as codes(Codes, []).

string(+String)

String is a string representing the source GraphQL text.

Stream

Stream is a stream from which the source GraphQL text is read with phrase_from_stream/2.

Options is a list whose elements can be one of:

variable_names([Name=Value|...])

A list of associations of Prolog variable names, given as atoms, to GraphQL values.

Occurences of the special lexical construct "<Name>" (that is, ASCII 60, then the codes of the atom Name, then ASCII 62) in Source are expanded in Document to the GraphQL value Value. This option can be used to interpolate GraphQL documents with values given in Prolog representation.

 graphql_document_to_string(+Document, -String, +Options) is det

Serialize the GraphQL document Document and unify String with the resulting string.

Options are passed on to graphql_document_to_codes/3.

 graphql_document_to_codes(+Document, -Codes, +Options) is det

Serialize Document, a Prolog term representing a GraphQL document as obtained from graphql_read_document/3 or the graphql/4 quasi-quotation, and unify Codes with the resulting list of character codes.

Options are a list whose elements are one of:

separator(+Sep)

Sep is a list of codes to be used for separating adjancent GraphQL values in Codes. Defaults to a single space. This option can be used to separate values with commas (which are optional throughout GraphQL) by passing e.g. separator(`, `).