Skip to content

Latest commit

 

History

History
189 lines (145 loc) · 7.14 KB

README.md

File metadata and controls

189 lines (145 loc) · 7.14 KB
Raw

Oook selector

This is the beginning of convenience tools for interacting with MarkLogic.

Oook -- is all the Librarian at the university of the Discworld ever utters. He is the sole staff member of the greatest database of knowledge, and as such offers a very versatile and helpful interface to it.

Warning

It is not even alpha but just some very early work and might change a lot.

Successor of XDBC selector

The Oook selector replaces XDBC selector. Oook selector now uses Oook instead of Cider Any; we decided to get rid of the backend design of cider-any and have a simpler interface that just lets you evaluate XQuery documents.

Installation

Please refer to the separate installation instructions for Oook selector.

If you haven't installed MarkLogic and just want to test Oook selector, you might want to follow our quick instructions to install MarkLogic Server.

Set up a Leiningen project

In order to use Oook selector, you have to start Cider REPL in a Leiningen project. The Uruk library must be pinned in the project.clj in the dependencies section, as Oook and Oook selector actually use Uruk to talk to MarkLogic via MarkLogic's XML Content Connector for Java (XCC/J).

If you don't program in Clojure but want to use the Oook selector to access your XML database, you can just use a stub gateway project. Just extract uruk-gw.tbz:

cd ~/src
tar xvfj oook-selector/uruk-gw.tbz

or recreate the stub project yourself by executing:

cd ~/src

lein new app uruk-gw

cat > uruk-gw/project.clj <<__EOL__
(defproject uruk-gw "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.8.0"]
                 [uruk "0.3.9"]]
  :main ^:skip-aot uruk-gw.core
  :target-path "target/%s"
  :profiles {:uberjar {:aot :all}})
__EOL__

Usage

To use Oook selector, you cider-jack-in to an Uruk project by opening the uruk-gw/project.clj file in Emacs and starting a Cider REPL by entering C-c m j.

You actually use Oook selector by invoking C-c m plus an additional letter. There is help available by pressing ?. With C-c m x, for example, you can just evaluate an XQuery from a minibuffer.

All other commands have usually a lowercase version for the current database, and a UPPERCASE one for the modules database of the current session/connection.

Complete list of available selector methods:

  • general methods:
    • C-c m ? - Selector help buffer
    • C-c m q - Quit / abort
  • Cider convenience functions:
    • C-c m j - (cider) Start an nREPL server for the current project and connect to it.
    • C-c m r - (cider) Select the REPL buffer, when possible in an existing window.
    • C-c m R - (cider) Switch to the last Clojure buffer.
  • simple XQuery evaluation:
    • C-c m x - Evaluate an XQuery from minibuffer
    • C-c m X - Evaluate an XQuery from minibuffer in the modules database
  • document management:
    • C-c m l - List documents †
    • C-c m L - List documents in the modules database †
    • C-c m s - Show document ‡
    • C-c m S - Show document in the modules database ‡
    • C-c m t - Show this document at point ‡
    • C-c m T - Show this document at point in the modules database ‡
    • C-c m u - Upload document ‡
    • C-c m U - Upload document into the modules database ‡
    • C-c m d - Delete document ‡
    • C-c m D - Delete document in the modules database
    • C-c m b - Set server path for current buffer ‡
    • C-c m B - Set database for current buffer ‡
  • database selection:
    • C-c m c - Choose/select database within current session/connection
    • C-c m . - Select default database of the server
    • C-c m , - Select modules database of the server
    • C-c m - - Show which database is currently used
    • C-c m / - Show which database is currently used

† Notes on the Document list

  • Press u to update the document list
  • Press <Return> on a document's URI to show the document at point (This is the same as entering C-c m t outside of a Document list.)
  • For paged output, set page limit with xdmp-set-page-limit. Use numerical prefix to switch to a different page.
  • Currently, it cannot list documents with an URL not beginning with a /.

‡ Notes server path and database of the current buffer

When a file is directly opened from MarkLogic using Show document (and friends) or uploaded at a new location, its server path and database are stored in buffer local variables.

"Upload document" and "Delete document" obey these variables, so that you can just update the document in MarkLogic or delete it from the database by entering C-c m u and C-c m d, respectively, from within the opened file buffer.

You can set those variables explicitly by entering C-c m b (set server path) and C-c m B (set database). To upload to a new path, you can also just enter a different path than the suggested when uploading by entering C-c m u.

Note on upload and delete document methods

To use upload and delete document you should have the file that is to be transfered or delete open in a buffer. If you fire the command the filename will be taken from the buffer and you will be interactively queried to enter a directory path. The file will be uploaded with a URI of <directory>/<filename>. Delete works analogously.

Selection of Document Upload Implementation

There are two implementations of xdmp-document-load. One is using xdmp:document-load, the other uruk.core/insert-string. Both variants have its pros and cons:

xdmp-document-load/xdmp-document-load

pro:

  • does work with binary files as well

con:

  • loads the file from the file system, ignores changes in the buffer that are not stored yet
  • needs file on the file system of the MarkLogic server
    • so it works only when you have MarkLogic on the same host as Emacs (usually, your localhost)

xdmp-document-load/uruk-insert-string

load document using new uruk.core/insert-string method of Uruk 0.3.7

pro:

  • also works if MarkLogic is installed on another host then the one where your Emacs runs
  • just uploads the current contents of the buffer even if it is has not been stored to disk yet
  • works for XML, JSON, and text files

con:

  • does not work for binary files
  • needs recent Uruk

Changing the default

By default, the uruk-insert-string variant is selected as it has the big plus of working with remote MarkLogic servers and just uploads the current buffer contents.

You might only want to change to the xdmp-document-load if, for example, you need to upload binary files such as images from Emacs directly.

To change the default, add this in your ~/.emacs or ~/.emacs.d/init.el:

(fset 'xdmp-document-load (symbol-function 'xdmp-document-load/xdmp-document-load))

somewhere after the line that loads the Oook Selector:

(require 'oook-setup  "~/src/oook-selector/oook-setup")