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)  2010-2013, University of 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(rdf_triple,
   36          [ rdf_triples/2,              % +Parsed, -Tripples
   37            rdf_triples/3,              % +Parsed, -Tripples, +Tail
   38            rdf_reset_ids/0,            % Reset gensym id's
   39            rdf_start_file/2,           % +Options, -Cleanup
   40            rdf_end_file/1,             % +Cleanup
   41            anon_prefix/1               % Prefix for anonynmous resources
   42          ]).   43:- use_module(library(gensym)).   44:- use_module(library(option)).   45:- use_module(library(uri)).   46:- use_module(rdf_parser).   47
   48:- predicate_options(rdf_start_file/2, 1,
   49                     [ base_uri(atom),
   50                       blank_nodes(oneof([share,noshare]))
   51                     ]).   52
   53/** <module> Create triples from intermediate representation
   54
   55Convert the output of xml_to_rdf/3  from   library(rdf)  into  a list of
   56triples of the format described   below. The intermediate representation
   57should be regarded a proprietary representation.
   58
   59        rdf(Subject, Predicate, Object).
   60
   61Where `Subject' is
   62
   63        * Atom
   64        The subject is a resource
   65
   66        * each(URI)
   67        URI is the URI of an RDF Bag
   68
   69        * prefix(Pattern)
   70        Pattern is the prefix of a fully qualified Subject URI
   71
   72And `Predicate' is
   73
   74        * Atom
   75        The predicate is always a resource
   76
   77And `Object' is
   78
   79        * Atom
   80        URI of Object resource
   81
   82        * literal(Value)
   83        Literal value (Either a single atom or parsed XML data)
   84*/
   85
   86%!  rdf_triples(+Term, -Triples) is det.
   87%!  rdf_triples(+Term, -Tridpples, +Tail) is det.
   88%
   89%   Convert an object as parsed by rdf.pl into a list of rdf/3
   90%   triples.  The identifier of the main object created is returned
   91%   by rdf_triples/3.
   92%
   93%   Input is the `content' of the RDF element in the format as
   94%   generated by load_structure(File, Term, [dialect(xmlns)]).
   95%   rdf_triples/3 can process both individual descriptions as
   96%   well as the entire content-list of an RDF element.  The first
   97%   mode is suitable when using library(sgml) in `call-back' mode.
   98
   99rdf_triples(RDF, Tripples) :-
  100    rdf_triples(RDF, Tripples, []).
  101
  102rdf_triples([]) -->
  103    !,
  104    [].
  105rdf_triples([H|T]) -->
  106    !,
  107    rdf_triples(H),
  108    rdf_triples(T).
  109rdf_triples(Term) -->
  110    triples(Term, _).
  111
  112%!  triples(-Triples, -Id, +In, -Tail)
  113%
  114%   DGC set processing the output of  xml_to_rdf/3. Id is unified to
  115%   the identifier of the main description.
  116
  117triples(description(Type, About, Props), Subject) -->
  118    { var(About),
  119      share_blank_nodes(true)
  120    },
  121    !,
  122    (   { shared_description(description(Type, Props), Subject)
  123        }
  124    ->  []
  125    ;   { make_id('_:Description', Id)
  126        },
  127        triples(description(Type, about(Id), Props), Subject),
  128        { assert_shared_description(description(Type, Props), Subject)
  129        }
  130    ).
  131triples(description(description, IdAbout, Props), Subject) -->
  132    !,
  133    { description_id(IdAbout, Subject)
  134    },
  135    properties(Props, Subject).
  136triples(description(TypeURI, IdAbout, Props), Subject) -->
  137    { description_id(IdAbout, Subject)
  138    },
  139    properties([ rdf:type = TypeURI
  140               | Props
  141               ], Subject).
  142triples(unparsed(Data), Id) -->
  143    { make_id('_:Error', Id),
  144      print_message(error, rdf(unparsed(Data)))
  145    },
  146    [].
  147
  148
  149                 /*******************************
  150                 *          DESCRIPTIONS        *
  151                 *******************************/
  152
  153:- thread_local
  154    node_id/2,                      % nodeID --> ID
  155    unique_id/1.                    % known rdf:ID
  156
  157rdf_reset_node_ids :-
  158    retractall(node_id(_,_)),
  159    retractall(unique_id(_)).
  160
  161description_id(Id, Id) :-
  162    var(Id),
  163    !,
  164    make_id('_:Description', Id).
  165description_id(about(Id), Id).
  166description_id(id(Id), Id) :-
  167    (   unique_id(Id)
  168    ->  print_message(error, rdf(redefined_id(Id)))
  169    ;   assert(unique_id(Id))
  170    ).
  171description_id(each(Id), each(Id)).
  172description_id(prefix(Id), prefix(Id)).
  173description_id(node(NodeID), Id) :-
  174    (   node_id(NodeID, Id)
  175    ->  true
  176    ;   make_id('_:Node', Id),
  177        assert(node_id(NodeID, Id))
  178    ).
  179
  180properties(PlRDF, Subject) -->
  181    properties(PlRDF, 1, [], [], Subject).
  182
  183properties([], _, Bag, Bag, _) -->
  184    [].
  185properties([H0|T0], N, Bag0, Bag, Subject) -->
  186    property(H0, N, NN, Bag0, Bag1, Subject),
  187    properties(T0, NN, Bag1, Bag, Subject).
  188
  189%!  property(Property, N, NN, Subject)// is det.
  190%
  191%   Generate triples for {Subject,  Pred,   Object}.  Also generates
  192%   triples for Object if necessary.
  193%
  194%   @param Property One of
  195%
  196%           * Pred = Object
  197%           Used for normal statements
  198%           * id(Id, Pred = Object)
  199%           Used for reified statements
  200
  201property(Pred0 = Object, N, NN, BagH, BagT, Subject) --> % inlined object
  202    triples(Object, Id),
  203    !,
  204    { li_pred(Pred0, Pred, N, NN)
  205    },
  206    statement(Subject, Pred, Id, _, BagH, BagT).
  207property(Pred0 = collection(Elems), N, NN, BagH, BagT, Subject) -->
  208    !,
  209    { li_pred(Pred0, Pred, N, NN)
  210    },
  211    statement(Subject, Pred, Object, _Id, BagH, BagT),
  212    collection(Elems, Object).
  213property(Pred0 = Object, N, NN, BagH, BagT, Subject) -->
  214    !,
  215    { li_pred(Pred0, Pred, N, NN)
  216    },
  217    statement(Subject, Pred, Object, _Id, BagH, BagT).
  218property(id(Id, Pred0 = Object), N, NN, BagH, BagT, Subject) -->
  219    triples(Object, ObjectId),
  220    !,
  221    { li_pred(Pred0, Pred, N, NN)
  222    },
  223    statement(Subject, Pred, ObjectId, Id, BagH, BagT).
  224property(id(Id, Pred0 = collection(Elems)), N, NN, BagH, BagT, Subject) -->
  225    !,
  226    { li_pred(Pred0, Pred, N, NN)
  227    },
  228    statement(Subject, Pred, Object, Id, BagH, BagT),
  229    collection(Elems, Object).
  230property(id(Id, Pred0 = Object), N, NN, BagH, BagT, Subject) -->
  231    { li_pred(Pred0, Pred, N, NN)
  232    },
  233    statement(Subject, Pred, Object, Id, BagH, BagT).
  234
  235%!  statement(+Subject, +Pred, +Object, +Id, +BagH, -BagT)
  236%
  237%   Add a statement to the model. If nonvar(Id), we reinify the
  238%   statement using the given Id.
  239
  240statement(Subject, Pred, Object, Id, BagH, BagT) -->
  241    rdf(Subject, Pred, Object),
  242    {   BagH = [Id|BagT]
  243    ->  statement_id(Id)
  244    ;   BagT = BagH
  245    },
  246    (   { nonvar(Id)
  247        }
  248    ->  rdf(Id, rdf:type, rdf:'Statement'),
  249        rdf(Id, rdf:subject, Subject),
  250        rdf(Id, rdf:predicate, Pred),
  251        rdf(Id, rdf:object, Object)
  252    ;   []
  253    ).
  254
  255
  256statement_id(Id) :-
  257    nonvar(Id),
  258    !.
  259statement_id(Id) :-
  260    make_id('_:Statement', Id).
  261
  262%!  li_pred(+Pred, -Pred, +Nth, -NextNth)
  263%
  264%   Transform rdf:li predicates into _1, _2, etc.
  265
  266li_pred(rdf:li, rdf:Pred, N, NN) :-
  267    !,
  268    NN is N + 1,
  269    atom_concat('_', N, Pred).
  270li_pred(Pred, Pred, N, N).
  271
  272%!  collection(+Elems, -Id)
  273%
  274%   Handle the elements of a collection and return the identifier
  275%   for the whole collection in Id.
  276
  277collection([], Nil) -->
  278    { global_ref(rdf:nil, Nil)
  279    }.
  280collection([H|T], Id) -->
  281    triples(H, HId),
  282    { make_id('_:List', Id)
  283    },
  284    rdf(Id, rdf:type, rdf:'List'),
  285    rdf(Id, rdf:first, HId),
  286    rdf(Id, rdf:rest, TId),
  287    collection(T, TId).
  288
  289
  290rdf(S0, P0, O0) -->
  291    { global_ref(S0, S),
  292      global_ref(P0, P),
  293      global_obj(O0, O)
  294    },
  295    [ rdf(S, P, O) ].
  296
  297
  298global_ref(In, Out) :-
  299    (   nonvar(In),
  300        In = NS:Local
  301    ->  (   NS == rdf,
  302            rdf_name_space(RDF)
  303        ->  atom_concat(RDF, Local, Out)
  304        ;   atom_concat(NS, Local, Out0),
  305            iri_normalized(Out0, Out)
  306        )
  307    ;   Out = In
  308    ).
  309
  310global_obj(V, V) :-
  311    var(V),
  312    !.
  313global_obj(literal(type(Local, X)), literal(type(Global, X))) :-
  314    !,
  315    global_ref(Local, Global).
  316global_obj(literal(X), literal(X)) :- !.
  317global_obj(Local, Global) :-
  318    global_ref(Local, Global).
  319
  320
  321                 /*******************************
  322                 *             SHARING          *
  323                 *******************************/
  324
  325:- thread_local
  326    shared_description/3,           % +Hash, +Term, -Subject
  327    share_blank_nodes/1,            % Boolean
  328    shared_nodes/1.                 % counter
  329
  330reset_shared_descriptions :-
  331    retractall(shared_description(_,_,_)),
  332    retractall(shared_nodes(_)).
  333
  334shared_description(Term, Subject) :-
  335    term_hash(Term, Hash),
  336    shared_description(Hash, Term, Subject),
  337    (   retract(shared_nodes(N))
  338    ->  N1 is N + 1
  339    ;   N1 = 1
  340    ),
  341    assert(shared_nodes(N1)).
  342
  343
  344assert_shared_description(Term, Subject) :-
  345    term_hash(Term, Hash),
  346    assert(shared_description(Hash, Term, Subject)).
  347
  348
  349                 /*******************************
  350                 *            START/END         *
  351                 *******************************/
  352
  353%!  rdf_start_file(+Options, -Cleanup) is det.
  354%
  355%   Initialise for the translation of a file.
  356
  357rdf_start_file(Options, Cleanup) :-
  358    rdf_reset_node_ids,             % play safe
  359    reset_shared_descriptions,
  360    set_bnode_sharing(Options, C1),
  361    set_anon_prefix(Options, C2),
  362    add_cleanup(C1, C2, Cleanup).
  363
  364%!  rdf_end_file(:Cleanup) is det.
  365%
  366%   Cleanup reaching the end of an RDF file.
  367
  368rdf_end_file(Cleanup) :-
  369    rdf_reset_node_ids,
  370    (   shared_nodes(N)
  371    ->  print_message(informational, rdf(shared_blank_nodes(N)))
  372    ;   true
  373    ),
  374    reset_shared_descriptions,
  375    Cleanup.
  376
  377set_bnode_sharing(Options, erase(Ref)) :-
  378    option(blank_nodes(Share), Options, noshare),
  379    (   Share == share
  380    ->  assert(share_blank_nodes(true), Ref), !
  381    ;   Share == noshare
  382    ->  fail                        % next clause
  383    ;   throw(error(domain_error(share, Share), _))
  384    ).
  385set_bnode_sharing(_, true).
  386
  387set_anon_prefix(Options, erase(Ref)) :-
  388    option(base_uri(BaseURI), Options),
  389    nonvar(BaseURI),
  390    !,
  391    (   BaseURI == []
  392    ->  AnonBase = '_:'
  393    ;   atomic_list_concat(['_:', BaseURI, '#'], AnonBase)
  394    ),
  395    asserta(anon_prefix(AnonBase), Ref).
  396set_anon_prefix(_, true).
  397
  398add_cleanup(true, X, X) :- !.
  399add_cleanup(X, true, X) :- !.
  400add_cleanup(X, Y, (X, Y)).
  401
  402
  403                 /*******************************
  404                 *             UTIL             *
  405                 *******************************/
  406
  407%!  anon_prefix(-Prefix) is semidet.
  408%
  409%   If defined, it is the prefix used to generate a blank node.
  410
  411:- thread_local
  412    anon_prefix/1.  413
  414make_id(For, ID) :-
  415    anon_prefix(Prefix),
  416    !,
  417    atom_concat(Prefix, For, Base),
  418    gensym(Base, ID).
  419make_id(For, ID) :-
  420    gensym(For, ID).
  421
  422anon_base('_:Description').
  423anon_base('_:Statement').
  424anon_base('_:List').
  425anon_base('_:Node').
  426
  427%!  rdf_reset_ids is det.
  428%
  429%   Utility predicate to reset the gensym counters for the various
  430%   generated identifiers.  This simplifies debugging and matching
  431%   output with the stored desired output (see rdf_test.pl).
  432
  433rdf_reset_ids :-
  434    anon_prefix(Prefix),
  435    !,
  436    (   anon_base(Base),
  437        atom_concat(Prefix, Base, X),
  438        reset_gensym(X),
  439        fail
  440    ;   true
  441    ).
  442rdf_reset_ids :-
  443    (   anon_base(Base),
  444        reset_gensym(Base),
  445        fail
  446    ;   true
  447    )