alexandria-zoom 0.6.0

data/README.md

@@ -0,0 +1,94 @@
+Ruby/ZOOM
+=========
+
+Ruby/ZOOM provides a Ruby binding to the Z39.50 Object-Orientation Model 
+(ZOOM), an abstract object-oriented programming interface to a subset of the 
+services specified by the Z39.50 standard, also known as the international 
+standard ISO 23950.
+
+This software is based (and therefore depends) on YAZ, a free-software 
+implementation of the Z39.50/SRW/SRU standards, but could be easily ported to 
+any ZOOM compliant implementation.
+
+Ruby/ZOOM is free-software, covered by the GNU Lesser General Public License 
+and provided without any warranties of any kind.
+
+Requirements
+------------
+
+    Ruby:       http://www.ruby-lang.org/
+    YAZ (*):    http://www.indexdata.dk/yaz/ 
+
+    * : Make sure you did pass the --enabled-shared option to the configure
+        script before building YAZ.  Ruby/ZOOM requires a YAZ shared library 
+        and YAZ does not build it by default. 
+
+Install
+-------
+
+    0. gem install alexandria-zoom
+
+Build from Source using bundler
+-----------------
+
+    0. add to your Gemfile:
+    gem "alexandria-zoom"
+    1. bundle
+
+Samples
+-------
+
+    Some programming examples are available in the `sample' directory. 
+
+Canonical Sample Program
+------------------------
+
+  To give a flavour of the Ruby binding, here is ZOOM's equivalent of the
+  ``Hello World'' program: a tiny Z39.50 client that fetches and displays
+  the MARC record for Farlow & Brett Surman's The Complete Dinosaur from
+  the Library of Congress.
+
+
+    require 'zoom'
+
+    ZOOM::Connection.open('z3950.loc.gov', 7090) do |conn|
+      conn.database_name = 'Voyager'
+      conn.preferred_record_syntax = 'USMARC'
+      rset = conn.search('@attr 1=7 0253333490')
+      p rset[0]
+    end
+
+ZOOM Extended Services
+----------------------
+
+  With release 0.4.1 extended services support has been added which allows
+  create, update and delete of records. This only works for XML.
+  Here's an example adapted from the test suite. 
+
+    require 'zoom'
+
+    new_record = File.read('programming_ruby.xml')
+
+    ZOOM::Connection.open('localhost:99999/test') do |conn|
+      p = conn.package
+      p.wait_action = 'waitIfPossible'
+      p.action = 'specialUpdate'
+      p.record = new_record
+      p.send('update')
+      p.send('commit')     
+    end
+
+
+Copying
+-------
+
+    Copyright (c) 2005 Laurent Sansonetti <lrz@chopine.be>
+      
+    This library is free software.
+    You can distribute/modify this program under the terms of
+    the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1.
+
+Project Website
+---------------
+
+    http://ruby-zoom.rubyforge.org

data/ext/zoom/extconf.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "pkg-config"
+
+unless PKGConfig.have_package("yaz")
+  warn "yaz development files do not appear to be installed"
+  exit(false)
+end
+
+unless have_header("yaz/zoom.h")
+  warn "yaz zoom header not available"
+  exit
+end
+
+append_cflags PKGConfig.cflags("yaz")
+append_ldflags PKGConfig.libs("yaz")
+
+create_makefile("zoom")

data/ext/zoom/rbzoom.c

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2005 Laurent Sansonetti <lrz@chopine.be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#include "rbzoom.h"
+
+
+void
+Init_zoom (void)
+{
+    VALUE mZoom;
+
+    mZoom = rb_define_module ("ZOOM");
+
+    Init_zoom_connection (mZoom);
+    Init_zoom_query (mZoom);
+    Init_zoom_resultset (mZoom);
+    Init_zoom_record (mZoom);
+    Init_zoom_package (mZoom);
+}

data/ext/zoom/rbzoom.h

@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2005 Laurent Sansonetti <lrz@chopine.be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#ifndef __RBZOOM_H_
+#define __RBZOOM_H_
+
+#include <yaz/zoom.h>
+#include <ruby.h>
+#include <assert.h>
+
+/* initialization */
+void Init_zoom (void);
+void Init_zoom_connection (VALUE mZoom);
+void Init_zoom_query (VALUE mZoom);
+void Init_zoom_resultset (VALUE mZoom);
+void Init_zoom_record (VALUE mZoom);
+void Init_zoom_package (VALUE mZoom);
+
+/* rbzoomoptions.c */
+ZOOM_options ruby_hash_to_zoom_options (VALUE hash);
+VALUE zoom_option_value_to_ruby_value (const char *value);
+void define_zoom_option (VALUE klass, const char *option);
+
+/* rbzoomparse.c */
+ZOOM_query rbz_query_get (VALUE obj);
+
+/* rbzoomresultset.c */
+VALUE rbz_resultset_make (ZOOM_resultset resultset);
+
+/* rbzoomrecord.c */
+VALUE rbz_record_make (ZOOM_record record);
+
+/* rbzoompackage.c */
+VALUE rbz_package_make (ZOOM_connection connection, ZOOM_options options);
+
+/* rbconnection.c */
+void rbz_connection_check(VALUE obj); 
+        
+/* useful macros */
+#if !defined (RVAL2CSTR)
+# define RVAL2CSTR(x)       (NIL_P (x) ? NULL : RSTRING_PTR(x))
+#endif
+#if !defined (CSTR2RVAL)
+# define CSTR2RVAL(x)       (x == NULL ? Qnil : rb_str_new2(x))
+#endif
+#if !defined (RVAL2CBOOL)
+# define RVAL2CBOOL(x)      (RTEST (x))
+#endif
+#if !defined (CBOOL2RVAL)
+# define CBOOL2RVAL(x)      (x ? Qtrue : Qfalse)
+#endif
+
+#endif /* __RBZOOM_H_ */

data/ext/zoom/rbzoomconnection.c

@@ -0,0 +1,346 @@
+/*
+ * Copyright (C) 2005 Laurent Sansonetti <lrz@chopine.be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#include "rbzoom.h"
+
+#ifdef MAKING_RDOC_HAPPY
+mZoom = rb_define_module("ZOOM");
+#endif
+
+
+/* Document-class: ZOOM::Connection
+ * The Connection object is a session with a target.
+ */
+static VALUE cZoomConnection;
+
+
+static VALUE
+rbz_connection_make (ZOOM_connection connection)
+{
+    return connection != NULL
+        ? Data_Wrap_Struct (cZoomConnection,
+                            NULL,
+                            ZOOM_connection_destroy,
+                            connection)
+        : Qnil;
+}
+
+static ZOOM_connection
+rbz_connection_get (VALUE obj)
+{
+    ZOOM_connection connection;
+        
+    Data_Get_Struct (obj, struct ZOOM_connection_p, connection);
+    assert (connection != NULL);
+
+    return connection;
+}
+
+#define RAISE_IF_FAILED(connection)                     \
+    do {                                                \
+        int error;                                      \
+        const char *errmsg;                             \
+        const char *addinfo;                            \
+                                                        \
+        error = ZOOM_connection_error (connection,      \
+                                       &errmsg,         \
+                                       &addinfo);       \
+        if (error != 0)                                 \
+            rb_raise (rb_eRuntimeError, "%s (%d) %s",   \
+                      errmsg, error, addinfo);          \
+    }                                                   \
+    while (0)
+
+void rbz_connection_check(VALUE obj)
+{
+	ZOOM_connection connection;
+	
+	connection = rbz_connection_get(obj);
+  	RAISE_IF_FAILED (connection);
+}
+
+
+/*
+ * call-seq: 
+ * 	open(host, port=nil) { |conn| ... }
+ *
+ * host: hostname of the target to connect to.
+ *
+ * port: network port of the target to connect to.
+ *
+ * A convenience method that creates a new connection and attempts to 
+ * establish a network connection to the given target, basically calling
+ * ZOOM::Connection.new and ZOOM::Connection#connect.
+ *  
+ * If a block is given, then it will be called once the connection is 
+ * established, passing a reference to the connection object as a parameter, 
+ * and destroying the connection automatically at the end of the block.
+ * With no block, this method just returns the connection object.
+ *
+ * Returns: a newly created ZOOM::Connection object.
+ */
+static VALUE
+rbz_connection_open (int argc, VALUE *argv, VALUE self)
+{
+    VALUE host;
+    VALUE port;
+    ZOOM_connection connection;
+    VALUE rb_connection;
+    
+    rb_scan_args (argc, argv, "11", &host, &port);
+
+    connection = ZOOM_connection_new (RVAL2CSTR (host),
+                                      NIL_P (port) ? 0 : FIX2INT (port));
+    RAISE_IF_FAILED (connection);
+    
+    rb_connection = rbz_connection_make (connection);
+    if (rb_block_given_p ()) {
+        rb_yield(rb_connection);
+        return Qnil;
+    }
+    return rb_connection;
+}
+
+/*
+ * call-seq: new(options=nil)
+ *
+ * options: options for the connection, as a Hash object.
+ *
+ * Creates a new connection object, but does not establish a network connection
+ * immediately, allowing you to specify options before (if given). You can 
+ * thus establish the connection using ZOOM::Connection#connect.
+ * 
+ * Returns: a newly created ZOOM::Connection object.
+ */
+static VALUE
+rbz_connection_new (int argc, VALUE *argv, VALUE self)
+{
+    ZOOM_options options;
+    ZOOM_connection connection;
+    VALUE rb_options;
+    
+    rb_scan_args (argc, argv, "01", &rb_options);
+
+    if (NIL_P (rb_options))
+        options = ZOOM_options_create ();
+    else
+        options = ruby_hash_to_zoom_options (rb_options);
+
+    connection = ZOOM_connection_create (options);
+    ZOOM_options_destroy (options);
+    RAISE_IF_FAILED (connection);
+
+    return rbz_connection_make (connection);
+}
+
+/*
+ * call-seq:
+ * 	connect(host, port=nil)
+ *
+ * host: hostname of the target to connect to.
+ *
+ * port: network port of the target to connect to.
+ *
+ * Establishes a network connection to the target specified by the given
+ * arguments.  If no port is given, 210 will be used.  A colon in the host
+ * string denotes the beginning of a port number.  If the host string includes
+ * a slash, the following part specifies a database for the connection.
+ *
+ * You can also prefix the host string with a scheme followed by a colon.
+ * The default scheme is tcp (Z39.50 protocol).  The scheme http selects SRW
+ * over HTTP.
+ *
+ * This method raises an exception on error.
+ *
+ * Returns: self.
+ */
+static VALUE
+rbz_connection_connect (int argc, VALUE *argv, VALUE self)
+{
+    ZOOM_connection connection;
+    VALUE host;
+    VALUE port;
+    
+    rb_scan_args (argc, argv, "11", &host, &port);
+  
+    connection = rbz_connection_get (self);
+    ZOOM_connection_connect (connection, 
+                             RVAL2CSTR (host), 
+                             NIL_P (port) ? 0 : FIX2INT (port));
+    RAISE_IF_FAILED (connection); 
+
+    return self;
+}
+
+/*
+ * call-seq:
+ * 	set_option(key, value)
+ *
+ * key: the name of the option, as a string.
+ *
+ * value: the value of this option (as a string, integer or boolean).
+ *
+ * Sets an option on the connection.
+ * 
+ * Returns: self.
+ */
+static VALUE
+rbz_connection_set_option (VALUE self, VALUE key, VALUE val)
+{
+    ZOOM_connection connection;
+    
+    connection = rbz_connection_get (self);
+    ZOOM_connection_option_set (connection,
+                                RVAL2CSTR (key),
+                                RVAL2CSTR (rb_obj_as_string (val)));
+    RAISE_IF_FAILED (connection); 
+    
+    return self;
+}
+
+/*
+ * call-seq: 
+ * 	get_option(key)
+ *
+ * key: the name of the option, as a string.
+ *
+ * Gets the value of a connection's option.
+ * 
+ * Returns: the value of the given option, as a string, integer or boolean.
+ */
+static VALUE
+rbz_connection_get_option (VALUE self, VALUE key)
+{
+    ZOOM_connection connection;
+    const char *value;
+ 
+    connection = rbz_connection_get (self);
+    value = ZOOM_connection_option_get (connection,
+                                        RVAL2CSTR (key));
+
+    return zoom_option_value_to_ruby_value (value);
+}
+
+/*
+ * call-seq: 
+ * 	search(criterion)
+ *
+ * criterion: the search criterion, either as a ZOOM::Query object or as a string,
+ * representing a PQF query.
+ *  
+ * Searches the connection from the given criterion.  You can either create and
+ * pass a reference to a ZOOM::Query object, or you can simply pass a string
+ * that represents a PQF query.
+ *
+ * This method raises an exception on error.
+ * 
+ * Returns: a result set from the search, as a ZOOM::ResultSet object,
+ * empty if no results were found.
+ */
+static VALUE
+rbz_connection_search (VALUE self, VALUE criterion)
+{
+    ZOOM_connection connection;
+    ZOOM_resultset resultset;
+
+    connection = rbz_connection_get (self);
+    if (TYPE (criterion) == T_STRING)
+        resultset = ZOOM_connection_search_pqf (connection,
+                                                RVAL2CSTR (criterion));
+    else
+        resultset = ZOOM_connection_search (connection,
+                                            rbz_query_get (criterion));
+    RAISE_IF_FAILED (connection); 
+    assert (resultset != NULL);
+  
+    return rbz_resultset_make (resultset);
+}
+
+
+/*
+ * Constructs a new extended services ZOOM::Package using this connections host information.
+ *
+ * Note: The Perl script passes this connections options if already set, otherwise constructs a new ZOOM::Option object. 
+ * Currently this method always constructs a new ZOOM::Option object for each package.
+ * 
+ * Returns: a new ZOOM::Package object.
+ */
+static VALUE
+rbz_connection_package(VALUE self)
+{
+  ZOOM_connection connection;
+  ZOOM_options options;
+  VALUE package;
+
+  connection = rbz_connection_get (self);
+  options = ZOOM_options_create ();
+  package = rbz_package_make(connection, options);
+  return package;
+}
+
+
+void
+Init_zoom_connection (VALUE mZoom)
+{
+    VALUE c;
+
+    c = rb_define_class_under (mZoom, "Connection", rb_cObject); 
+    rb_undef_alloc_func(c);
+
+    rb_define_singleton_method (c, "open", rbz_connection_open, -1);
+    rb_define_singleton_method (c, "new", rbz_connection_new, -1);
+    rb_define_method (c, "connect", rbz_connection_connect, -1);
+    rb_define_method (c, "set_option", rbz_connection_set_option, 2);
+    rb_define_method (c, "get_option", rbz_connection_get_option, 1);
+    rb_define_method (c, "package", rbz_connection_package, 0);
+
+    define_zoom_option (c, "implementationName");
+    define_zoom_option (c, "user");
+    define_zoom_option (c, "group");
+    define_zoom_option (c, "password");
+    define_zoom_option (c, "host");
+    define_zoom_option (c, "proxy");
+    define_zoom_option (c, "async");
+    define_zoom_option (c, "maximumRecordSize");
+    define_zoom_option (c, "preferredMessageSize");
+    define_zoom_option (c, "lang");
+    define_zoom_option (c, "charset");
+    define_zoom_option (c, "serverImplementationId");
+    define_zoom_option (c, "targetImplementationName");
+    define_zoom_option (c, "serverImplementationVersion");
+    define_zoom_option (c, "databaseName");
+    define_zoom_option (c, "piggyback");
+    define_zoom_option (c, "smallSetUpperBound");
+    define_zoom_option (c, "largeSetLowerBound");
+    define_zoom_option (c, "mediumSetPresentNumber");
+    define_zoom_option (c, "smallSetElementSetName");
+    define_zoom_option (c, "mediumSetElementSetName");
+
+    /* herited from Zoom::ResultSet */
+    define_zoom_option (c, "start");
+    define_zoom_option (c, "count");
+    define_zoom_option (c, "presentChunk");
+    define_zoom_option (c, "elementSetName");
+    define_zoom_option (c, "preferredRecordSyntax");
+    define_zoom_option (c, "schema");
+    define_zoom_option (c, "setname");
+    
+    rb_define_method (c, "search", rbz_connection_search, 1);
+    
+    cZoomConnection = c;
+}

data/ext/zoom/rbzoomoptions.c

@@ -0,0 +1,121 @@
+/*
+ * Copyright (C) 2005 Laurent Sansonetti <lrz@chopine.be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#include <ctype.h>
+#include "rbzoom.h"
+
+ZOOM_options
+ruby_hash_to_zoom_options (VALUE hash)
+{
+    ZOOM_options options;
+    VALUE ary;
+    VALUE pair;
+    VALUE key;
+    VALUE value;
+    int i;
+
+    options = ZOOM_options_create ();
+    
+    ary = rb_funcall (hash, rb_intern ("to_a"), 0);
+    for (i = 0; i < RARRAY_LEN(ary); i++) {
+        pair = RARRAY_PTR(ary)[i];
+        key = RARRAY_PTR(pair)[0];
+        value = RARRAY_PTR(pair)[1];
+        
+        switch (TYPE (value)) {
+            case T_TRUE:
+            case T_FALSE:
+                ZOOM_options_set_int (options, 
+                                      RVAL2CSTR (key),
+                                      RVAL2CBOOL (value) ? 1 : 0);
+                break;
+
+            case T_FIXNUM:
+                ZOOM_options_set_int (options, 
+                                      RVAL2CSTR (key),
+                                      FIX2INT (value));
+                break;
+                
+            case T_STRING:
+                ZOOM_options_set (options, 
+                                  RVAL2CSTR (key), 
+                                  RVAL2CSTR (value));
+                break;
+
+            default:
+                rb_raise (rb_eArgError, "Unrecognized type");        
+        }
+    }        
+
+    return options;
+}
+
+VALUE
+zoom_option_value_to_ruby_value (const char *value)
+{
+    unsigned int i;
+
+    if (value == NULL)
+        return Qnil; 
+
+    for (i = 0; i < strlen (value); i++)
+        if (!isdigit (value [i]))
+            return CSTR2RVAL (value);
+
+    return INT2FIX (atoi (value));
+}
+
+void
+define_zoom_option (VALUE klass, const char *option)
+{
+    char code [1024];
+    char rubyname [128];
+    char c;
+    unsigned int i;
+    unsigned int j;
+   
+    /* rubyfy the option name */
+    for (i = 0, j = 0; i < strlen (option) && j < sizeof rubyname; i++, j++) {
+        c = option [i];
+        if (isupper (c)) {
+            rubyname [j++] = '_';
+            c = tolower (c);
+        }
+		else if (c == '-')
+		{
+			c = '_';
+		}
+		else if (c == '.')
+		{
+			c = '_';
+		}
+		
+        rubyname [j] = c;
+    }
+    rubyname [j] = '\0';
+
+    snprintf (code, sizeof code, 
+              "def %s; get_option(\"%s\"); end\n"
+              "def %s=(val); set_option(\"%s\", val); val; end\n"
+              "def set_%s(val); set_option(\"%s\", val); end\n",
+              rubyname, option,
+              rubyname, option,
+              rubyname, option);
+             
+    rb_funcall (klass, rb_intern ("module_eval"), 1, CSTR2RVAL (code));
+}