Skip to content
Ruby gem for accessing Widgit's 'Symgate' SOAP symbolisation service
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.junit
lib
symboliser-vagrant @ 58a554f
test
.gitignore
.gitmodules
.rubocop.yml
.ruby-version
.travis.yml
CHANGELOG.md
Gemfile
LICENSE
README.md
Rakefile
symgate-gem.gemspec

README.md

Symgate - Ruby client for the Widgit symbolisation service

Build Status Code Climate codecov.io Dependency Status Gem Version Apache License

This gem provides a wrapper around the Symgate SOAP API, providing a simple Ruby interface that matches the remote API as much as possible.

The API provides a client for each of the sections of API functionality. These are:

  • Symgate::Auth::Client for authentication, user and group management
  • Symgate::Wordlist::Client for per-user/group metadata storage
  • Symgate::Metadata::Client for per-user/group wordlist management

Please note that a symbolisation client is scheduled for a future release.

Prerequisites

This gem works with Ruby 2.1 and above

Installation

Add this line to your application's Gemfile:

gem 'symgate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install symgate

Usage

Initialisation

To call any Symgate methods you must create a client of the relevant type. These can be instantiated in the following ways:

Account/key

require 'symgate/auth'

auth_client = Symgate::Auth::Client.new(account: 'my_account', key: 'secret')

User/password

require 'symgate/wordlist'

wordlist_client = Symgate::Wordlist::Client.new(account: 'my_account', 
                                                user: 'group/user',
                                                password: 'secret')

User/token

You need to call the authenticate method in order to obtain a token:

require 'symgate/auth'
require 'symgate/metadata'

# obtain a token from the authentication client

auth_client = Symgate::Auth::Client.new(account: 'my_account', 
                                        user: 'group/user',
                                        password: 'secret')

begin
  token = auth_client.authenticate
rescue Symgate::Error => e
  puts "Authentication failed with the following error: #{e.message}"
end

metadata_client = Symgate::Metadata::Client.new(account: 'my_account',
                                                user: 'group/user',
                                                token: token)

Other initialisation options

You can also initialise a client with the following options:

Option
:endpoint Specifies the symbolisation SOAP endpoint to use, if not the public symbolisation server.
:savon_opts Specifies options to pass to the underlying savon engine. e.g. { log_level: :debug }

Errors

If any method call fails, it will raise a Symgate::Error exception. Examine the exception for further information on what went wrong.

Further documentation

For more information, see the documentation at:

http://www.rubydoc.info/github/symbols-worldwide/symgate-gem/

Development

After checking out the repository, run bundle install to obtain the necessary development gems.

Run rake test to run the tests, which consist of

  • rubocop
  • rspec (with coverage)

Successful PRs require 100% code coverage and all tests and cops passing.

Integration tests

If you want to run the integration tests (test the gem against a running server):

  1. Install Vagrant 1.8 or later, if not already installed
  2. Run rake vagrant:up to set up a local VM running the latest symboliser.
  3. Run rake spec:integration to run the integration tests.

To pause testing until later, run rake vagrant:halt which will suspend your virtual machine. To resume testing run rake vagrant:up again.

To shut down and destroy the VM completely, run rake vagrant:destroy

Note that you need access to the Widgit CI server for this to work.

License

This project is licensed under the Apache License 2.0.

Contributing

  1. Fork it ( https://github.com/symbols-worldwide/symgate-gem/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
You can’t perform that action at this time.