# WWWJDic
Copyright © 2014, 2015, 2016, 2017, 2018, 2019 Marco Bresciani
This file is part of wwwjdic.
wwwjdic is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.
wwwjdic is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along
with wwwjdic. If not, see .
## Description
This gem uses WWWJDic Backdoor Entry/API as described by
http://www.csse.monash.edu.au/~jwb/wwwjdicinf.html#backdoor_tag to
interact with WWWJDic and translate to and from Japanese language.
WWWJDic is an online Japanese translation server made by Jim Breen and
available at http://www.edrdg.org/cgi-bin/wwwjdic/wwwjdic?1C .
GNU GPLv3 license; source code (not yet) available through anonymous
checkout: `hg clone http://hg.savannah.nongnu.org/hgweb/wwwjdic/` or
write me and I'll send it.
You can even decide to contribute to this little free software project
by registering to Savannah and ask to be part of the 'WWWJDic' project!
With contributions from: Jim Breen, 新部裕, Jon Maken.
## Documentation
WWWJDic tries to follow semantic versioning (see http://semver.org/).
There may be backward incompatible changes each time minor version
number changes, but that any tiny version number change should be bug
fixes and internal changes only. Be sure to read the CHANGELOG each time
we cut a new release and lock your gems accordingly.
RDoc documentation available in the html folder.
### Installing WWWJDic
RubyGems is the preferred easy install method for WWWJDic. WWWJDic is
intended to be installed via the
[RubyGems](http://rubyforge.org/projects/rubygems/) system. To get the
latest version, simply enter the following into your command prompt:
`gem install wwwjdic`.
### Supported Ruby Versions and Implementations
Because WWWJDic is pure Ruby, it should run pretty much anywhere,
including Rubinius, JRuby, MacRuby, etc. Officially the support is for
2.x MRI.
### Support
The easiest way to get help with WWWJDic is to post a message to the
mailing list: `http://lists.nongnu.org/mailman/listinfo/wwwjdic-users`
Feel free to post any question there, developers are responsive and will
be happy to help you figure out how to use WWWJDic, or help you
determine whether it's the right tool for the task you are working on.
Please make your posts to the list as specific as possible, including
code samples and output where relevant. Do not post any information that
should not be shared publicly, and be sure to reduce your example code
as much as possible so that those who are responding to your question
can more easily see what the issue might be.
### Contributing
If you've found a bug, want to submit a patch, or have a feature
request, please enter a ticket into our bug tracker:
`https://savannah.nongnu.org/bugs/?func=additem&group=wwwjdic`
We strongly encourage bug reports to come with failing tests or at least
a reduced example that demonstrates the problem.
Similarly, patches should include tests, API documentation, and an
update to the manual where relevant. Feel free to clone early though and
participate in the project, if you just want some feedback or a code
review before preparing your code to be merged.
If you are unsure about whether or not you've found a bug, or want to
check to see whether we'd be interested in the feature you want to add
before you start working on it, feel free to post to our mailing list.
### License
WWWJDic is released under GNU GPL v3 license: if you wish to contribute
to WWWJDic, you will retain your own copyright but must agree to license
your code under the same terms as the project itself (or any compatible
license according to [GPL Compatible
Licenses](http://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses)).
### Links
#### Savannah
* Project page: https://savannah.nongnu.org/projects/wwwjdic/
* Source code (Mercurial) repository: http://hg.savannah.gnu.org/hgweb/wwwjdic/
* Known Bugs: https://savannah.nongnu.org/bugs/?group=wwwjdic
* Users Mailing List: https://savannah.nongnu.org/mail/?group=wwwjdic
* News: https://savannah.nongnu.org/news/?group=wwwjdic
#### RubyGems
* Gem page: https://rubygems.org/gems/wwwjdic
* Online RDoc: http://rubydoc.info/gems/wwwjdic/
* Gem updates Atom Feed: https://rubygems.org/gems/wwwjdic/versions.atom
#### Other links
* WWWJDic: http://www.edrdg.org/cgi-bin/wwwjdic/wwwjdic?1C .
* Jim Breen's Japanese Page: http://nihongo.monash.edu/japanese.html#links_software
* "An HTTP/HTTPS/FTP file downloader library/CLI based upon
MiniPortile's HTTP implementation." gist by Jon Maken:
https://gist.github.com/jonforums/2202048.
### Usage Examples
See `examples` folder. To run the examples just run
`ruby examples/`{EXAMPLE_NAME}`.rb`. Running the examples you'll see
both the example description and correct code usage to perform such
action. Here below are listed the currently available examples:
* The `basics.rb` example (run `ruby examples/basics.rb`) shows how to
initialize and use a WWWJDic object through the `breener` factory
method;
* The `uri.rb` example (run `ruby examples/uri.rb`) shows how to ask for
translation URI at WWWJDic, with all available options and
configurations.
* The `translate.rb` example (run `ruby examples/translate.rb`) shows
how to ask for an actual translation through WWWJDic Backdoor/API,
with all available options and configurations. It will also show how
to download such translation;
Using this API is pretty simple. First, get a reference to the WWWJDic
object, through its factory method with
my_wwwjdic = WWWJDic::breener
This will save a WWWJDic instance in your `my_wwwjdic` object.
#### Parameters
You can then start possibly manipulating some basic parameters that can
be set and read from the API. These are not mandatory settings, but are
useful whether you'll use your `my_wwwjdic` object for further similar
requests: settings these values internally will save you type more
parameters in the request, leaving only the word to search/translate as
needed.
* the `server` name/URL to use:
my_wwwjdic.server # returns the default server URL http://www.csse.monash.edu.au/~jwb/cgi-bin/wwwjdic.cgi?
my_wwwjdic.to_s # contains the URL above
# this below is (again) the default configured server
my_wwwjdic.server = :edrdg
my_wwwjdic.server # returns the URL http://www.edrdg.org/cgi-bin/wwwjdic/wwwjdic.cgi?
my_wwwjdic.to_s # contains the URL above
# this is the additional server
my_wwwjdic.server = :monash
my_wwwjdic.server # returns the URL http://www.csse.monash.edu.au/~jwb/cgi-bin/wwwjdic.cgi?
my_wwwjdic.to_s # contains the URL above
* the default reference `dictionary` to use for translations. All
currently available dictionaries strings can be used: `'1'`, `'2'`,
`'3'`, `'4'`, `'5'`, `'6'`, `'7'`, `'8'`, `'9'`, `'A'`, `'B'`, `'C'`,
`'D'`, `'E'`, `'F'`, `'G'`, `'H'`, `'I'`, `'J'`, `'K'`, `'L'`, `'M'`,
`'N'`, `'O'`, `'P'`, `'Q'` and `'R'`.
You can even use the whole (exact) dictionary strings as listed in the
WWWJDic HTML source code: `'Jpn-Eng General (EDICT)'`,
`'Japanese Names (ENAMDICT)'`, `'Computing/Telecomms'`,
`'Life Sciences/Bio-Med'`, `'Legal Terms'`, `'Finance/Marketing'`,
`'Buddhism'`, `'Miscellaneous'`, `'Special Text-glossing'`,
`'Engineering/Science'`, `'Linguistics'`, `'River & Water Systems'`,
`'Automobile Industry'`, `'Japanese Wordnet'`,
`'Work-in-progress File'`, `'Japanese-German (WaDoku)'`,
`'Japanese-French'`, `'Japanese-Russian'`, `'Japanese-Swedish'`,
`'Japanese-Hungarian'`, `'Japanese-Spanish'`, `'Japanese-Dutch'`,
`'Japanese-Slovenian'`, `'Japanese-Italian'`, `'Untranslated'`,
`'Combined Jpn-Eng'`, `'Expanded Text-glossing'`.
my_wwwjdic.dictionary # returns 0 as default, if not set
my_wwwjdic.dictionary = '7'
my_wwwjdic.dictionary # returns the string '7'
* Then you can obviously ask for a translation reference URL. Basic
examples:
my_wwwjdic.uri 'word' # this return the URL for translation of 'word', with normal display format
my_wwwjdic.raw_uri 'word' # this return the URL for translation of 'word', with raw display format
my_wwwjdic.json_uri 'word' # this return the URL for translation of 'word', returning a JSON data as { 'word': 'url' } with normal display format
* Then, instead of the pure URL to reference the WWWJDic site, you can
retrieve the actual translation itself or save it to a file:
my_wwwjdic.translate 'word' # returns a string containing the web page content of the raw display format
my_wwwjdic.translate 'word', nil, filename # regardless the nil (see it later) the third parameter is the filename where to save the retrieved translation
* Another possible result for translation is to get it in JSON format
also with the possibility to save it in a file.
my_wwwjdic.json_translate 'word' # returns the JSON format of the translation.
For this, the resulting JSON format will be:
{
word : translation uri for raw display format
'title' : title (extracted from
TITLE
tags in raw display format)
'translation' : translation content (extracted from TRANSLATION
raw display format
'message' : possible error message or result (extracted from MESSAGE\n raw display format
}
* Now let's come to the second parameter of the methods above (set to
`nil` in the examples), the arguments for the translation. The default
is to translate to/from English/Japanese with normal display layout
and no other specificities, except that the API automatically
identifies Japanese or English and manages the romaji and so on. The
returned URL is the default EDR&DG one. What if the user wants to
customize something? The `args`, second parameter of all those methods
above, is a dictionary (hash map) that allows to specify which
parameters and to which values they shall be set.
Valid parameters, and their values are:
* `dict` parameter allows both numbers and (exact) strings to select
dictionaries: `'1'`, `'2'`, `'3'`, `'4'`, `'5'`, `'6'`, `'7'`,
`'8'`, `'9'`, `'A'`, `'B'`, `'C'`, `'D'`, `'E'`, `'F'`, `'G'`,
`'H'`, `'I'`, `'J'`, `'K'`, `'L'`, `'M'`, `'N'`, `'O'`, `'P'`,
`'Q'`, and `'R'`, together with the full (exact) strings
`'Jpn-Eng General (EDICT)'`, `'Japanese Names (ENAMDICT)'`,
`'Computing/Telecomms'`, `'Life Sciences/Bio-Med'`,
`'Legal Terms'`, `'Finance/Marketing'`, `'Buddhism'`,
`'Miscellaneous'`, `'Special Text-glossing'`,
`'Engineering/Science'`, `'Linguistics'`,
`'River & Water Systems'`, `'Automobile Industry'`,
`'Japanese Wordnet'`, `'Work-in-progress File'`,
`'Japanese-German (WaDoku)'`, `'Japanese-French'`,
`'Japanese-Russian'`, `'Japanese-Swedish'`,
`'Japanese-Hungarian'`, `'Japanese-Spanish'`, `'Japanese-Dutch'`,
`'Japanese-Slovenian'`, `'Japanese-Italian'`, `'Untranslated'`,
`'Combined Jpn-Eng'` and `'Expanded Text-glossing'`.
* `display` parameter to select the final format of the referred
HTML page (either regular HTML or raw): `:regular`, `:raw`.
* `server` allows the user to select from the default URL (at
Electronic Dictionaries R&D Group) or the Monash university URL:
`:edrdg`, `:monash`.
Some examples of these parameters' usage:
my_wwwjdic.translate 'sprache', dict: 'F' # this translates using the 'F' dictionary, that is the German one
my_wwwjdic.uri 'sprache', dict: 'F' # same as above, but returns the translation URL, instead
my_wwwjdic.raw_uri 'sprache', dict: 'F' # same as above, but returns the translation URL with raw display, instead
my_wwwjdic.uri 'sprache', dict: 'F', display: raw # same as above
------------------------------------------
wwwjdic
Copyright © 2014, 2015, 2016, 2017, 2018, 2019 Marco Bresciani
This file is part of wwwjdic.
wwwjdic is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.
wwwjdic is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along
with wwwjdic. If not, see .