symgate 0.1.0

data/lib/symgate/metadata/client.rb

@@ -0,0 +1,72 @@
+require 'symgate/client'
+require 'symgate/error'
+require 'symgate/metadata/data_item'
+
+# rubocop:disable Style/AccessorMethodName
+
+module Symgate
+  module Metadata
+    # client for the Symgate metadata system
+    class Client < Symgate::Client
+      # Gets metadata visible to the current user.
+      #
+      # If the 'scope' option is specified, this will list only the metadata
+      # defined at a particular scope. Otherwise it will list metadata items
+      # visible, with user metadata replacing group metadata and so on.
+      #
+      # If the 'keys' option is specified, this will list only the metadata
+      # matching the list of keys supplied.
+      #
+      # The 'key' option is also provided as a convenience, which works as above
+      # for a single item.
+      def get_metadata(opts = {})
+        o = opts
+        parse_get_metadata_opts o
+        o[:key] = o.delete(:keys) if o.include? :keys
+
+        resp = savon_request(:get_metadata) { |soap| soap.message(o) }
+
+        Symgate::Client.savon_array(
+          resp.body[:get_metadata_response],
+          :data_item,
+          Symgate::Metadata::DataItem
+        )
+      end
+
+      # Creates one or more metadata items, overwriting any that match the key
+      # and scope specified within the DataItem object. Supply either a single
+      # item or an array of items.
+      def set_metadata(items)
+        i = [items].flatten
+
+        check_array_for_type(i, Symgate::Metadata::DataItem)
+        raise Symgate::Error, 'No items supplied' if i.empty?
+
+        savon_request(:set_metadata, returns_error_string: true) do |soap|
+          soap.message('auth:data_item': i.map(&:to_soap))
+        end
+      end
+
+      # Destroys one or more metadata items on the specified scope, specified by
+      # their key(s). Specify a valid scope and a single string, or an array of
+      # strings.
+      def destroy_metadata(scope, keys)
+        k = [keys].flatten
+        check_array_for_type(k, String)
+        raise Symgate::Error, 'No keys supplied' if k.empty?
+
+        savon_request(:destroy_metadata, returns_error_string: true) do |soap|
+          soap.message(scope: scope, key: k)
+        end
+      end
+
+      private
+
+      def parse_get_metadata_opts(opts)
+        arrayize_option(:key, :keys, opts)
+        check_option_is_array_of(String, :keys, opts)
+        check_for_unknown_opts(%i(keys scope), opts)
+      end
+    end
+  end
+end

data/lib/symgate/metadata/data_item.rb

@@ -0,0 +1,34 @@
+require 'symgate/type'
+
+module Symgate
+  module Metadata
+    # meta data item
+    class DataItem < Symgate::Type
+      def self.from_soap(hash)
+        Symgate::Metadata::DataItem.new(
+          key: hash[:@key],
+          scope: hash[:@scope],
+          value: hash_value_with_optional_namespace(:auth, :value, hash)
+        )
+      end
+
+      def to_soap
+        {
+          '@key': key,
+          '@scope': scope,
+          'auth:value': value
+        }
+      end
+
+      def to_s
+        "{DataItem (scope: #{scope}, key #{key}, value #{value})}"
+      end
+
+      protected
+
+      def attributes
+        %i(key value scope)
+      end
+    end
+  end
+end

data/lib/symgate/metadata.rb

@@ -0,0 +1,2 @@
+require 'symgate/metadata/data_item'
+require 'symgate/metadata/client'

data/lib/symgate/namespaces.rb

@@ -0,0 +1,9 @@
+module Symgate
+  NAMESPACES = {
+    'xmlns:auth': 'http://ws.widgit.com/schema/auth/1.2',
+    'xmlns:wl': 'http://ws.widgit.com/schema/wordlist/1.2',
+    'xmlns:cml': 'http://ws.widgit.com/schema/cml/2.0',
+    'xmlns:gt': 'http://ws.widgit.com/schema/globaltypes/1.2',
+    'xmlns:symboliser': 'http://ws.widgit.com/schema/symboliser/1.2'
+  }.freeze
+end

data/lib/symgate/type.rb

@@ -0,0 +1,55 @@
+require 'symgate/error'
+
+module Symgate
+  # base class for API types, that provides magic initialisation from hash plus
+  # assignment and comparison operators
+  class Type
+    def initialize(opts = {})
+      attrs = attributes
+      self.class.class_eval { attr_accessor(*attrs) }
+      opts.each do |key, _value|
+        unless attributes.include? key
+          raise Symgate::Error, "Unknown option #{key} for #{self.class.name}"
+        end
+      end
+
+      attributes.each do |attribute|
+        instance_variable_set "@#{attribute}", opts[attribute]
+      end
+    end
+
+    def ==(other)
+      attributes.all? do |attribute|
+        a = other.instance_variable_get("@#{attribute}")
+        b = instance_variable_get("@#{attribute}")
+
+        a == b || values_are_empty([a, b])
+      end
+    end
+
+    def self.hash_value_with_optional_namespace(namespace, key, hash)
+      hash[key] || hash["#{namespace}:#{key}".to_sym]
+    end
+
+    protected
+
+    # override this to return an array of symbols for your class variables
+    # :nocov:
+    def attributes
+      raise Symgate::Error, "No attributes defined for object type #{self.class.name}"
+    end
+    # :nocov:
+
+    def value_or_nil(value)
+      if value.respond_to?(:empty?) ? value.empty? : !value
+        nil
+      else
+        value
+      end
+    end
+
+    def values_are_empty(values)
+      values.all? { |v| value_or_nil(v).nil? }
+    end
+  end
+end

data/lib/symgate/version.rb

@@ -0,0 +1,3 @@
+module Symgate
+  VERSION = '0.1.0'.freeze
+end

data/lib/symgate/wordlist/client.rb

@@ -0,0 +1,166 @@
+require 'base64'
+require 'symgate/client'
+require 'symgate/error'
+require 'symgate/wordlist/info'
+
+module Symgate
+  module Wordlist
+    # client for the Symgate wordlist system
+    class Client < Symgate::Client
+      # returns a list of wordlists available to the current user.
+      # optionally, supply one or more wordlist contexts as a string or string array parameter
+      # to only retrieve wordlist information about that context. e.g.:
+      # enumerate_wordlists('User')
+      # enumerate_wordlists(%w(Topic SymbolSet))
+      def enumerate_wordlists(context = [])
+        response = savon_request(:enumerate_wordlists) do |soap|
+          soap.message(context: [context].flatten)
+        end
+
+        Symgate::Client.savon_array(
+          response.body[:enumerate_wordlists_response],
+          :wordlistinfo,
+          Symgate::Wordlist::Info
+        )
+      end
+
+      # creates a wordlist with the specified name, context and scope (see auth:scope).
+      # optionally, supply a list of entries to form the wordlist's initial content
+      def create_wordlist(name, context, entries = [])
+        tries ||= 3 # TODO: Find out if we still need to do this!
+
+        Symgate::Wordlist::Info.from_soap(
+          savon_request(:create_wordlist) do |soap|
+            soap.message(soap_params_for_create_wordlist(name, context, entries))
+          end.body[:create_wordlist_response][:wordlistinfo]
+        )
+      rescue Symgate::Error => e
+        # Handle SOS-105 (sometimes the wordlist is created but the symboliser claims it can't
+        # find it and sends a SOAP error back) by extract the wordlist UUID from the error message.
+        # Yes, this is not nice.
+        match = /^No wordlist found for ID: ({[0-9a-f-]{36}})$/.match(e.detail)
+
+        return get_wordlist_info(match[1]) if match
+        (tries -= 1).zero? ? raise(e) : retry
+      end
+
+      # destroys a wordlist with the specified uuid. throws an error on failure
+      def destroy_wordlist(uuid)
+        tries ||= 3 # TODO: Find out if we still need to do this!
+
+        savon_request(:destroy_wordlist, returns_error_string: true) do |soap|
+          soap.message(wordlistid: uuid)
+        end
+      rescue Symgate::Error => e
+        (tries -= 1).zero? ? raise(e) : retry
+      end
+
+      # returns the information for the wordlist identified by the specified uuid
+      def get_wordlist_info(uuid)
+        response = savon_request(:get_wordlist_info) do |soap|
+          soap.message(wordlistid: uuid)
+        end
+
+        Symgate::Wordlist::Info.from_soap(
+          response.body[:get_wordlist_info_response][:wordlistinfo]
+        )
+      end
+
+      # returns all wordlist entries for the wordlist specified by uuid.
+      # accepts the following optional parameters:
+      #   attachments (boolean) - fetch custom graphics for the entries (default: false)
+      #   match (string) - only return wordlist entries matching this word
+      #   entry (string, uuid) - return the entry specified by the uuid
+      def get_wordlist_entries(uuid, opts = {})
+        check_for_unknown_opts(%i(match entry attachments), opts)
+        check_for_multiple_opts(%i(match entry), opts)
+
+        response = savon_request(:get_wordlist_entries) do |soap|
+          soap.message(wordlistid: uuid, getattachments: opts[:attachments])
+          soap[:message][:match] = { matchstring: opts[:match] } if opts.include? :match
+          soap[:message][:match] = { entryid: opts[:entry] } if opts.include? :entry
+        end
+
+        Symgate::Client.savon_array(response.body[:get_wordlist_entries_response],
+                                    :wordlistentry,
+                                    Symgate::Wordlist::Entry)
+      end
+
+      # inserts an entry into a wordlist, specified by the wordlist uuid
+      def insert_wordlist_entry(uuid, entry)
+        unless entry.is_a? Symgate::Wordlist::Entry
+          raise Symgate::Error, 'Please supply a Symgate::Wordlist::Entry to insert'
+        end
+
+        savon_request(:insert_wordlist_entry, returns_error_string: true) do |soap|
+          soap.message(wordlistid: uuid, 'wl:wordlistentry': entry.to_soap)
+        end
+      end
+
+      # overwrites a wordlist with the wordlist contents specified by 'entries'
+      def overwrite_wordlist(uuid, entries)
+        check_array_for_type(entries, Symgate::Wordlist::Entry)
+
+        savon_request(:overwrite_wordlist, returns_error_string: true) do |soap|
+          soap.message(wordlistid: uuid, 'wl:wordlistentry': entries.map(&:to_soap))
+        end
+      end
+
+      # removes the wordlist entry specified by entry_uuid, from the wordlist specified by uuid
+      def remove_wordlist_entry(uuid, entry_uuid)
+        savon_request(:remove_wordlist_entry, returns_error_string: true) do |soap|
+          soap.message(wordlistid: uuid, entryid: entry_uuid)
+        end
+      end
+
+      # renames the wordlist specified by its uuid, to the name requested
+      def rename_wordlist(uuid, name)
+        savon_request(:rename_wordlist, returns_error_string: true) do |soap|
+          soap.message(wordlistid: uuid, name: name)
+        end
+      end
+
+      # gets the cfwl-format data for the specified wordlist
+      def get_wordlist_as_cfwl_data(uuid)
+        Base64.decode64(
+          savon_request(:get_wordlist_as_cfwl_data) do |soap|
+            soap.message(wordlistid: uuid)
+          end.body[:get_wordlist_as_cfwl_data_response][:cfwl]
+        )
+      end
+
+      # creates a wordlist from the supplied cfwl data, in the requested context
+      # if 'preserve_uuid' is true, the new wordlist will have the same uuid as the file
+      def create_wordlist_from_cfwl_data(raw_cfwl_data, context, preserve_uuid)
+        savon_request(:create_wordlist_from_cfwl_data) do |soap|
+          soap.message(cfwl: Base64.encode64(raw_cfwl_data),
+                       context: context,
+                       preserve_uuid: preserve_uuid)
+        end.body[:create_wordlist_from_cfwl_data_response][:uuid]
+      end
+
+      private
+
+      def scope_for_context(context)
+        case context.to_s
+        when 'Topic', 'SymbolSet'
+          'Group'
+        when 'Lexical'
+          'Account'
+        else
+          'User'
+        end
+      end
+
+      def soap_params_for_create_wordlist(name, context, entries)
+        {
+          name: name,
+          context: context,
+          scope: scope_for_context(context)
+        }.merge(
+          entries ? { 'wl:wordlistentry': entries.map(&:to_soap) } : {}
+        )
+      end
+    end
+  end
+end

data/lib/symgate/wordlist/entry.rb

@@ -0,0 +1,48 @@
+require 'symgate/cml/symbol'
+require 'symgate/wordlist/graphic_attachment'
+require 'symgate/type'
+require 'symgate/client'
+require 'tryit'
+
+module Symgate
+  module Wordlist
+    # a wordlist entry
+    class Entry < Symgate::Type
+      def self.from_soap(hash)
+        Symgate::Wordlist::Entry.new(
+          word: hash_value_with_optional_namespace(:wl, :word, hash),
+          uuid: hash_value_with_optional_namespace(:wl, :uuid, hash),
+          priority: hash_value_with_optional_namespace(:wl, :priority, hash).to_i,
+          concept_code: hash_value_with_optional_namespace(:wl, :conceptcode, hash),
+          symbols: Symgate::Client.savon_array(hash, :symbol,
+                                               Symgate::Cml::Symbol),
+          custom_graphics: Symgate::Client.savon_array(hash, :customgraphic,
+                                                       Symgate::Wordlist::GraphicAttachment),
+          last_change: hash_value_with_optional_namespace(:wl, :lastchange, hash)
+        )
+      end
+
+      def to_soap
+        {
+          'wl:word': word,
+          'wl:uuid': uuid,
+          'wl:priority': priority,
+          'wl:conceptcode': value_or_nil(concept_code),
+          'cml:symbol': @symbols.tryit { map(&:to_soap) },
+          'wl:customgraphic': @custom_graphics.tryit { map(&:to_soap) },
+          'wl:lastchange': last_change.to_s
+        }.delete_if { |_, v| v.nil? }
+      end
+
+      def to_s
+        "{Entry: #{@word}[#{@priority}]/#{@uuid} (#{@symbols.count}+#{@custom_graphics.count})}"
+      end
+
+      protected
+
+      def attributes
+        %i(word uuid priority concept_code symbols custom_graphics last_change)
+      end
+    end
+  end
+end

data/lib/symgate/wordlist/graphic_attachment.rb

@@ -0,0 +1,37 @@
+require 'symgate/type'
+require 'base64'
+
+module Symgate
+  module Wordlist
+    # contains an embedded wordlist entry graphic
+    class GraphicAttachment < Symgate::Type
+      def self.from_soap(hash)
+        data = hash_value_with_optional_namespace(:wl, :data, hash)
+
+        Symgate::Wordlist::GraphicAttachment.new(
+          type: hash_value_with_optional_namespace(:wl, :type, hash),
+          uuid: hash_value_with_optional_namespace(:wl, :uuid, hash),
+          data: data ? Base64.decode64(data) : nil
+        )
+      end
+
+      def to_soap
+        {
+          'wl:type': @type,
+          'wl:uuid': @uuid,
+          'wl:data': @data ? Base64.encode64(@data) : nil
+        }
+      end
+
+      def to_s
+        "{#{@type} Attachment: #{@uuid} (#{@data.length} bytes)}"
+      end
+
+      protected
+
+      def attributes
+        %i(type uuid data)
+      end
+    end
+  end
+end

data/lib/symgate/wordlist/info.rb

@@ -0,0 +1,30 @@
+require 'symgate/type'
+
+module Symgate
+  module Wordlist
+    # contains information about a wordlist
+    class Info < Symgate::Type
+      def self.from_soap(hash)
+        Symgate::Wordlist::Info.new(
+          name: hash_value_with_optional_namespace(:wl, :name, hash),
+          context: hash_value_with_optional_namespace(:wl, :context, hash),
+          uuid: hash_value_with_optional_namespace(:wl, :uuid, hash),
+          engine: hash_value_with_optional_namespace(:wl, :engine, hash),
+          scope: hash_value_with_optional_namespace(:wl, :scope, hash),
+          entry_count: hash_value_with_optional_namespace(:wl, :entrycount, hash).to_i,
+          last_change: hash_value_with_optional_namespace(:wl, :lastchange, hash)
+        )
+      end
+
+      def to_s
+        "{#{@context} Wordlist: \"#{@name}\"/#{@uuid} (#{@engine}, #{@entry_count} entries)}"
+      end
+
+      protected
+
+      def attributes
+        %i(name context uuid entry_count last_change engine scope)
+      end
+    end
+  end
+end

data/lib/symgate/wordlist.rb

@@ -0,0 +1,4 @@
+require 'symgate/wordlist/info'
+require 'symgate/wordlist/entry'
+require 'symgate/wordlist/graphic_attachment'
+require 'symgate/wordlist/client'

data/lib/symgate.rb

@@ -0,0 +1 @@
+require 'symgate/version'

data/symgate-gem.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'symgate'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'symgate'
+  spec.version       = Symgate::VERSION
+  spec.authors       = ['Simon Detheridge']
+  spec.email         = ['simon@widgit.com']
+
+  spec.summary       = "Wrapper around Widgit's Symgate SOAP symboliser"
+  spec.homepage      = 'https://github.com/symbols-worldwide/symgate-gem'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f|
+    f.match(%r{^(test|spec|features)/})
+  }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.9'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.4.0'
+  spec.add_development_dependency 'rubocop', '~> 0.41.1'
+  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.2.3'
+  spec.add_development_dependency 'rubocop-junit-formatter', '~> 0.1.3'
+  spec.add_development_dependency 'rack', '~> 1.6.4'
+  spec.add_development_dependency 'mysql2', '~> 0.4.1'
+  spec.add_development_dependency 'simplecov', '~> 0.12.0'
+  spec.add_development_dependency 'simplecov-teamcity-summary', '~> 0.1.2'
+
+  spec.add_dependency 'savon', '~> 2.11.0'
+  spec.add_dependency 'tryit', '~> 0.0.1'
+end