README.rdoc
= WLAPI
{RubyGems}[http://rubygems.org/gems/wlapi] | {WLAPI Project Page}[http://bu.chsta.be/projects/wlapi/] |
{Source Code}[https://github.com/arbox/wlapi] | {Bug Tracker}[https://github.com/arbox/wlapi/issues] |
{Mailing List}[http://groups.google.com/group/wlapi]
{<img src="https://img.shields.io/gem/v/wlapi.svg" alt="Gem Version" />}[https://rubygems.org/gems/wlapi]
{<img src="https://img.shields.io/travis/arbox/wlapi.svg" alt="Build Status" />}[https://travis-ci.org/arbox/wlapi]
{<img src="https://img.shields.io/codeclimate/github/arbox/wlapi.svg" alt="Code Climate" />}[https://codeclimate.com/github/arbox/wlapi]
{<img src="https://img.shields.io/gemnasium/arbox/wlapi.svg" alt="Dependency Status" />}[https://gemnasium.com/arbox/wlapi]
*DISCLAIMER* We are working on the new RESTful client. Please be patient!
== DESCRIPTION
WLAPI is a programmatic API for web services provided by the project
{Wortschatz}[http://wortschatz.uni-leipzig.de/], University of Leipzig. These
services are a great source of linguistic knowledge for morphological, syntactic
and semantic analysis of German both for traditional and Computational
Linguistics (CL).
Use this API to gain data on word frequencies, left and right neighbours,
collocations and semantic similarity. Check it out if you are interested
in Natural Language Processing (NLP) and Human Language Technology (HLT).
This library is a set of Ruby bindings for the following featuren. You may also
be interested in other language specific bindings:
* {Perl}[http://search.cpan.org/~schroeer/Lingua-DE-Wortschatz/]
* {Python}[https://github.com/lehmannro/libleipzig-python]
* {PHP}[http://web.archive.org/web/20090418233940/http://blog.klassifikator.de/2009/03/php-implementierung-des-wortschatz-webservice-der-uni-leipzig/]
* {C#}[http://code-bude.net/2013/07/22/csharp-api-fuer-den-wortschatz-leipzig-thesaurus-webservic/]
The original Java based clients with many examples can be found on the
{project overview page}[http://wortschatz.uni-leipzig.de/axis/servlet/ServiceOverviewServlet].
=== Implemented Features
You can use the following search methods:
* <tt>#baseform</tt>;
* <tt>#cooccurrences</tt>;
* <tt>#cooccurrences_all</tt>;
* <tt>#crossword</tt>;
* <tt>#domain</tt>;
* <tt>#experimental_synonyms</tt>;
* <tt>#frequencies</tt>;
* <tt>#left_collocation_finder</tt>;
* <tt>#left_neighbours</tt>;
* <tt>#right_collocation_finder</tt>;
* <tt>#right_neighbours</tt>;
* <tt>#sentences</tt>;
* <tt>#similarity</tt>;
* <tt>#synonyms</tt>;
* <tt>#thesaurus</tt>;
* <tt>#wordforms</tt>;
* <tt>#ngrams</tt>;
* <tt>#ngram_references</tt>;
The services <tt>NGrams</tt> and <tt>NGramReferences</tt> are under development
and will be available soon. Both methods throw an <tt>NotImplementedError</tt>
for now.
The interface will be slightly changed in the version <tt>1.0</tt> to be more
readable. For example, <tt>#cooccurrences_all</tt> may become
<tt>#all_cooccurrences</tt>.
There are two additional services by Wortschatz Leipzig: MARS and
Kookurrenzschnitt. They will not be implemented due to internal restrictions of
the service provider.
== INSTALLATION
WLAPI is provided as a <tt>.gem</tt> package. Simply install it via
{RubyGems}[http://rubygems.org/gems/wlapi].
To install WLAPI ussue the following command:
$ gem install wlapi
The current version of WLAPI works with the second {Savon}[http://savonrb.com/version2/]
generation. You might want to install versions prior to +0.8.0+, if you are bound
on the old implementations of {savon}[http://savonrb.com/]:
$ gem install wlapi -v 0.7.4
If you want to do a system wide installation, do this as root (possibly using +sudo+).
Alternatively use your <tt>Gemfile</tt> for dependency management.
We are working on a <tt>.deb</tt> package, which will be released soon.
== SYNOPSIS
Basic usage is very simple:
$ require 'wlapi'
$ api = WLAPI::API.new
$ api.synonyms('Haus', 15) # returns an array with string values (UTF8 encoded)
$ api.domain('Auto') # => Array
If you are going to send mass requests, please contact the support team
of the project {Wortschatz}[http://wortschatz.uni-leipzig.de/], get your private
credentials and instantiate an authenticated client:
$ require 'wlapi'
$ api = WLAPI::API.new(username, password)
See documentation in the WLAPI::API class for details
on particular search methods.
== EXCEPTION HIERARCHY
While using WLAPI you can face following errors:
* <tt>WLAPI::UserError</tt>;
* <tt>WLAPI::ExternalError</tt>.
The errors here are presented in the order they may occur
during WLAPI's work.
First WLAPI checks the user input and throws a <tt>WLAPI::UserError</tt>
if the arguments are not appropriate.
Then it fetches a response from a remote server, it can result
in a <tt>WLAPI::ExternalError</tt>. In most cases it will be a simple wrapper
around other errors, e.g. <tt>Savon::SOAP::Fault</tt>.
All of them are subcalsses of <tt>WLAPI::Error</tt> which is in turn a subclass
of the standard +RuntimeError+.
If you want to intercept any and every exception thrown by WLAPI simply rescue
<tt>WLAPI::Error</tt>.
== SUPPORT
If you have question, bug reports or any suggestions, please drop me an email :)
Any help is deeply appreciated!
If you need some new functionality please contact me or provide a pull request.
You code should be complete and tested. Please use <tt>local_*</tt> and
<tt>remote_*</tt> naming convention for your tests.
=== Supported Ruby Versions
The library is testend on the following Ruby interpreters:
* MRI 1.8.7
* MRI 1.9.3
* MRI 2.0.x
* MRI 2.1.x
* JRuby (both 1.8 and 1.9 modes)
* Rubinius
== CHANGELOG
For details on future plan and working progress see CHANGELOG.
== CAUTION
This library is <b>work in process</b>! Though the interface is mostly complete,
you might face some not implemented features.
Please contact me with your suggestions, bug reports and feature requests.
== LICENSE
WLAPI is a copyrighted software by Andrei Beliankou, 2010-2016
You may use, redistribute and change it under the terms provided
in the LICENSE file.