View source with formatted comments or as raw
    1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        J.Wielemaker@vu.nl
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2013-2015, VU University Amsterdam
    7    All rights reserved.
    8
    9    Redistribution and use in source and binary forms, with or without
   10    modification, are permitted provided that the following conditions
   11    are met:
   12
   13    1. Redistributions of source code must retain the above copyright
   14       notice, this list of conditions and the following disclaimer.
   15
   16    2. Redistributions in binary form must reproduce the above copyright
   17       notice, this list of conditions and the following disclaimer in
   18       the documentation and/or other materials provided with the
   19       distribution.
   20
   21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   32    POSSIBILITY OF SUCH DAMAGE.
   33*/
   34
   35:- module(quasi_quotations,
   36          [ with_quasi_quotation_input/3,       % +Content, -Stream, :Goal
   37            phrase_from_quasi_quotation/2,      % :Grammar, +Content
   38            quasi_quotation_syntax_error/1,     % +Error
   39            quasi_quotation_syntax/1            % :Syntax
   40          ]).   41:- autoload(library(error),[must_be/2]).   42:- autoload(library(pure_input),[stream_to_lazy_list/2]).   43
   44
   45/** <module> Define Quasi Quotation syntax
   46
   47Inspired                                                              by
   48[Haskell](http://www.haskell.org/haskellwiki/Quasiquotation), SWI-Prolog
   49support _quasi quotation_. Quasi quotation   allows for embedding (long)
   50strings using the syntax of an external   language  (e.g., HTML, SQL) in
   51Prolog text and syntax-aware  embedding  of   Prolog  variables  in this
   52syntax. At the same time,  quasi   quotation  provides an alternative to
   53represent long strings and atoms in Prolog.
   54
   55The basic form of a quasi quotation  is defined below. Here, `Syntax` is
   56an arbitrary Prolog term that must  parse   into  a  _callable_ (atom or
   57compound) term and Quotation is an arbitrary sequence of characters, not
   58including the sequence =||}|=. If this sequence needs to be embedded, it
   59must be escaped according to the  rules   of  the target language or the
   60`quoter' must provide an escaping mechanism.
   61
   62    ==
   63    {|Syntax||Quotation|}
   64    ==
   65
   66While reading a Prolog term, and if   the  Prolog flag =quasi_quotes= is
   67set to =true= (which is the case if  this library is loaded), the parser
   68collects quasi quotations. After reading the final full stop, the parser
   69makes the call below. Here, `SyntaxName` is the functor name of `Syntax`
   70above and `SyntaxArgs` is a list   holding  the arguments, i.e., `Syntax
   71=.. [SyntaxName|SyntaxArgs]`. Splitting the  syntax   into  its name and
   72arguments is done to make the quasi  quotation parser a predicate with a
   73consistent arity 4, regardless of the number of additional arguments.
   74
   75    ==
   76    call(+SyntaxName, +Content, +SyntaxArgs, +VariableNames, -Result)
   77    ==
   78
   79The arguments are defined as
   80
   81  - `SyntaxName` is the principal functor of the quasi quotation syntax.
   82  This must be declared using quasi_quotation_syntax/1 and there must be
   83  a predicate SyntaxName/4.
   84
   85  - `Content` is an opaque term that carries the content of the quasi
   86  quoted material and position information about the source code. It is
   87  passed to with_quasi_quote_input/3.
   88
   89  - `SyntaxArgs` carries the additional arguments of the `Syntax`. These are
   90  commonly used to make the parameter passing between the clause and the
   91  quasi quotation explicit. For example:
   92
   93    ==
   94        ...,
   95        {|html(Name, Address)||
   96         <tr><td>Name<td>Address</tr>
   97         |}
   98    ==
   99
  100  - `VariableNames` is the complete variable dictionary of the clause as
  101  it is made available throug read_term/3 with the option
  102  =variable_names=. It is a list of terms `Name = Var`.
  103
  104  - `Result` is a variable that must be unified to resulting term.
  105  Typically, this term is structured Prolog tree that carries a
  106  (partial) representation of the abstract syntax tree with embedded
  107  variables that pass the Prolog parameters. This term is normally
  108  either passed to a predicate that serializes the abstract syntax tree,
  109  or a predicate that processes the result in Prolog. For example, HTML
  110  is commonly embedded for writing HTML documents (see
  111  library(http/html_write)). Examples of languages that may be embedded
  112  for processing in Prolog are SPARQL, RuleML or regular expressions.
  113
  114The file library(http/html_quasiquotations) provides   the,  suprisingly
  115simple, quasi quotation parser for HTML.
  116
  117@author Jan Wielemaker.  Introduction of Quasi Quotation was suggested
  118        by Michael Hendricks.
  119@see    [Why it's nice to be quoted: quasiquoting for
  120        haskell](http://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf)
  121*/
  122
  123
  124:- meta_predicate
  125    with_quasi_quotation_input(+, -, 0),
  126    quasi_quotation_syntax(4),
  127    phrase_from_quasi_quotation(//, +).  128
  129:- set_prolog_flag(quasi_quotations, true).  130
  131%!  with_quasi_quotation_input(+Content, -Stream, :Goal) is det.
  132%
  133%   Process the quasi-quoted Content using   Stream  parsed by Goal.
  134%   Stream is a temporary stream with the following properties:
  135%
  136%       - Its initial _position_ represents the position of the
  137%         start of the quoted material.
  138%       - It is a text stream, using =utf8= _encoding_.
  139%       - It allows for repositioning
  140%       - It will be closed after Goal completes.
  141%
  142%   @arg Goal is executed as once(Goal).  Goal must succeed.
  143%        Failure or exceptions from Goal are interpreted as
  144%        syntax errors.
  145%   @see phrase_from_quasi_quotation/2 can be used to process a
  146%        quotation using a grammar.
  147
  148with_quasi_quotation_input(Content, Stream, Goal) :-
  149    functor(Content, '$quasi_quotation', 3),
  150    !,
  151    setup_call_cleanup(
  152        '$qq_open'(Content, Stream),
  153        (   call(Goal)
  154        ->  true
  155        ;   quasi_quotation_syntax_error(
  156                quasi_quotation_parser_failed,
  157                Stream)
  158        ),
  159        close(Stream)).
  160
  161%!  phrase_from_quasi_quotation(:Grammar, +Content) is det.
  162%
  163%   Process the quasi quotation using the   DCG  Grammar. Failure of
  164%   the grammar is interpreted as a syntax error.
  165%
  166%   @see    with_quasi_quotation_input/3 for processing quotations from
  167%           stream.
  168
  169phrase_from_quasi_quotation(Grammar, Content) :-
  170    functor(Content, '$quasi_quotation', 3),
  171    !,
  172    setup_call_cleanup(
  173        '$qq_open'(Content, Stream),
  174        phrase_quasi_quotation(Grammar, Stream),
  175        close(Stream)).
  176
  177phrase_quasi_quotation(Grammar, Stream) :-
  178    set_stream(Stream, buffer_size(512)),
  179    stream_to_lazy_list(Stream, List),
  180    phrase(Grammar, List),
  181    !.
  182phrase_quasi_quotation(_, Stream) :-
  183    quasi_quotation_syntax_error(
  184        quasi_quotation_parser_failed,
  185        Stream).
  186
  187%!  quasi_quotation_syntax(:SyntaxName) is det.
  188%
  189%   Declare the predicate SyntaxName/4  to   implement  the  the quasi
  190%   quote syntax SyntaxName.  Normally used as a directive.
  191
  192quasi_quotation_syntax(M:Syntax) :-
  193    must_be(atom, Syntax),
  194    '$set_predicate_attribute'(M:Syntax/4, quasi_quotation_syntax, true).
  195
  196%!  quasi_quotation_syntax_error(+Error)
  197%
  198%   Report syntax_error(Error) using the  current   location  in the
  199%   quasi quoted input parser.
  200%
  201%   @throws error(syntax_error(Error), Position)
  202
  203quasi_quotation_syntax_error(Error) :-
  204    quasi_quotation_input(Stream),
  205    quasi_quotation_syntax_error(Error, Stream).
  206
  207quasi_quotation_syntax_error(Error, Stream) :-
  208    stream_syntax_error_context(Stream, Context),
  209    throw(error(syntax_error(Error), Context)).
  210
  211quasi_quotation_input(Stream) :-
  212    '$input_context'(Stack),
  213    memberchk(input(quasi_quoted, _File, _Line, StreamVar), Stack),
  214    Stream = StreamVar.
  215
  216
  217%!  stream_syntax_error_context(+Stream, -Position) is det.
  218%
  219%   Provide syntax error  location  for   the  current  position  of
  220%   Stream.
  221
  222stream_syntax_error_context(Stream, file(File, LineNo, LinePos, CharNo)) :-
  223    stream_property(Stream, file_name(File)),
  224    position_context(Stream, LineNo, LinePos, CharNo),
  225    !.
  226stream_syntax_error_context(Stream, stream(Stream, LineNo, LinePos, CharNo)) :-
  227    position_context(Stream, LineNo, LinePos, CharNo),
  228    !.
  229stream_syntax_error_context(_, _).
  230
  231position_context(Stream, LineNo, LinePos, CharNo) :-
  232    stream_property(Stream, position(Pos)),
  233    !,
  234    stream_position_data(line_count,    Pos, LineNo),
  235    stream_position_data(line_position, Pos, LinePos),
  236    stream_position_data(char_count,    Pos, CharNo).
  237
  238
  239                 /*******************************
  240                 *         SYSTEM HOOK          *
  241                 *******************************/
  242
  243%       system:'$parse_quasi_quotations'(+Quotations:list, +Module) is
  244%       det.
  245%
  246%       @arg    Quotations is a list of terms
  247%
  248%                   quasi_quotation(Syntax, Quotation, VarNames, Result)
  249
  250:- public
  251    system:'$parse_quasi_quotations'/2.  252
  253system:'$parse_quasi_quotations'([], _).
  254system:'$parse_quasi_quotations'([H|T], M) :-
  255    qq_call(H, M),
  256    system:'$parse_quasi_quotations'(T, M).
  257
  258qq_call(quasi_quotation(Syntax, Content, VariableNames, Result), M) :-
  259    current_prolog_flag(sandboxed_load, false),
  260    Syntax =.. [SyntaxName|SyntaxArgs],
  261    setup_call_cleanup(
  262        '$push_input_context'(quasi_quoted),
  263        call(M:SyntaxName, Content, SyntaxArgs, VariableNames, Result),
  264        '$pop_input_context'),
  265    !.
  266qq_call(quasi_quotation(Syntax, Content, VariableNames, Result), M) :-
  267    current_prolog_flag(sandboxed_load, true),
  268    Syntax =.. [SyntaxName|SyntaxArgs],
  269    Expand =.. [SyntaxName, Content, SyntaxArgs, VariableNames, Result],
  270    QExpand = M:Expand,
  271    '$expand':allowed_expansion(QExpand),
  272    setup_call_cleanup(
  273        '$push_input_context'(quasi_quoted),
  274        call(QExpand),
  275        '$pop_input_context'),
  276    !.
  277qq_call(quasi_quotation(_Syntax, Content, _VariableNames, _Result), _M) :-
  278    setup_call_cleanup(
  279        '$push_input_context'(quasi_quoted),
  280        with_quasi_quotation_input(
  281            Content, Stream,
  282            quasi_quotation_syntax_error(quasi_quote_parser_failed, Stream)),
  283        '$pop_input_context'),
  284    !.
  285
  286
  287                 /*******************************
  288                 *             MESSAGES         *
  289                 *******************************/
  290
  291:- multifile
  292    prolog:error_message//1.  293
  294prolog:error_message(syntax_error(unknown_quasi_quotation_syntax(Syntax, M))) -->
  295    { functor(Syntax, Name, _) },
  296    [ 'Quasi quotation syntax ~q:~q is not defined'-[M, Name] ].
  297prolog:error_message(syntax_error(invalid_quasi_quotation_syntax(Syntax))) -->
  298    [ 'Quasi quotation syntax must be a callable term.  Found ~q'-[Syntax] ]