linkparser 1.0.3

data/ext/dictionary.c

@@ -0,0 +1,269 @@
+/*
+ *  dict.c - Ruby LinkParser - Dictionary Class
+ *  $Id: dictionary.c 48 2008-12-19 18:30:33Z deveiant $
+ *  
+ *  Authors:
+ *    * Michael Granger <ged@FaerieMUD.org>
+ *  
+ *  Please see the LICENSE file at the top of the distribution for licensing 
+ *  information.
+ */
+
+#include "linkparser.h"
+
+
+/* --------------------------------------------------
+ *  Memory management functions
+ * -------------------------------------------------- */
+
+/*
+ * Free function
+ */
+static void
+rlink_dict_gc_free( Dictionary dict ) {
+	if ( dict ) dictionary_delete( dict );
+}
+
+
+/*
+ * Object validity checker. Returns the data pointer.
+ */
+static Dictionary
+check_dict( VALUE self ) {
+	Check_Type( self, T_DATA );
+
+    if ( !IsDictionary(self) ) {
+		rb_raise( rb_eTypeError, "wrong argument type %s (expected LinkParser::Dictionary)",
+				  rb_class2name(CLASS_OF( self )) );
+    }
+	
+	return DATA_PTR( self );
+}
+
+
+/*
+ * Fetch the data pointer and check it for sanity.
+ */
+static Dictionary
+get_dict( VALUE self ) {
+	Dictionary dict = check_dict( self );
+
+	if ( !dict )
+		rb_raise( rb_eRuntimeError, "uninitialized Dictionary" );
+
+	return dict;
+}
+
+
+/* 
+ * Get the Dictionary behind the LinkParser::Dictionary +object+ specified.
+ */ 
+Dictionary
+rlink_get_dict( VALUE obj ) {
+	return get_dict( obj );
+}
+
+
+
+/* --------------------------------------------------
+ * Class Methods
+ * -------------------------------------------------- */
+
+
+/*
+ *  call-seq:
+ *     LinkParser::Dictionary.allocate   -> dict
+ *
+ *  Allocate a new LinkParser::Dictionary object.
+ */
+static VALUE
+rlink_dict_s_alloc( VALUE klass ) {
+	debugMsg(( "Wrapping an uninitialized Dictionary pointer." ));
+	return Data_Wrap_Struct( klass, 0, rlink_dict_gc_free, 0 );
+}
+
+
+/*
+ * Make a Dictionary with explicit datafile arguments. This is largely unnecessary, but
+ * can be useful for testing and stuff.
+ */
+static Dictionary
+rlink_make_oldstyle_dict( VALUE dict_file, VALUE pp_file, VALUE cons_file, VALUE affix_file ) {
+	SafeStringValue( dict_file  );
+	SafeStringValue( pp_file    );
+	SafeStringValue( cons_file  );
+	SafeStringValue( affix_file );
+	
+	return dictionary_create(
+		STR2CSTR( dict_file  ),
+		STR2CSTR( pp_file    ),
+		STR2CSTR( cons_file  ),
+		STR2CSTR( affix_file )
+	);
+}
+
+
+/*
+ *  call-seq:
+ *    LinkParser::Dictionary.new( options={} )
+ *    LinkParser::Dictionary.new( language, options={} )
+ *    LinkParser::Dictionary.new( dict, pp, ck, affix, option={} )
+ * 
+ *  Create a new LinkParser::Dictionary with data files for the given +language+, or
+ *  using the specified data files.
+ *
+ */
+static VALUE
+rlink_dict_initialize( int argc, VALUE *argv, VALUE self ) {
+	if ( !check_dict(self) ) {
+		int i = 0;
+		Dictionary dict = NULL;
+		VALUE arg1, arg2, arg3, arg4, arg5 = Qnil;
+		VALUE lang = Qnil;
+		VALUE opthash = Qnil;
+		
+		switch( i = rb_scan_args(argc, argv, "05", &arg1, &arg2, &arg3, &arg4, &arg5) ) {
+		  /* Dictionary.new */
+		  case 0:
+			debugMsg(( "No arguments" ));
+			break;
+
+		  /* Dictionary.new( lang )*/
+		  /* Dictionary.new( opthash )*/
+		  case 1:
+			if( TYPE(arg1) == T_HASH ) {
+				debugMsg(( "One arg: options hash."));
+				opthash = arg1;
+			} else {
+				debugMsg(( "One arg: language" ));
+				lang = arg1;
+			}
+			break;
+
+		  /* Dictionary.new( lang, opthash ) */
+		  case 2:
+			debugMsg(( "Two args: language and options hash."));
+			lang = arg1;
+			opthash = arg2;
+			break;
+
+		  /* Dictionary.new( dict, pp, cons, affix ) */
+		  /* Dictionary.new( dict, pp, cons, affix, opthash ) */
+		  case 4:
+		  case 5:
+			debugMsg(( "Four or five args: old-style explicit dict files." ));
+			dict = rlink_make_oldstyle_dict( arg1, arg2, arg3, arg4 );
+			opthash = arg5;
+			break;
+		
+		  /* Anything else is an error */	
+		  default:
+			rb_raise( rb_eArgError, 
+				"wrong number of arguments (%d for 0,1,2,4, or 5)", i );
+		}
+
+		/* Create the dictionary if it hasn't been already */
+		if ( !dict && i < 4 ) {
+			if ( RTEST(lang) ) {
+				SafeStringValue( lang );
+				dict = dictionary_create_lang( STR2CSTR(lang) );
+			} else {
+				dict = dictionary_create_default_lang();
+			}
+		}
+		
+		/* If the dictionary still isn't created, there was an error
+		   creating it */
+		if ( !dict ) rlink_raise_lp_error();
+
+		DATA_PTR( self ) = dict;
+
+		/* If they passed in an options hash, save it for later. */
+		if ( RTEST(opthash) ) rb_iv_set( self, "@options", opthash );
+		else rb_iv_set( self, "@options", rb_hash_new() );
+	}
+
+	else {
+		rb_raise( rb_eRuntimeError, "Cannot re-initialize a Dictionary object." );
+	}
+
+	return Qnil;
+}
+
+
+/*
+ *  call-seq:
+ *     dictionary.max_cost   -> fixnum
+ *
+ *  Returns the maximum cost (number of brackets []) that is placed on any
+ *  connector in the dictionary. This is useful for designing a parsing
+ *  algorithm that progresses in stages, first trying the cheap connectors.
+ */
+static VALUE 
+rlink_get_max_cost( VALUE self ) {
+	Dictionary dict = get_dict( self );
+	int cost = dictionary_get_max_cost( dict );
+	
+	debugMsg(( "Max cost is: %d", cost ));
+	
+	return INT2NUM( cost );
+}
+
+
+/*
+ *  call-seq:
+ *     dictionary.parse( string )            -> sentence
+ *     dictionary.parse( string, options )   -> sentence
+ *
+ *  Parse the specified sentence +string+ with the dictionary and return a 
+ *  LinkParser::Sentence. If you specify an +options+ hash, its values will override
+ *  those of the Dictionary's for the resulting Sentence.
+ */
+static VALUE 
+rlink_parse( int argc, VALUE *argv, VALUE self ) {
+	VALUE input_string, options, sentence;
+	VALUE args[2];
+	int i;
+
+	i = rb_scan_args( argc, argv, "11", &input_string, &options );
+
+	/* Create the new sentence */
+	args[0] = input_string;
+	args[1] = self;
+	sentence = rb_class_new_instance( 2, args, rlink_cSentence );
+	
+	/* Now call #parse on it */
+	if ( i == 1 )
+		rb_funcall( sentence, rb_intern("parse"), 0, 0 );
+	else
+		rb_funcall( sentence, rb_intern("parse"), 1, options );
+	
+	return sentence;
+}
+
+
+
+
+
+/* 
+ *  Document-class: LinkParser::Dictionary
+ *  
+ *  A Dictionary is the programmer's handle on the set of word definitions that defines the
+ *  grammar. A user creates a Dictionary from a grammar file and post-process knowledge
+ *  file, and then creates all other objects through it.
+ */
+void
+rlink_init_dict() {
+	rlink_cDictionary = rb_define_class_under( rlink_mLinkParser, "Dictionary",
+	 	rb_cObject );
+	
+	rb_define_alloc_func( rlink_cDictionary, rlink_dict_s_alloc );
+	rb_define_method( rlink_cDictionary, "initialize", rlink_dict_initialize, -1 );
+
+	rb_define_method( rlink_cDictionary, "max_cost", rlink_get_max_cost, 0 );
+	rb_define_method( rlink_cDictionary, "parse", rlink_parse, -1 );
+
+	/* The LinkParser::ParseOptions object for the Dictionary */
+	rb_define_attr( rlink_cDictionary, "options", 1, 0 );
+}
+

data/ext/extconf.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+require 'mkmf'
+
+ADDITIONAL_LIBRARY_DIRS = %w[
+	/usr/local/lib
+	/opt/lib
+	/opt/local/lib
+]
+ADDITIONAL_INCLUDE_DIRS = %w[
+	/usr/local/include
+	/opt/include
+	/opt/local/include
+]
+
+$CFLAGS << ' -Wall' << ' -DDEBUG'
+
+def fail( *messages )
+	$stderr.puts( *messages )
+	exit 1
+end
+
+
+dir_config( 'link-grammar' )
+
+
+find_library( "link-grammar", "dictionary_create", *ADDITIONAL_LIBRARY_DIRS ) or
+	fail( "Could not find Link-Grammar library", 
+	      "(http://www.abisource.com/projects/link-grammar/#download)." )
+find_header( "link-grammar/link-includes.h", *ADDITIONAL_INCLUDE_DIRS ) or
+	fail( "Could not find link-includes.h" )
+
+unless have_func( "linkage_free_diagram", 'link-grammar/link-includes.h' )
+	message "Your link-grammar library is too old for this binding.\n",
+	        "Please upgrade to the latest version posted here:\n",
+	        "  http://www.abisource.com/projects/link-grammar/#download\n",
+	        "and try again.\n"
+	fail "No linkage_free_diagram() in the installed link-grammar."
+end
+
+unless have_func( "linkage_get_current_sublinkage" )
+	message "Link grammar library is unpatched. Building anyways.\n"
+	message "  LinkParser::Linkage#current_sublinkage will not work,\n"
+	message "  but everything else will work okay.\n"
+end
+
+unless have_func( "linkgrammar_get_version" )
+	message "You are building with an older, unsupported version of the link-grammar\n"
+	message " library. If you encounter problems, please update it to 4.4.0 or later.\n"
+	message "Trying to build anyway.\n"
+end
+
+create_makefile( 'linkparser_ext' )

data/ext/linkage.c

@@ -0,0 +1,894 @@
+/*
+ *  linkage.c - Ruby LinkParser Linkage class
+ *  $Id: linkage.c 48 2008-12-19 18:30:33Z deveiant $
+ *  
+ *  Authors:
+ *    * Michael Granger <ged@FaerieMUD.org>
+ *  
+ *  Please see the LICENSE file at the top of the distribution for licensing 
+ *  information.
+ */
+
+#include "linkparser.h"
+
+
+/* --------------------------------------------------
+ *  Forward declarations
+ * -------------------------------------------------- */
+
+static VALUE rlink_linkage_make_cnode_array( CNode * );
+
+
+/* --------------------------------------------------
+ * Macros and constants
+ * -------------------------------------------------- */
+
+
+/* --------------------------------------------------
+ *	Memory-management functions
+ * -------------------------------------------------- */
+/*
+ * Allocation function
+ */
+static rlink_LINKAGE *
+rlink_linkage_alloc() {
+	rlink_LINKAGE *ptr = ALLOC( rlink_LINKAGE );
+	
+	ptr->linkage	= NULL;
+	ptr->sentence	= Qnil;
+	
+	debugMsg(( "Initialized an rlink_LINKAGE <%p>", ptr ));
+	return ptr;
+}
+
+
+/*
+ * GC Mark function
+ */
+static void
+rlink_linkage_gc_mark( rlink_LINKAGE *ptr ) {
+	debugMsg(( "Marking LinkParser::Linkage %p", ptr ));
+	
+	if ( ptr ) {
+		rb_gc_mark( ptr->sentence );
+	}
+	
+	else {
+		debugMsg(( "Not marking uninitialized rlink_LINKAGE" ));
+	}
+}
+
+
+/*
+ * GC Free function
+ */
+static void
+rlink_linkage_gc_free( rlink_LINKAGE *ptr ) {
+	if ( ptr ) {
+		linkage_delete( (Linkage)ptr->linkage );
+		ptr->linkage = NULL;
+		ptr->sentence = Qnil;
+	}
+	
+	else {
+		debugMsg(( "Not freeing an uninitialized rlink_LINKAGE" ));
+	}
+}
+
+
+/*
+ * Object validity checker. Returns the data pointer.
+ */
+static rlink_LINKAGE *
+check_linkage(  VALUE	self ) {
+	Check_Type( self, T_DATA );
+
+    if ( !IsLinkage(self) ) {
+		rb_raise( rb_eTypeError, "wrong argument type %s (expected LinkParser::Linkage)",
+				  rb_class2name(CLASS_OF( self )) );
+    }
+	
+	return DATA_PTR( self );
+}
+
+
+/*
+ * Fetch the data pointer and check it for sanity.
+ */
+static rlink_LINKAGE *
+get_linkage(  VALUE self ) {
+	rlink_LINKAGE *ptr = check_linkage( self );
+
+	if ( !ptr )
+		rb_raise( rb_eRuntimeError, "uninitialized Linkage" );
+
+	return ptr;
+}
+
+
+/*
+ * Publicly-usable linkage-fetcher
+ */
+rlink_LINKAGE *
+rlink_get_linkage( self ) {
+	return get_linkage( self );
+}
+
+
+
+/*
+ *  call-seq:
+ *     LinkParser::Linkage.allocate   -> LinkParser::Linkage
+ *
+ *  Allocate a new LinkParser::Linkage object.
+ */
+static VALUE
+rlink_linkage_s_alloc(  VALUE klass ) {
+	debugMsg(( "Wrapping an uninitialized Linkage pointer." ));
+	return Data_Wrap_Struct( klass, rlink_linkage_gc_mark, rlink_linkage_gc_free, 0 );
+}
+
+
+/*
+ *  call-seq:
+ *     new( index, sentence, options={} )   -> LinkParser::Linkage
+ *
+ *  Create a new LinkParser::Linkage object out of the linkage indicated by
+ *  +index+ (a positive Integer) from the specified sentence (a 
+ *  LinkParser::Sentence). The optional options hash can be used to override
+ *  the parse options of the Sentence for the new linkage.
+ */
+static VALUE
+rlink_linkage_init( argc, argv, self )
+	int argc;
+	VALUE *argv;
+	VALUE self;
+{
+	if ( !check_linkage(self) ) {
+		int i, link_index, max_index;
+		VALUE index, sentence, options, defopts;
+		rlink_SENTENCE *sent_ptr;
+		Linkage linkage;
+		Parse_Options opts;
+		rlink_LINKAGE *ptr;
+		
+		i = rb_scan_args( argc, argv, "21", &index, &sentence, &options );
+
+		defopts = rb_hash_new(); /*rb_funcall( sentence, rb_intern("options"), 0 );*/
+		options = rlink_make_parse_options( defopts, options );
+		opts = rlink_get_parseopts( options );
+
+		sent_ptr = (rlink_SENTENCE *)rlink_get_sentence( sentence );
+
+		link_index = NUM2INT(index);
+		max_index = sentence_num_valid_linkages((Sentence)sent_ptr->sentence) - 1;
+		if ( link_index > max_index )
+			rb_raise( rlink_eLpError, "Invalid linkage %d (max is %d)", 
+				link_index, max_index );
+
+		linkage = linkage_create( link_index, (Sentence)sent_ptr->sentence, opts );
+		if ( !linkage ) rlink_raise_lp_error();
+
+		DATA_PTR( self ) = ptr = rlink_linkage_alloc();
+		
+		ptr->linkage = linkage;
+		ptr->sentence = sentence;
+	}
+	
+	else {
+		rb_raise( rb_eRuntimeError,
+				  "Cannot re-initialize a linkage once it's been created." );
+	}
+	
+	return Qnil;
+}
+
+
+
+/*
+ *  call-seq:
+ *     diagram   -> str
+ *
+ *  Return a String containing a diagram of the linkage.
+ */
+static VALUE
+rlink_linkage_diagram( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	char *diagram_cstr;
+	VALUE diagram;
+	
+	diagram_cstr = linkage_print_diagram( (Linkage)ptr->linkage );
+	diagram = rb_str_new2( diagram_cstr );
+	linkage_free_diagram( diagram_cstr );
+	
+	return diagram;
+}
+
+
+/*
+ *  call-seq:
+ *     postscript_diagram( full_doc=false )   -> str
+ *
+ *  Returns the macros needed to print out the linkage in a postscript file. 
+ *  By default, the output is just the set of postscript macros that describe 
+ *  the diagram. With full_doc=true a complete encapsulated postscript document 
+ *  is returned.
+ */
+static VALUE
+rlink_linkage_print_postscript( VALUE self, VALUE full_doc ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	char *diagram_cstr;
+	VALUE diagram;
+	
+	diagram_cstr = linkage_print_postscript( (Linkage)ptr->linkage,
+		RTEST(full_doc) ? 1 : 0 );
+	diagram = rb_str_new2( diagram_cstr );
+	linkage_free_postscript( diagram_cstr );
+	
+	return diagram;
+}
+
+
+/*
+ *  call-seq:
+ *     links_and_domains   -> str
+ *
+ *  Return a String containing a lists all of the links and domain names for 
+ *  the current sublinkage.
+ *
+ *  Example:
+ *    sent = dict.parse("I eat, therefore I think")
+ *    puts sent.linkages.first.links_and_domains
+ *  
+ *  prints:
+ *              /////          RW      <---RW---->  RW        /////
+ *    (m)       /////          Wd      <---Wd---->  Wd        I.p
+ *    (m)       I.p            CC      <---CC---->  CC        therefore
+ *    (m)       I.p            Sp*i    <---Sp*i-->  Sp        eat
+ *    (m)       ,              Xd      <---Xd---->  Xd        therefore
+ *    (m) (m)   therefore      Wd      <---Wd---->  Wd        I.p
+ *    (m) (m)   I.p            Sp*i    <---Sp*i-->  Sp        think.v
+ * 
+ */
+static VALUE
+rlink_linkage_links_and_domains( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	char *diagram_cstr;
+	VALUE diagram;
+	
+	diagram_cstr = linkage_print_links_and_domains( (Linkage)ptr->linkage );
+	diagram = rb_str_new2( diagram_cstr );
+	linkage_free_links_and_domains( diagram_cstr );
+	
+	return diagram;
+}
+
+
+
+/*
+ *  call-seq:
+ *     num_sublinkages   -> fixnum
+ *
+ *  Return the number of sublinkages for a linkage with conjunctions, 1 
+ *  otherwise.
+ */
+static VALUE
+rlink_linkage_num_sublinkages( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	return INT2FIX( linkage_get_num_sublinkages((Linkage)ptr->linkage) );
+}
+
+
+/*
+ *  call-seq:
+ *     current_sublinkage = index   -> true or false
+ *
+ *  After this call, all operations on the linkage will refer to the index-th 
+ *  sublinkage. In the case of a linkage without conjunctions, this has no 
+ *  effect.
+ */
+static VALUE
+rlink_linkage_current_sublinkage_eq( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval = 0;
+	
+	rval = linkage_set_current_sublinkage( (Linkage)ptr->linkage, NUM2INT(index) );
+	
+	return INT2FIX( rval );
+}
+
+
+/*
+ *  call-seq:
+ *     current_sublinkage   -> fixnum
+ *
+ *  Get the index of the current sublinkage.
+ */
+static VALUE
+rlink_linkage_current_sublinkage( VALUE self ) {
+
+#ifdef HAVE_LINKAGE_GET_CURRENT_SUBLINKAGE
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval = 0;
+
+	rval = linkage_get_current_sublinkage( (Linkage)ptr->linkage );
+	
+	return INT2FIX( rval );
+#else
+	rb_notimplement();
+#endif
+}
+
+
+/*
+ * num_words
+ * --
+ * The number of words in the sentence for which this is a linkage. Note that 
+ * this function does not return the number of words used in the current 
+ * sublinkage.
+ */
+static VALUE
+rlink_linkage_get_num_words( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	return INT2FIX( linkage_get_num_words((Linkage)ptr->linkage) );
+}
+
+
+/*
+ * num_links
+ * --
+ * The number of links used in the current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_num_links( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	return INT2FIX( linkage_get_num_links((Linkage)ptr->linkage) );
+}
+
+
+/*
+ * link_lword( index )
+ * --
+ * The number of the word on the left end of the index-th link of the 
+ * current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_link_lword( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	
+	return INT2FIX( linkage_get_link_lword((Linkage)ptr->linkage, i) );
+}
+
+
+/*
+ * link_rword( index )
+ * --
+ * The number of the word on the right end of the index-th link of the 
+ * current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_link_rword( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	
+	return INT2FIX( linkage_get_link_rword((Linkage)ptr->linkage, i) );
+}
+
+
+/*
+ * link_length( index )
+ * --
+ * The number of words spanned by the index-th link of the current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_link_length( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	
+	return INT2FIX( linkage_get_link_length((Linkage)ptr->linkage, i) );
+}
+
+
+/*
+ * link_label( index ) -> str
+ * --
+ * The "intersection" of the left and right connectors that comprise the link.
+ */
+static VALUE
+rlink_linkage_get_link_label( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	const char *label;
+	
+	label = linkage_get_link_label( (Linkage)ptr->linkage, i );
+	if ( !label ) return Qnil;
+	
+	return rb_str_new2( label );
+}
+
+
+/*
+ * link_llabel -> str
+ * --
+ * The label on the left word of the index-th link of the current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_link_llabel( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	const char *label = NULL;
+	
+	label = linkage_get_link_llabel( (Linkage)ptr->linkage, i );
+	if ( !label ) return Qnil;
+	
+	return rb_str_new2( label );
+}
+
+/*
+ * link_rlabel -> str
+ * --
+ * The label on the right word of the index-th link of the current sublinkage.
+ */
+static VALUE
+rlink_linkage_get_link_rlabel( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	const char *label = NULL;
+	
+	label = linkage_get_link_rlabel( (Linkage)ptr->linkage, i );
+	if ( !label ) return Qnil;
+	
+	return rb_str_new2( label );
+}
+
+
+/*
+ *  call-seq:
+ *     link_num_domains( index )   -> fixnum
+ *
+ *  Returns the number of domains in the index-th link.
+ *
+ */
+static VALUE
+rlink_linkage_get_link_num_domains( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int i = NUM2INT( index );
+	int count = 0;
+	
+	count = linkage_get_link_num_domains( (Linkage)ptr->linkage, i );
+	return INT2FIX( count );
+}
+
+
+/*
+ *  call-seq:
+ *     link_domain_names( index )   -> array
+ *
+ *  Returns the names of the domains the index-th link belongs to.
+ */
+static VALUE
+rlink_linkage_get_link_domain_names( VALUE self, VALUE index ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	char **names;
+	int i = NUM2INT( index );
+	int count;
+	VALUE names_ary;
+	
+	names = linkage_get_link_domain_names( (Linkage)ptr->linkage, i );
+	count = linkage_get_link_num_domains( (Linkage)ptr->linkage, i );
+	if ( count < 0 ) return rb_ary_new();
+	
+	names_ary = rb_ary_new2( count );
+	
+	for ( i = 0; i < count; i++ ) {
+		rb_ary_store( names_ary, i, rb_str_new2(names[i]) );
+	}
+	
+	return names_ary;
+}
+
+
+/*
+ *  call-seq:
+ *     words   -> array
+ *
+ *  Return the Array of word spellings or individual word spelling for the 
+ *  current sublinkage. These are the "inflected" spellings, such as "dog.n". 
+ *  The original spellings can be obtained by calls to Sentence#words.
+ */
+static VALUE
+rlink_linkage_get_words( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	const char **words;
+	int count, i;
+	VALUE words_ary;
+	
+	count = linkage_get_num_words( (Linkage)ptr->linkage );
+	words = linkage_get_words( (Linkage)ptr->linkage );
+	words_ary = rb_ary_new2( count );
+	
+	for ( i = 0; i < count; i++ ) {
+		rb_ary_store( words_ary, i, rb_str_new2(words[i]) );
+	}
+	
+	return words_ary;
+}
+
+
+/*
+ *  call-seq:
+ *     compute_union   -> true or false
+ *
+ *  If the linkage has a conjunction, combine all of the links occurring in all
+ *  sublinkages together -- in effect creating a "master" linkage (which may
+ *  have crossing links). The union is created as another sublinkage, thus
+ *  increasing the number of sublinkages by one, and is returned by this method.
+ *  If the linkage has no conjunctions, computing its union has no effect. This 
+ *  method returns true if computing its union caused another sublinkage to be
+ *  created.
+ */
+static VALUE
+rlink_linkage_compute_union( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int before, after;
+	
+	before = linkage_get_num_sublinkages( (Linkage)ptr->linkage );
+	linkage_compute_union( (Linkage)ptr->linkage );
+	after = linkage_get_num_sublinkages( (Linkage)ptr->linkage );
+	
+	return (after > before) ? Qtrue : Qfalse;
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.unused_word_cost   -> fixnum
+ *
+ *  Returns the unused word cost of the linkage, which corresponds to the number
+ *  of null links that were required to parse it.
+ *     
+ */
+static VALUE
+rlink_linkage_unused_word_cost( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval;
+	
+	rval = linkage_unused_word_cost( (Linkage)ptr->linkage );
+	
+	return INT2FIX( rval );
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.disjunct_cost   -> fixnum
+ *
+ *  Returns the connector or disjunct cost of the linkage.
+ *
+ */
+static VALUE
+rlink_linkage_disjunct_cost( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval;
+	
+	rval = linkage_disjunct_cost( (Linkage)ptr->linkage );
+	
+	return INT2FIX( rval );
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.and_cost   -> fixnum
+ *
+ *  Returns the AND cost of the linkage, which is the difference in length 
+ *  between and-list elements.
+ *
+ */
+static VALUE
+rlink_linkage_and_cost( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval;
+	
+	rval = linkage_and_cost( (Linkage)ptr->linkage );
+	
+	return INT2FIX( rval );
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.link_cost   -> fixnum
+ *
+ *  Returns the total (LEN) cost of the linkage, which is the total length of 
+ *  all links in the sentence minus the number of words -- since the total link 
+ *  length is never less than the number of words.
+ *
+ */
+static VALUE
+rlink_linkage_link_cost( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval;
+	
+	rval = linkage_link_cost( (Linkage)ptr->linkage );
+	
+	return INT2FIX( rval );
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.canonical?   -> true or false
+ *
+ *  Returns +true+ if the linkage is canonical. The canonical linkage is the 
+ *  one in which the minimal disjunct that ever occurrs in a position is used 
+ *  in that position.
+ */
+static VALUE
+rlink_linkage_canonical_p( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval = 0;
+	
+	rval = linkage_is_canonical( (Linkage)ptr->linkage );
+	
+	return rval ? Qtrue : Qfalse;
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.improper?   -> true or false
+ *
+ *  Returns +true+ if the linkage is "improper". 
+ *  --
+ *  :FIXME: Find out what an "improper fat linkage" is.
+ *
+ */
+static VALUE
+rlink_linkage_improper_p( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval = 0;
+	
+	rval = linkage_is_improper( (Linkage)ptr->linkage );
+	
+	return rval ? Qtrue : Qfalse;
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.has_inconsistent_domains?   -> true or false
+ *
+ *  Returns +true+ if the linkage has inconsistent domains. 
+ *  --
+ *  :FIXME: Find out what it means that a linkage has inconsistent domains.
+ *
+ */
+static VALUE
+rlink_linkage_has_inconsistent_domains_p( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	int rval = 0;
+	
+	rval = linkage_has_inconsistent_domains( (Linkage)ptr->linkage );
+	
+	return rval ? Qtrue : Qfalse;
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.violation_name   -> str
+ *
+ *  If the linkage violated any post-processing rules, this method returns the 
+ *  name of the violated rule in the post-process knowledge file. 
+ */
+static VALUE
+rlink_linkage_get_violation_name( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	const char *violation_name = NULL;
+	
+	violation_name = linkage_get_violation_name( (Linkage)ptr->linkage );
+	
+	if ( violation_name ) {
+		return rb_str_new2( violation_name );
+	} else {
+		return Qnil;
+	}
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.constituent_tree   -> hash
+ *
+ *  Return the Linkage's constituent tree as a hash of hashes.
+ *
+ *     sent = dict.parse( "He is a big dog." )
+ *     link = sent.linkages.first
+ *     ctree = link.constituent_tree
+ *     #=> {}
+ *     
+ */
+static VALUE
+rlink_linkage_constituent_tree( VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	CNode *ctree = NULL;
+	VALUE rval = Qnil;
+	
+	ctree = linkage_constituent_tree( (Linkage)ptr->linkage );
+	rval = rlink_linkage_make_cnode_array( ctree );
+	
+	linkage_free_constituent_tree( ctree );
+	return rval;
+}
+
+
+/* 
+ * Make an Array of LinkParser::Linkage::CTree objects from the specified
+ * linked list of CNode *.
+ */
+static VALUE
+rlink_linkage_make_cnode_array( CNode *ctree ) {
+	VALUE nodes = rb_ary_new();
+	VALUE rnode;
+	CNode *cnode = ctree;
+	
+	/*	
+		struct CNode_s {
+		  char  * label;
+		  CNode * child;
+		  CNode * next;
+		  int   start, end;
+		};
+	*/
+	while ( cnode ) {
+		rnode = rb_struct_new( rlink_sLinkageCTree,
+			rb_str_new2( linkage_constituent_node_get_label(cnode) ),
+			Qnil,
+			INT2FIX( linkage_constituent_node_get_start(cnode) ),
+			INT2FIX( linkage_constituent_node_get_end(cnode) )			/* end */
+		  );
+
+		/* Make a node array for any children */
+		rb_struct_aset( rnode, INT2FIX(1), 
+			rlink_linkage_make_cnode_array(linkage_constituent_node_get_child(cnode)) );
+
+		rb_ary_push( nodes, rnode );
+		cnode = linkage_constituent_node_get_next( cnode );
+	}
+	
+	return nodes;
+}
+
+
+/*
+ *  call-seq:
+ *     linkage.constituent_tree_string( mode=1 )   -> str
+ *
+ *  Return the constituent tree as a printable string.
+ *
+ *  Example:
+ *     sent = dict.parse( "He is a big dog." )
+ *     link = sent.linkages.first
+ *     link.constituent_tree_string
+ #  
+ #  # ==> "(S (NP He)\n   (VP is\n       (NP a big dog))\n   .)\n"
+ */
+static VALUE
+rlink_linkage_constituent_tree_string( int argc, VALUE *argv, VALUE self ) {
+	rlink_LINKAGE *ptr = get_linkage( self );
+	char *ctree_string = NULL;
+	VALUE rval = Qnil, modenum = Qnil;
+	int mode;
+	
+	if ( rb_scan_args(argc, argv, "01", &modenum) == 1 ) {
+		mode = NUM2INT( modenum );
+	} else {
+		mode = 1;
+	}
+
+	if ( mode < 1 || mode > 3 )
+		rb_raise( rb_eArgError, "Illegal mode %d specified.", mode );
+
+	ctree_string = linkage_print_constituent_tree( (Linkage)ptr->linkage, mode );
+
+	if ( ctree_string ) {
+		rval = rb_str_new2( ctree_string );
+		linkage_free_constituent_tree_str( ctree_string );
+	} else {
+		rval = Qnil;
+	}
+	
+	return rval;
+}
+
+
+
+/* 
+ * This is the API's representation of a parse. A LinkParser::Sentence may have one or more
+ * of LinkParser::Linkages, each of which represents one possible structure of the sentence.
+ * It can be thought of as a Sentence together with a collection of links. If the parse 
+ * has a conjunction, then the Linkage is made up of at least two "sublinkages". A 
+ * Linkage can be pretty printed in either ASCII or Postscript format, and individual 
+ * links can be extracted.
+ *
+ */
+void
+rlink_init_linkage() {
+	rlink_cLinkage = rb_define_class_under( rlink_mLinkParser, "Linkage", rb_cObject );
+	
+	rb_define_alloc_func( rlink_cLinkage, rlink_linkage_s_alloc );
+	
+	rb_define_method( rlink_cLinkage, "initialize", rlink_linkage_init, -1 );
+	rb_define_method( rlink_cLinkage, "diagram", rlink_linkage_diagram, 0 );
+	rb_define_method( rlink_cLinkage, "postscript_diagram",
+	 	rlink_linkage_print_postscript, 1 );
+	rb_define_method( rlink_cLinkage, "links_and_domains", 
+		rlink_linkage_links_and_domains, 0 );
+
+	rb_define_method( rlink_cLinkage, "num_sublinkages", 
+		rlink_linkage_num_sublinkages, 0 );
+	rb_define_method( rlink_cLinkage, "current_sublinkage=",
+		rlink_linkage_current_sublinkage_eq, 1 );
+	rb_define_method( rlink_cLinkage, "current_sublinkage",
+		rlink_linkage_current_sublinkage, 0 );
+
+	rb_define_method( rlink_cLinkage, "num_words",
+	 	rlink_linkage_get_num_words, 0 );
+	rb_define_alias ( rlink_cLinkage, "word_count", "num_words" );
+	rb_define_method( rlink_cLinkage, "num_links",
+	 	rlink_linkage_get_num_links, 0 );
+	rb_define_alias ( rlink_cLinkage, "link_count", "num_links" );
+	
+	rb_define_method( rlink_cLinkage, "link_lword",
+	 	rlink_linkage_get_link_lword, 1 );
+	rb_define_method( rlink_cLinkage, "link_rword",
+	 	rlink_linkage_get_link_rword, 1 );
+	rb_define_method( rlink_cLinkage, "link_length",
+	 	rlink_linkage_get_link_length, 1 );
+	rb_define_method( rlink_cLinkage, "link_label",
+	 	rlink_linkage_get_link_label, 1 );
+	rb_define_method( rlink_cLinkage, "link_llabel",
+	 	rlink_linkage_get_link_llabel, 1 );
+	rb_define_method( rlink_cLinkage, "link_rlabel",
+	 	rlink_linkage_get_link_rlabel, 1 );
+
+	rb_define_method( rlink_cLinkage, "link_num_domains",
+	 	rlink_linkage_get_link_num_domains, 1 );
+	rb_define_method( rlink_cLinkage, "link_domain_names",
+	 	rlink_linkage_get_link_domain_names, 1 );
+	
+	rb_define_method( rlink_cLinkage, "words",
+	 	rlink_linkage_get_words, 0 );
+
+	rb_define_method( rlink_cLinkage, "compute_union",
+	 	rlink_linkage_compute_union, 0 );
+	rb_define_method( rlink_cLinkage, "unused_word_cost",
+	 	rlink_linkage_unused_word_cost, 0 );
+	rb_define_method( rlink_cLinkage, "disjunct_cost",
+	 	rlink_linkage_disjunct_cost, 0 );
+	rb_define_method( rlink_cLinkage, "and_cost",
+	 	rlink_linkage_and_cost, 0 );
+	rb_define_method( rlink_cLinkage, "link_cost",
+	 	rlink_linkage_link_cost, 0 );
+	rb_define_method( rlink_cLinkage, "canonical?",
+	 	rlink_linkage_canonical_p, 0 );
+	rb_define_method( rlink_cLinkage, "improper?",
+	 	rlink_linkage_improper_p, 0 );
+	rb_define_method( rlink_cLinkage, "has_inconsistent_domains?",
+	 	rlink_linkage_has_inconsistent_domains_p, 0 );
+	rb_define_method( rlink_cLinkage, "violation_name",
+	 	rlink_linkage_get_violation_name, 0 );
+
+	/* Struct that contains links of a constituent tree (:label, :children, :start, :end) */
+	rb_define_const( rlink_cLinkage, "CTree", rlink_sLinkageCTree );
+
+	rlink_sLinkageCTree = rb_struct_define( "LinkParserLinkageCTree", 
+		"label", "children", "start", "end", NULL );
+	rb_define_method( rlink_cLinkage, "constituent_tree",
+		rlink_linkage_constituent_tree, 0 );
+	rb_define_method( rlink_cLinkage, "constituent_tree_string",
+	 	rlink_linkage_constituent_tree_string, -1 );
+}
+