juxta 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9537d609ce2a9506964a49b399dce7a4f54b4cd7
-  data.tar.gz: be87bc4c13083793d5a0afdf3cb57edec7ae66db
+  metadata.gz: 59a37cdbefe64c30540822a438e0f71e95ca62e2
+  data.tar.gz: 7e077e5a91a479abb46c153f8e72bf4b620fcd9d
 SHA512:
-  metadata.gz: d11ec8282f12f0656d0eece0923ffbdfa33370f049a855a4af93e061384574e0ed0a1648ae58f0cbe201626a58978a293e4fe685df9dd7e787298ddcf428185d
-  data.tar.gz: 013597f634a633718c0fbc9cc2f7df724fc5014b5a3f4b27cb73b205ac282b41ab70b0525b69725908e356cabeb3ce9fde51604f3bf68ecbf5125cf502c2ec15
+  metadata.gz: ac2c27e52a38ce5e8a1b4797dc7e1fd443e16d3f650b1cc636753ca6baecc61bf4048f5d787990d43b343e9a05dca6f37cb1183ea14d6affc85cca71ee5033d0
+  data.tar.gz: 75b3e08ef1486e2dbc36098bca5981146997e0d1540402a3e7908a0005b0b55088bc82231835d50533d4818d98ebcbdc9455a7dd7a2c4576826d88043e986bd4

data/lib/juxta.rb

@@ -1,52 +1,130 @@
 require 'juxta/connection'
 require 'juxta/utilities'
 
+# Author::    Nick Laiacona  (mailto:nick@performantsoftware.com), Lou Foster, Dave Goldstein
+# Copyright:: Copyright (c) 2013
+# License::   Distributes under Apache License
+
+# This class provides the Ruby interface to the JuxtaWS REST web service. 
 class Juxta
 
-  attr :logging
+  # Set to true to enable logging.
+  attr_accessor :logging
+  
+  # The connection object for this Juxta instance.
   attr_reader :connection
 
-  def initialize( url, workspace )
-    @logging = true
-    @connection = Connection.new( url, workspace, "", "" ) 
-  end
-
+  # Initialize a Juxta interface with optional authentication. 
+  # 
+  # @param [String] URL of the JuxtaWS server to connect to.
+  # @param [String] username if server require authentication.
+  # @param [String] password if server require authentication.
+  # @return [Connection] 
+  def initialize( url, username=nil, password=nil )
+    @logging = false
+    @connection = Connection.new( url, username, password ) 
+  end
+
+  # The name of the currently selected workspace. Default is "public".
+  # @return [String] The name of the current workspace. 
+  def workspace()
+    @connection.workspace
+  end
+  
+  # Select a workspace to operate in.
   #
-  # workspace behavior
+  # @param [String] workspace_name this is the name of the workspace.
+  # @return [Object] true if selection suceeded, false otherwise.
+  def select_workspace(workspace_name)
+    workspaces = list_workspaces()
+    workspace_names = workspaces.map { |workspace|
+      workspace["name"]
+    }
+    
+    if workspace_names.include? workspace_name
+      @connection.workspace = workspace_name
+      return true
+    else
+      return false
+    end    
+  end
+
+  # Lists the workspaces available on this server.
   #
+  # @return [Array] List of workspace names.
   def list_workspaces
     log_message( "Listing workspaces..." ) unless @logging == false
-    ws_list = @connection.get( "workspace" )
+    ws_list = @connection.get( "workspace", false )
     return ws_list
   end
 
+  # Create a new workspace.
+  #
+  # @param [String] Name of the workspace to create. Must be unique to this server.  
+  # @return [String] If successful, the created workspace's id.
   def create_workspace( workspace_id )
     log_message( "Creating workspace #{workspace_id} ..." ) unless @logging == false
     json = { "name" => workspace_id, "description" => "the description for #{workspace_id}" }
-    workspace_id = @connection.post( "workspace", json )
+    workspace_id = @connection.post( "workspace", json, false )
     return workspace_id
   end
 
+  # Delete a new workspace and everything in it.
+  #
+  # @param [String] Name of the workspace to delete. 
+  # @return [Object] True if successful, false otherwise.
   def delete_workspace( workspace_id )
-    return delete_asset( "workspace/#{workspace_id}" )
+    log_message( "Deleting workspace #{workspace_id} ..." ) unless @logging == false
+    resp = @connection.delete( "workspace/#{workspace_id}", false )
+    if resp['status'] == 'FAILED'
+       error_message( "failed to delete asset: #{asset_id}")
+       return false
+    end
+    return true
   end
 
+  # List the witnesses in this workspace. Witnesses are the transformed version of the sources.
   #
-  # witness behavior
-  #
-
+  # @return [Array] An array of hashes with summary information about each witness.
   def list_witnesses
     log_message( "Listing witnesses..." ) unless @logging == false
-    witness_list = @connection.get( "witness" )
-    return witness_list
+    @connection.get( "witness" )
   end
 
+  # Get full information about a given witness.
+  #
+  # @param [String,Integer] witness_id Identifier of the witness to retrieve. 
+  # @return [Hash] A hash with complete information about the witness, including full text.
   def get_witness( witness_id )
     log_message( "Getting witness #{witness_id}..." ) unless @logging == false
-    resp = @connection.get( "witness/#{witness_id}" )
-    return resp
+    @connection.get( "witness/#{witness_id}" )
+  end
+  
+  # Get full information about a given source.
+  #
+  # @param [String,Integer] source_id Identifier of the source to retrieve. 
+  # @return [Hash] A hash with complete information about the source, including full text.
+  def get_source( source_id )
+    log_message( "Getting source #{source_id}..." ) unless @logging == false
+    @connection.get( "source/#{source_id}" )
+  end
+  
+  # Retrieve a text fragment from a given witness.
+  #
+  # @param [String,Integer] witness_id Identifier of the witness. 
+  # @param [String,Integer] start_point Starting offset of the fragment. 
+  # @param [String,Integer] end_point Ending offset of the fragment. 
+  # @return [String] A string containing the text fragment, if found.
+  def get_witness_fragment( witness_id, start_point, end_point )
+    log_message( "Getting witness #{witness_id}..." ) unless @logging == false
+    @connection.get_html( "witness/#{witness_id}.txt?range=#{start_point},#{end_point}" )
   end
 
+  # Change the name of the witness.
+  #
+  # @param [String,Integer] witness_id Identifier of the witness. 
+  # @param [String,Integer] new_name The new name for the witness. 
+  # @return [Hash] 
   def rename_witness( witness_id, new_name )
     log_message( "Renaming witness #{witness_id} to #{new_name}..." ) unless @logging == false
     json = { 'name' => new_name }
@@ -54,43 +132,60 @@ class Juxta
     return resp
   end
 
+  # List the sources in this workspace.
   #
-  # source behavior
-  #
-
+  # @return [Array] An array of hashes with summary information about each source.
   def list_sources
     log_message( "Listing sources..." ) unless @logging == false
     source_list = @connection.get( "source" )
     return source_list
   end
 
-  #
-  # xslt behavior
-  #
-
-  def create_xslt( json )
-     asset_id = "xslt"
-     resp = @connection.post(asset_id, json)
-     return resp
+  # Create a new XSLT on the server.
+  # 
+  # @param [String] name A display name for this XSLT.
+  # @param [String] xslt XML string for the XSLT.
+  # @return [String] An identifier for the newly created XSLT.
+  def create_xslt( name, xslt )
+    @connection.post("xslt", {:name=>name, :xslt=>xslt } )
   end
 
+  # List the XSL stylesheets in this workspace.
+  #
+  # @return [Array] An array of hashes with summary information about each XSLT.
   def list_xslt
     log_message( "Listing xslt..." ) unless @logging == false
     xslt_list = @connection.get( "xslt" )
     return xslt_list
   end
-
-  #
-  # annotation behavior
+  
+  # Get full information about a given comparison set.
   #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @return [Hash] A hash with complete information about the comparison set, including a list of witnesses.
+  def get_set( set_id )
+    log_message( "Getting set #{set_id}..." ) unless @logging == false
+    @connection.get( "set/#{set_id}" )
+  end
 
-  def create_annotation( set_id, witness_id, json )
+  # Create new annotations, on a given witness in a comparison set. 
+  #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @param [String,Integer] witness_id Identifier of a witness. 
+  # @param [Array] json An array of hashes defining annotations. See JuxtaWS API docs for hash format. 
+  # @return [String] A JSON array of annotation identifiers created. 
+  def create_annotations( set_id, witness_id, json )
      asset_id = "set/#{set_id}/witness/#{witness_id}/annotation"
      log_message( "Posting annotations to #{asset_id}..." ) unless @logging == false   
      resp = @connection.post(asset_id, json)
      return resp
   end
 
+  # List the annotations applied to a given witness in a comparison set.
+  #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @param [String,Integer] witness_id Identifier of a witness. 
+  # @return [Array] An array of hashes containing annotation data.
   def list_annotations( set_id, witness_id )
     asset_id = "set/#{set_id}/witness/#{witness_id}"
     log_message( "Listing annotations for #{asset_id}..." ) unless @logging == false
@@ -98,76 +193,105 @@ class Juxta
     return annotation_list
   end
 
-  def get_annotation( annotation_id )
+  # Retrieve information about a specific annotation.
+  #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @param [String,Integer] witness_id Identifier of a witness. 
+  # @param [String,Integer] annotation_id Identifier of the specified annotation. 
+  # @return [Hash] A hash containing the annotation data.  
+  def get_annotation( set_id, witness_id, annotation_id )
     log_message( "Getting annotation #{annotation_id}..." ) unless @logging == false
-    resp = @connection.get( "#{annotation_id}?content=YES" )
-    return resp
+    @connection.get( "set/#{set_id}/witness/#{witness_id}/annotation/#{annotation_id}?content=YES" )
   end
 
+  # Create new alignments, which are associations of annotations in a comparison set.
   #
-  # alignmant behavior
-  #
-
-  def create_alignment( set_id, json )
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @param [Array] json An array of hashes defining alignments. See JuxtaWS API docs for hash format. 
+  # @return [String] A JSON array of alignment identifiers created. 
+  def create_alignments( set_id, json )
      asset_id = "set/#{set_id}/alignment"
      log_message( "Posting alignments to #{asset_id}..." ) unless @logging == false   
      resp = @connection.post(asset_id, json)
      return resp
   end
 
+  # List the alignments for a given comparison set.
+  #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @return [Array] An array of hashes containing alignment data.  
   def list_alignments( set_id )
     asset_id = "set/#{set_id}"
     log_message( "Listing alignments for #{asset_id}..." ) unless @logging == false
-    annotation_list = @connection.get( "#{asset_id}/alignment" )
-    return annotation_list
+    @connection.get( "#{asset_id}/alignment" )
   end
 
+  # Get full information about a given alignment.
+  #
+  # @param [String,Integer] set_id Identifier of a comparison set. 
+  # @param [String,Integer] alignment_id Identifier of an alignment. 
+  # @return [Hash] A hash with complete information about the alignment, including text fragments.  
   def get_alignment( set_id, alignment_id )
     asset_id = "set/#{set_id}/alignment/#{alignment_id}"
     log_message( "Getting alignment #{asser_id}..." ) unless @logging == false
-    resp = @connection.get( "#{asset_id}" )
-    return resp
+    @connection.get( "#{asset_id}" )
   end
 
+  # Delete the specified witness.
   #
-  # delete behavior
-  #
-
-  def delete_asset( asset_id )
-
-    log_message( "Deleting asset #{asset_id} ..." ) unless @logging == false
-    resp = @connection.delete( asset_id )
-    if resp['status'] == 'FAILED'
-       error_message( "failed to delete asset: #{asset_id}")
-       return false
-    end
-    return true
-  end
-
+  # @param [String,Integer] witness_id Identifier of the witness.
+  # @return [Object] True if successful, false otherwise.
   def delete_witness( witness_id )
      return delete_asset( "witness/#{witness_id}" )
   end
 
+  # Delete the specified source.
+  #
+  # @param [String,Integer] source_id Identifier of the source.
+  # @return [Object] True if successful, false otherwise.
   def delete_source( source_id )
     return delete_asset( "source/#{source_id}" )
   end
 
+  # Delete the specified XSLT.
+  #
+  # @param [String,Integer] xslt_id Identifier of the XSLT.
+  # @return [Object] True if successful, false otherwise.
+  def delete_xslt( xslt_id )
+    return delete_asset( "xslt/#{xslt_id}" )
+  end
+  
+  # Delete the specified comparison set.
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @return [Object] True if successful, false otherwise.
   def delete_set( set_id )
     return delete_asset( "set/#{set_id}" )
   end
 
+  # Delete the specified annotation from a given comparison set witness.
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @param [String,Integer] witness_id Identifier of the witness.
+  # @param [String,Integer] annotation_id Identifier of the annotation.
+  # @return [Object] True if successful, false otherwise.
   def delete_annotation( set_id, witness_id, annotation_id )
     return delete_asset( "set/#{set_id}/witness/#{witness_id}/annotation/#{annotation_id}" )
   end
 
+  # Delete the specified alignment from a given comparison set.
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @param [String,Integer] alignment_id Identifier of a given alignment.
+  # @return [Object] True if successful, false otherwise.
   def delete_alignment( set_id, alignment_id )
     return delete_asset( "set/#{set_id}/alignment/#{alignment_id}" )
   end
 
+  # Upload a file from local disk to the server.
   #
-  # upload behavior
-  #
-
+  # @param [String] file_name Local path to the file to upload.
+  # @return [String] Identifier of uploaded source if successful, otherwise nil.
   def upload_source( file_name )
 
      id = make_guid()
@@ -187,28 +311,57 @@ class Juxta
      return nil
   end
 
+  # Command the server to create source files from the provided array of hashes.
   #
-  # transform behavior
+  # @param [Array] source_array Array of hashes describing the sources to be created. See JuxtaWS API for format.
+  # @return [Array] Identifiers of the sources if successful, otherwise nil.  
+  def create_sources( source_array )
+    log_message( "Creating sources from JSON data..." ) unless @logging == false
+    resp = @connection.post( "source", source_array )
+    JSON.parse(resp) 
+  end
+    
+  # Command the server to obtain an XML source file from the specified URL.
   #
+  # @param [String] url URL of the XML source file to grab.
+  # @return [String] Identifier of the obtained source if successful, otherwise nil.
+  def obtain_source_from_url( url )
+    id = make_guid()
+    log_message( "Downloading #{url} as #{id} ..." ) unless @logging == false
+    resp = @connection.post( "source", [{name: id, type: 'url', contentType: 'xml', data: url}] )
+    parsed = JSON.parse(resp) 
+    if parsed.length > 0
+      parsed[0]
+    else
+      nil
+    end
+  end
 
-  def transform_source( file_id )
+  # Transform the specified source into a witness using the associated XSLT.
+  #
+  # @param [String,Integer] source_id Identifier of the source.
+  # @return [String] Identifier of the resultant witness.
+  def transform_source( source_id )
 
-    log_message( "Transforming #{file_id} ..." ) unless @logging == false
-    json = { 'source' => file_id, 'finalName' => make_guid() }
+    log_message( "Transforming #{source_id} ..." ) unless @logging == false
+    json = { 'source' => source_id, 'finalName' => make_guid() }
     wit_id = @connection.post( "transform", json )
     return wit_id
   end
 
+  # List the comparison sets in this workspace.
   #
-  # witness set behavior
-  #
-
+  # @return [Array] An array of hashes with summary information about each comparison set.
   def list_sets
     log_message( "Listing sets..." ) unless @logging == false
     set_list = @connection.get( "set" )
     return set_list
   end
 
+  # Group the specified witnesses into a new comparison set.
+  #
+  # @param [Array] witness_ids An array of witness identifiers.
+  # @return [String] Identifier of the resultant comparison set.
   def make_set( witness_ids )
     log_message( "Creating witness set ..." ) unless @logging == false
     set = { 'name' => make_guid(), 'witnesses' => witness_ids }
@@ -216,12 +369,21 @@ class Juxta
     return set_id
   end
 
+  # Tokenize the specified comparison set. Returns 
+  # immediately, use get_status(task_id) to check the status of tokenization. Tokens are 
+  # accessible as annotations of type 'token'. 
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @return [String] An identifier for the server task.
   def async_tokenize_set( set_id )
      log_message( "Tokenizing witness set #{set_id}..." ) unless @logging == false
-     task_id = @connection.post( "set/#{set_id}/tokenize", nil)
-     return task_id
+     @connection.post( "set/#{set_id}/tokenize", nil)
   end
 
+  # Tokenize the specified comparison set. Tokens are accessible as annotations of type 'token'.
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @return [Object] True if successful, false otherwise.
   def tokenize_set( set_id )
     task_id = async_tokenize_set( set_id )
     while true do
@@ -238,12 +400,20 @@ class Juxta
     end
   end
 
+  # Collate the specified comparison set. Returns immediately, use 
+  # get_status(task_id) to check the status of collation.
+  #
+  # @param [String,Integer] set_id Identifier of the comparison set.
+  # @return [String] An identifier for the server task.
   def async_collate_set( set_id )
      log_message( "Collating witness set #{set_id}..." ) unless @logging == false
-     task_id = @connection.post( "set/#{set_id}/collate", nil)
-     return task_id
+     @connection.post( "set/#{set_id}/collate", nil)
   end
 
+  # Collate the specified comparison set and wait for the response from server.
+  #
+  # @param [String,Integer] set_id Identifier of the target comparison set.
+  # @return [Object] True if successful, false otherwise.
   def collate_set( set_id )
     task_id = async_collate_set( set_id )
     while true do
@@ -260,29 +430,31 @@ class Juxta
     end
   end
 
+  # Search the current workspace for the specified phrase. Server must have search indexing enabled.
   #
-  # Search behavior
-  #
+  # @param [String] query The phrase to search for within the workspace.
+  # @return [Array] An array of objects that detail the search results.
   def search( query )
     log_message( "Searching for #{query}..." ) unless @logging == false
     resp = @connection.get("search?q=#{query}")
     return resp
   end
 
+  # Retrieve the status of a server side task. 
   #
-  # task status behavior
-  #
-
+  # @param [String,Integer] task_id An identifier for a server side task.
+  # @return [String] A status code. Possible codes are: PENDING, PROCESSING, COMPLETE, CANCEL_REQUESTED, CANCELLED, FAILED.
   def get_status( task_id )
     log_message( "Getting status for #{task_id}..." ) unless @logging == false
     resp = @connection.get("task/#{task_id}/status")
     return resp['status']
   end
 
+  # Retrieve the HTML for a given asset. Returns immediately, use 
+  # get_status(task_id) to check status.
   #
-  # get asset behavior
-  #
-
+  # @param [String, Integer] asset_id Identifier of a given asset.
+  # @return [String] Task_id for the checking status or nil if the asset can not be retrieved. 
   def async_get_as_html( asset_id )
     log_message( "Getting html #{asset_id}..." ) unless @logging == false
     resp = @connection.get_html( asset_id )
@@ -292,6 +464,50 @@ class Juxta
     return nil
   end
 
+  # Creates an asset identifier for the heatmap of a given base text in a comparison set. 
+  # Use get_as_html or get_as_json to retrieve the asset.
+  #
+  # @param [String, Integer] set_id Identifier of a comparison set.
+  # @param [String, Integer] base_id Identifier of a base text.
+  # @return [String] Asset identifier for the heatmap visualization of the given base text.
+  def get_heatmap_asset_id( set_id, base_id )
+    "set/#{set_id}/view?mode=heatmap&base=#{base_id}"    
+  end
+  
+  # Creates an asset identifier for a side-by-side comparison of two witnesses in a comparison set.
+  # Use get_as_html or get_as_json to retrieve the asset.
+  #
+  # @param [String, Integer] set_id Identifier of a comparison set.
+  # @param [String, Integer] witness_a Identifier of the first witness.
+  # @param [String, Integer] witness_b Identifier of the second witness.
+  # @return [String] Asset identifier for the side-by-side visualization.
+  def get_side_by_side_asset_id( set_id, witness_a, witness_b )
+    "set/#{set_id}/view?mode=sidebyside&docs=#{witness_a},#{witness_b}" 
+  end
+
+  # Creates a URL for the heatmap of a given base text in a comparison set.
+  #
+  # @param [String, Integer] set_id Identifier of a comparison set.
+  # @param [String, Integer] base_id Identifier of a base text.
+  # @return [String] URL to the heatmap visualization of the given base text.
+  def get_heatmap_url( set_id, base_id )
+    @connection.make_full_url( get_heatmap_asset_id(set_id,base_id) )    
+  end
+  
+  # Creates a URL for a side-by-side comparison of two witnesses in a comparison set.
+  #
+  # @param [String, Integer] set_id Identifier of a comparison set.
+  # @param [String, Integer] witness_a Identifier of the first witness.
+  # @param [String, Integer] witness_b Identifier of the second witness.
+  # @return [String] URL to the side-by-side visualization.
+  def get_side_by_side_url( set_id, witness_a, witness_b )
+    @connection.make_full_url( get_side_by_side_asset_id(set_id, witness_a, witness_b) )    
+  end
+
+  # Retrieve the HTML for a given asset, waiting for server to prepare asset if necessary.
+  #
+  # @param [String, Integer] asset_id Identifier of a given asset.
+  # @return [Object] HTML for the asset or false if the asset could not be retrieved. 
   def get_as_html( asset_id )
      task_id = async_get_as_html( asset_id )
      if task_id.nil? == false
@@ -311,6 +527,11 @@ class Juxta
      return resp
   end
 
+  # Retrieve the JSON for a given asset. Returns immediately, use 
+  # get_status(task_id) to check status.
+  #
+  # @param [String, Integer] asset_id Identifier of a given asset.
+  # @return [String] Task_id for the checking status or nil if the asset can not be retrieved.
   def async_get_as_json( asset_id )
     log_message( "Getting json #{asset_id}..." ) unless @logging == false
     resp = @connection.get( asset_id )
@@ -320,6 +541,10 @@ class Juxta
     return nil
   end
 
+  # Retrieve the JSON for a given asset, waiting for server to prepare asset if necessary.
+  #
+  # @param [String, Integer] asset_id Identifier of a given asset.
+  # @return [Object] JSON for the asset or false if the asset could not be retrieved. 
   def get_as_json( asset_id )
      task_id = async_get_as_json( asset_id )
      if task_id.nil? == false
@@ -339,82 +564,28 @@ class Juxta
      return false
   end
 
-  def get_info( asset_id )
-    log_message( "Getting info for #{asset_id}..." ) unless @logging == false
-    resp = @connection.get( "#{asset_id}/info" )
-    return resp
-  end
-
-  def get_usage( asset_id )
-    log_message( "Getting usage for #{asset_id}..." ) unless @logging == false
-    resp = @connection.get( "#{asset_id}/usage" )
-    return resp
-  end
-
+  # Get the specified XSLT resource from server.
+  #
+  # @param [String,Integer] asset_id The identifier of the specified XSLT.
+  # @return [String] XML for the specified XSLT.
   def get_xslt( asset_id )
     log_message( "Getting xslt #{asset_id}..." ) unless @logging == false
-    resp = @connection.get_html( "xslt/#{asset_id}" )
-    return resp
+    @connection.get_html( "xslt/#{asset_id}" )
   end
 
-  #
   # TEI Parallel segmentation export
-  #
-
   def export( set_id, base_id )
     log_message( "Exporting set #{set_id}..." ) unless @logging == false
     resp = @connection.get_xml( "set/#{set_id}/export?mode=teips&base=#{base_id}&sync" )
     return resp
   end
 
+  # Create an uncollated comparison set from an array of local files.
   # 
-  # Edition starter
-  # 
-
-  def edition( set_id, title, line_freq, base_id, wit_siglum_map )
-     data = {}
-     data['title'] = title
-     data['lineFrequency'] = line_freq
-     data['numberBlankLines'] = false
-     witnesses = []
-     wit_siglum_map.each do |id, siglum|
-        wit = {"id"=> id, "include"=>true, "base"=>(id == base_id), "siglum"=>siglum}
-        witnesses << wit
-     end
-     data['witnesses'] = witnesses
-
-     log_message( "Exporting edition for set #{set_id}..." ) unless @logging == false   
-     resp = @connection.post("set/#{set_id}/edition", data)
-
-     # wait for task to complete
-     parsed = JSON.parse(resp)
-     token = parsed['token']
-     task = parsed['taskId']
-
-     while true do
-      sleep(2.0)
-      resp = get_status( task )
-      puts resp
-      case resp
-        when 'COMPLETE'
-          break
-
-        when 'FAILED'
-          error_message( "failed to tokenize set: #{set_id}")
-          return false
-      end
-    end
-
-    # now request the HTML edition and pass along the token
-    html = @connection.get_html("set/#{set_id}/edition?token=#{token}&format=html")
-    return html
-
-  end
-
-  #
-  # convience methods
-  #
-
+  # @param [Array] file_list An array of paths to local files to upload. 
+  # @return [Array] Array of resultant source identifiers. 
+  # @return [Array] Array of resultant witness identifiers. 
+  # @return [String] The identifier for the resultant comparison set. 
   def create_witness_set( file_list )
 
     src_ids = []
@@ -437,21 +608,19 @@ class Juxta
 
     return src_ids, wit_ids, set_id
   end
+  
+  protected
+  
+  # Helper method for deleting sets, sources, witnesses.
+  def delete_asset( asset_id )
 
-  def destroy_witness_set( source_list, witness_list )
-
-    witness_list.each do |wit_id|
-      status = delete_witness( wit_id )
-      return false unless status == true
-    end
-
-    source_list.each do |src_id|
-      status = delete_source( src_id )
-      return false unless status == true
+    log_message( "Deleting asset #{asset_id} ..." ) unless @logging == false
+    resp = @connection.delete( asset_id )
+    if resp['status'] == 'FAILED'
+       error_message( "failed to delete asset: #{asset_id}")
+       return false
     end
-
     return true
   end
 
-
 end

data/lib/juxta/connection.rb

@@ -5,14 +5,14 @@ require 'base64'
 class Connection
 
    attr_reader :url
-   attr_reader :workspace
+   attr_accessor :workspace
 
-   def initialize( url, workspace, username, password )
+   def initialize( url, username=nil, password=nil )
 
       @authtoken = "Basic #{Base64.encode64("#{username}:#{password}")}"
-      @url = "#{url}/juxta"
-      @workspace = workspace
-
+      @url = url
+      @workspace = "public"
+      
       @timeout = 600        # 10 minute get timeout...
       @open_timeout = 600   # 10 minute post timeout
 
@@ -32,9 +32,10 @@ class Connection
       return json['version']
    end
 
-   def get( request )
+   def get( request, in_workspace=true )
       start_time = Time.now.to_f
-      resp = @rest_client[ make_url( request ) ].get :content_type => "application/json", :accept=>'application/json', :authorization => @authtoken
+      url = in_workspace ? make_url( request ) : request 
+      resp = @rest_client[ url ].get :content_type => "application/json", :accept=>'application/json', :authorization => @authtoken
       dump_time( "get", start_time )
       JSON.parse(resp)
    end
@@ -53,17 +54,18 @@ class Connection
       return resp
    end
 
-   def post( request, payload )
+   def post( request, payload, in_workspace=true )
       start_time = Time.now.to_f
+      url = in_workspace ? make_url( request ) : request   
       if payload.nil? == true
-         resp = @rest_client[ make_url( request ) ].post "", :authorization => @authtoken
+         resp = @rest_client[ url ].post "", :authorization => @authtoken
       else
-         resp = @rest_client[ make_url( request ) ].post payload.to_json, :authorization => @authtoken, :content_type => "application/json"
+         resp = @rest_client[ url ].post payload.to_json, :authorization => @authtoken, :content_type => "application/json"
       end
       dump_time( "post", start_time )
       return resp
    end
-   
+      
    def upload_file( file_name, content_type, file ) 
       opts = {
          :sourceName=> file_name,
@@ -85,20 +87,20 @@ class Connection
       return resp
    end
 
-   def delete( request )
+   def delete( request, in_workspace=true )
       start_time = Time.now.to_f
-      resp =  @rest_client[ make_url( request ) ].delete :authorization => @authtoken
+      url = in_workspace ? make_url( request ) : request   
+      resp =  @rest_client[ url ].delete :authorization => @authtoken
       dump_time( "delete", start_time )
       return resp
    end
 
    def make_url( request )
-     if @workspace.length != 0
-       url = "#{@workspace}/#{request}"
-     else
-       url = request
-     end
-     return url
+     "#{@workspace}/#{request}"
+   end
+   
+   def make_full_url( request ) 
+    "#{@url}/#{make_url(request)}"
    end
 
    def dump_time( what, start_time )

data/lib/juxta/utilities.rb

@@ -1,4 +1,6 @@
 require 'uuidtools'
+require 'restclient'
+require 'json'
 
 # coordinate access to stdout...
 Log_sem = Mutex.new
@@ -28,8 +30,30 @@ end
 
 def standard_fileset( )
   fileset = []
-  fileset.push("good-testdata/MD_AmerCh1b.xml")
-  fileset.push("good-testdata/MD_Brit_v1CH1a.xml")
+  fileset.push("test/good-testdata/MD_AmerCh1b.xml")
+  fileset.push("test/good-testdata/MD_Brit_v1CH1a.xml")
   return fileset
 
+end
+
+def wikipediaQueryRevisions( lang, params )
+  return JSON.parse(RestClient.get("http://#{lang}.wikipedia.org/w/api.php", :params => {
+    :format => "json",
+    :action => "query"
+  }.merge(params))).fetch("query", {}).fetch("pages", {}).values.map { |page| page.fetch("revisions", []) }.flatten
+end
+
+def wikipedia( title, limit=5, lang="en" )
+  revision_ids = wikipediaQueryRevisions(lang, {
+    :titles => title,
+    :prop => "revisions",
+    :rvlimit => 500,
+    :rvprop => "ids|flags"    
+  }).select { |rev|  !rev.has_key?("minor")  }.map { |rev| rev["revid"] }.slice(0, limit)
+
+  wikipediaQueryRevisions(lang, {
+    :revids => revision_ids.join("|"),
+    :prop => "revisions",
+    :rvprop => "content"    
+  }).map { |rev| rev.fetch("*", "") }.select { |rev| rev != "" }
 end

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: juxta
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
+- Lou Foster
+- Dave Goldstein
 - Nick Laiacona
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-24 00:00:00.000000000 Z
+date: 2013-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -66,7 +68,10 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.1.3
-description: JuxtaWS Ruby bindings
+description: JuxtaWS can collate two or more versions of the same textual work (“witnesses”)
+  and generate a list of alignments as well as two different styles of visualization
+  suitable for display on the web. This gem provides a Ruby interface to the JuxtaWS
+  REST web service.
 email: nick@performantsoftware.com
 executables: []
 extensions: []
@@ -76,7 +81,8 @@ files:
 - lib/juxta/connection.rb
 - lib/juxta/utilities.rb
 homepage: http://rubygems.org/gems/juxta
-licenses: []
+licenses:
+- Apache 2.0
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -86,7 +92,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
@@ -97,6 +103,6 @@ rubyforge_project:
 rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
-summary: JuxtaWS Ruby bindings
+summary: Provides a Ruby interface to the JuxtaWS REST web service.
 test_files: []
 has_rdoc: