PKB4Unix
Tools to handle RDF graphs, inspired by the UNIX philosophy

PKB4Unix provides several command line tools to process RDF graphs. Each of
them take ntriples as input and output ntriples. As such, they can be used
easily in pipelines. The ntriples format is line based, but is also valid
turtle. Also included is a tool that converts between various serialization
formats. It is also capable of producing canonical ntriples and turtle, which
makes its output suitable for version control.
PKB4Unix was originally intended to manage a personal knowledge base. The
project may however have wider applications. It may be split up or adapted in
the future.

For more information see

    http://www.andonyar.com/rec/2012/pkb/

=== Requirements ===

- Python 3
- A recent version of RDFLib <https://github.com/RDFLib>
- A SPARQL 1.1 endpoint with support for updates and the graph
  store HTTP protocol.
- A Unix-like operating system (tested on Linux only)

=== Setup ===

Run

    python3 setup.py install

or if you want to install to your user directory

    python3 setup.py install --user

You can also test the scripts where they are. For this, add the
directory to your PATH.

=== Environment Variables ===

Most scripts know-* need a few environment variables to be set.
You are advised to run the scripts through the wrapper `know`. It
allows you to easily set these variables using command line options.
Use `know help` to find out what options are required and to which
value they are currently set.

=== Usage ===

Find out what commands are available:

    know help

Read the help of a command:

    know <command> --help

=== Example Session ===

Starting my SPARQL backend

    $ ./tomcat-instance/bin/startup.sh 
    ...
    Tomcat started

Loading my data into the endpoint

    $ know load data/*
    data/friends.rdf: loading as file:///home/urs/p/knowledge/data/friends.rdf ... done.
    data/interesting_websites.ttl: loading as file:///home/urs/p/knowledge/data/interesting_websites.ttl ... done.
    data/problemandsolution.ttl: loading as file:///home/urs/p/knowledge/data/problemandsolution.ttl ... done.
    data/quotes.ttl: loading as file:///home/urs/p/knowledge/data/quotes.ttl ... done.
    data/software.ttl: loading as file:///home/urs/p/knowledge/data/software.ttl ... done.
    data/tracker.rdf: loading as file:///home/urs/p/knowledge/data/tracker.rdf ... done.

Interactively constructing a new task

    $ know construct ~/.local/share/pkb4unix/templates/task.tmpl
    /home/urs/.local/bin/know-construct: Constructing graph urn:uuid:b6667453-3a99-41d5-9ad0-e5419d9a3f69
    Available commands:
    ! CMD
        Executes CMD in a shell
    | CMD
        Executes CMD in a shell and takes output as value
    @
        Same as `| know edit --null`


    === http://www.w3.org/2005/01/wf/flow#Task
    I will insert the following triples:
        ?task a wf:Open ;
              wf:tracker ?tracker ;
              wf:dateDue ?dateDue ;
              wf:dependent ?dependent ;
              wf:description ?description .

    CONSTRUCTING Creating an open task> | know rdf-uuid
    RESOURCE1/1 [wf:Tracker] tracked by> private:tracker
    LITERAL1/? [^^xsd:date] date this task has to be completed> 2013-05-15
    RESOURCE1/* [wf:Task] A task this one depends on> 
    LITERAL1/1 description> Finish publication of Carambola manual
    Adding tribles with SPARQL:
    INSERT {
        ?task a wf:Open ;
              wf:tracker ?tracker ;
              wf:dateDue ?dateDue ;
              wf:dependent ?dependent ;
              wf:description ?description .
    }
    WHERE {
    VALUES (?task) { (<urn:uuid:126b72a8-cc93-4353-afd2-8ce7acdca5be>) }
    VALUES (?dateDue) { ("2013-05-15"^^<http://www.w3.org/2001/XMLSchema#date>) }
    VALUES (?description) { ("Finish publication of Carambola manual") }
    VALUES (?tracker) { (<private:tracker>) }
    }
    === done

    ## At this point an editor is called to check the created graph
    ## and modify if necessary.

    STDIN: loading as urn:uuid:7ce4218b-343a-46c1-b13b-6b816c13be85 ... done.

    /home/urs/.local/bin/know-construct: Construction of graph urn:uuid:b6667453-3a99-41d5-9ad0-e5419d9a3f69 completed.

Merging with the tracker graph

    $ know merge data/tracker.rdf urn:uuid:7ce4218b-343a-46c1-b13b-6b816c13be85

Saving the tracker graph to file

    $ know save data/tracker.rdf 
    Saving file:///home/urs/p/knowledge/data/tracker.rdf to /home/urs/p/knowledge/data/tracker.rdf ...
    $ cat data/tracker.rdf
    ...
    <rdf:Description rdf:about="private:tracker">
            <rdf:type rdf:resource="http://www.w3.org/2005/01/wf/flow#Tracker"/>
            <description xmlns="http://www.w3.org/2005/01/wf/flow#">My private tracker</description>
    </rdf:Description>

    <rdf:Description rdf:about="urn:uuid:126b72a8-cc93-4353-afd2-8ce7acdca5be">
            <rdf:type rdf:resource="http://www.w3.org/2005/01/wf/flow#Open"/>
            <description xmlns="http://www.w3.org/2005/01/wf/flow#">Finish publication of Carambola manual</description>
            <tracker xmlns="http://www.w3.org/2005/01/wf/flow#" rdf:resource="private:tracker"/>
            <dateDue xmlns="http://www.w3.org/2005/01/wf/flow#" rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2013-05-15</dateDue>
    </rdf:Description>

Stopping the SPARQL backend

    $ ./tomcat-instance/bin/shutdown.sh 
    ...
    Tomcat stopped 

=== License ===

pkb4unix is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.