dictionaries 0.3.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62930bb167bba769a92f5706a71e4c2fe336f2d12aa9b5aeeab1b256b5cc71fc
+  data.tar.gz: 2b4c175f20c648c169b84727339ea76f46c7ffe836b69ca8d1161e4b56d43db0
+SHA512:
+  metadata.gz: 9fc775f6d0a1a339c33d9bb9e7b3bb2c3345298b873a2c498bbaf8f641eb370633290c3ff569b3d3d430f2867344b7fb2728d133436670a46a0ef682fc239cd1
+  data.tar.gz: e03551937464bab00ebc197019d5bb73a8e8c52e7e00c3058a7f3288075a16e8618aa729a318e29a75eea2991217e0602b4feacae6e61f20a1d9251d4d40b9d6

data/README.md

@@ -0,0 +1,219 @@
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/dictionaries.svg)](https://badge.fury.io/rb/dictionaries)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">30.07.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">18:47:39</span> o'clock.
+
+## Environment variable to use a specific yaml file
+
+You can use an <b>environment variable</b> to denote the default
+yaml file in use. This allows you to use your own yaml file
+format, rather than the yaml files that are distributed with
+this gem.
+
+The name of that environment variable must be <b>DICTIONARIES_FILE</b>.
+It shall point to your yaml file that holds the key-value pairs.
+
+For example, if your file is at /opt/czech.yml, then
+DICTIONARIES_FILE should point at that location.
+
+In bash, this may be equivalent to:
+
+    export DICTIONARIES_FILE=/opt/czech.yml
+
+Note that in the long run, the dictionaries gem could be extended
+with these yaml files - or allow means to download these files
+over the www. But before we can do so, let's aim for at the least
+100 words in such a file before we would consider distributing
+it or offering means to distribute said file.
+
+## Difficult english sentences
+
+English is not the most difficult language in the world, but when it
+comes to proper pronounciation of words, english can be surprisingly
+difficult.
+
+This subsection may keep a listing of sentences that, for one reason
+or the other, can be somewhat difficult to **read out aloud** without
+mistake, on a first try. It is just a fun-subsection, not meant to be
+taken too seriously; and it is quite subjective.
+
+Without any further ado, here comes a listing of sentences that may
+be difficult to pronounce properly so:
+
+    I would like to distribute something.
+
+## Obtaining all translations into german for a given english word
+
+Since as of **November 2020** the following API exists:
+
+    Dictionaries.return_array_of_translated_words_from_online_leo('cat')
+    Dictionaries.return_array_of_translated_words_from_online_leo('dog')
+    Dictionaries.return_array_of_translated_words_from_online_leo('human')
+
+This will return an Array of german names. It does not work 100% perfectly
+as it is based on a regex; and using a regex to parse HTML is never a
+trivial way. But if you just want to get the first entry, just call
+.first on it, and in most cases this is the best, most likely
+translation available.
+
+The regex has to find matches to entries such as the following one:
+
+    </repr><words><word>der Jazzfan</word></words>
+
+Anyone to come up with a more accurate regex is welcome to share it. :)
+
+This functionality was specifically necessary because I needed to
+use this in the ruby-gtk bindings for this project.
+
+## Dictionaries.return_unique_words_from_this_file
+
+This method will return all words that are presently not registered
+in the english dictionary.
+
+The idea here is for me to slowly add more english words into the
+yaml file. I won't add every english word that exists, but I will
+try to aim for a seizable number in the long run, such as 
+5000 english words - already halfway there. \o/
+
+## GUI component
+
+The **GUI component** of the dictionaries gem defaults to
+**GTK3** finally. It is not a very advanced GUI, though.
+
+First, install the gtk3 gem:
+
+    gem install gtk3
+
+Then install the gtk_paradise project:
+
+    gem install gtk_paradise
+
+Now you should be able to start the GUI component if the above
+has worked:
+
+    dictionaries --gui
+
+See also the help options.
+
+    dictionaries --help
+
+You may need to install some .h files if you use a specific
+Linux distribution; look at the relevant -dev packages for
+this. Or just compile from source. :)
+
+The current version of ruby-gtk3 in October 2021 looks like
+this:
+
+<img src="https://i.imgur.com/K430Kae.png" style="margin-left: 2em">
+
+Yes, this isn't very pretty; I just wanted to focus a bit on
+the functionality. Tons of things are missing, such as 
+switching to other .yml files from within the GUI itself.
+I just wanted to showcase a demo - the convert from
+english-to-german functionality is working, though, so
+the GUI is functional, even if not super-pretty.
+
+In **February 2022** this was improved a little bit. It's still
+not extremely pretty, but you can see a few small improvements.
+In the long run I will add functionality to switch between 
+different .yml files (thus, different dictionaries, such as
+english, italian and so forth) - but it is a hobby project.
+I won't have enough time to add all dictionaries into this
+project as-is. I will, however had, add the possibility to
+load custom .yml files and other formats in the long run,
+so others can adapt the project to suit their needs.
+
+<img src="https://i.imgur.com/ChFJmfo.png" style="margin-left: 2em">
+
+## sinatra
+
+To start the sinatra interface of the dictionaries gem, do:
+
+    dictionaries --sinatra
+
+You can then visit it on the localhost and it may look like
+this:
+
+<img src="https://i.imgur.com/uhzbXZ1.png" style="margin: 0.5em; margin-left: 2em">
+
+You can then input an english word into the form, or the
+URL area in your browser. If this word is registered in
+the .yml file then the following result can be seen:
+
+<img src="https://i.imgur.com/i1RqRmr.png" style="margin: 0.5em; margin-left: 2em">
+
+This is really just very basic - I wanted to show the
+functionality. You may have to adapt the code if you
+have a more realistic use case, so consider the images
+above just as examples of how this <b>could</b> be
+used in a website.
+
+## Generating a .pdf file containing the translations
+
+Since as of <b>July 2022</b> you can generate a .pdf file
+with all the translated words. This functionality depends
+on the <b>prawn</b> gem right now, so make sure that
+this gem is installed before invoking the ruby code
+that generates the .pdf file.
+
+The toplevel API for creating the .pdf file is as follows:
+
+    Dictionaries.generate_pdf_file
+
+## Licence
+
+Until the 17th of October 2019, this project was using the **GPLv2
+licence** (no later clause).
+
+However had, I believe that the GPLv2 licence is not great for
+a project that focuses on existing words in **real languages**,
+aka dictionaries. Thus, I have decided to change the licence into
+the **MIT licence** on that day (**17.11.2019**, in dd.mm.yyyy notation).
+
+So the gem is now MIT licenced. There may be dragons! \o/
+
+For a description of that licence, see
+https://opensource.org/licenses/MIT.
+
+
+## Contact information and mandatory 2FA coming up in 2022
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail for various reasons. In order to limit this
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore, for various reasons.
+
+Do keep in mind that responding to emails may take some time, depending on
+the amount of work I may have at that moment.
+
+In 2022 rubygems.org decided to make 2FA mandatory for every gem owner:
+see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+As I can not use 2FA, for reasons I will skip explaining here (see
+various github issue discussions in the past), this effectively means that
+Betty Li and others who run the show at rubygems.org will perma-ban me
+from using rubygems as a developer.
+
+As I disagree with that decision completely, this will mean that all my
+gems will be removed from rubygems.org prior to that sunset date, e. g.
+before they permanently lock me out from the code that I used
+to maintain. It is pointless to want to discuss this with them anymore -
+they have made up their minds and decided that you can only use
+the code if 2FA is in place, even though the code itself works just
+fine. If you don't use 2FA you are effectively locked out from your
+own code; I consider this a malicious attack. See also how they limited
+discussions to people with mandatory 2FA on the ruby-bugtracker, thus
+banning everyone permanently without 2FA:  
+
+https://bugs.ruby-lang.org/issues/18800
+
+Guess it may indeed be time to finally abandon ruby - not because
+ruby is a bad language, but there are people now in charge who
+really should not be part of ruby in the first place.
+

data/bin/dictionaries

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'dictionaries'
+
+Dictionaries.parse_commandline(ARGV)

data/bin/unique_words_in_this_file

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'dictionaries'
+
+pp Dictionaries.return_unique_words_from_this_file(ARGV)

data/dictionaries.gemspec

@@ -0,0 +1,85 @@
+# =========================================================================== #
+# Gemspec for Project Dictionaries.
+# =========================================================================== #
+require 'dictionaries'
+require 'roebe'
+
+Gem::Specification.new { |s|
+
+  s.name    = 'dictionaries'
+  s.version = Dictionaries::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+This project is called dictionaries.
+
+It used to be called ask_english_words but the name was changed towards
+"dictionaries", when the focus became on dictionaries in general rather
+than merely translations from and to the english language.
+
+There are a total of #{Dictionaries.n_entries?} english words
+registered, with the associated german translation. (It is
+german primarily because that is my native language, but in
+principle this project could be extended to include other
+languages as well. You only need to add a yaml file containing
+the key-value pairs.)
+
+If you need a more comprehensive dictionary, I can recommend
+the file de-en.txt that is part of the tu-chemnitz 
+distribution ( https://www-user.tu-chemnitz.de/~fri/ding/ ). That
+file is really huge - about 20 MB.
+
+In principle, the dictionaries project could be extended to 
+make use of that massive file instead. I will be thinking
+about this for the time being (starting at July 2018).
+
+  EOF
+
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+
+  # ========================================================================= #
+  # Show this message when a user installs this project.
+  # ========================================================================= #
+  s.post_install_message = <<-EOF
+
+  This project can ask or translate english or italian words (or words
+  from any other language, as long as a .yml file is supplied that
+  contains these key-value pair entries).
+
+  This project is probably not very useful for other people, but it helps
+  me to improve my knowledge about the english or italian language or
+  any other language.
+
+  For more information, have a look at the main README.md file, which
+  can also be found on the hompage of this gem at rubygems.org, on
+  the bottom right side (see https://www.rubydoc.info/gems/dictionaries/ ).
+
+  EOF
+  
+  s.extra_rdoc_files = %w()
+
+  s.authors  = ['Robert A. Heiler']
+  s.email    = Roebe.email?
+  s.files    = Dir['**/*']
+  # s.files   << 'README.md'
+  # s.files   << 'USAGE.md'
+  s.license  = 'MIT'
+  s.homepage = 'https://www.rubydoc.info/gems/dictionaries/'
+
+  s.required_ruby_version     = '>= '+Roebe.third_most_stable_version_of_ruby
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  # ========================================================================= #
+  # External dependencies for the project:
+  # ========================================================================= #
+  s.add_dependency 'colours'
+  s.add_dependency 'generate_shell_completion'
+  s.add_dependency 'opn'
+  s.add_dependency 'open'
+  s.add_dependency 'save_file'
+  s.add_dependency 'xorg_buffer'
+
+}

data/doc/README.gen

@@ -0,0 +1,176 @@
+ADD_RUBY_BADGE
+ADD_TIME_STAMP
+
+## Environment variable to use a specific yaml file
+
+You can use an <b>environment variable</b> to denote the default
+yaml file in use. This allows you to use your own yaml file
+format, rather than the yaml files that are distributed with
+this gem.
+
+The name of that environment variable must be <b>DICTIONARIES_FILE</b>.
+It shall point to your yaml file that holds the key-value pairs.
+
+For example, if your file is at /opt/czech.yml, then
+DICTIONARIES_FILE should point at that location.
+
+In bash, this may be equivalent to:
+
+    export DICTIONARIES_FILE=/opt/czech.yml
+
+Note that in the long run, the dictionaries gem could be extended
+with these yaml files - or allow means to download these files
+over the www. But before we can do so, let's aim for at the least
+100 words in such a file before we would consider distributing
+it or offering means to distribute said file.
+
+## Difficult english sentences
+
+English is not the most difficult language in the world, but when it
+comes to proper pronounciation of words, english can be surprisingly
+difficult.
+
+This subsection may keep a listing of sentences that, for one reason
+or the other, can be somewhat difficult to **read out aloud** without
+mistake, on a first try. It is just a fun-subsection, not meant to be
+taken too seriously; and it is quite subjective.
+
+Without any further ado, here comes a listing of sentences that may
+be difficult to pronounce properly so:
+
+    I would like to distribute something.
+
+## Obtaining all translations into german for a given english word
+
+Since as of **November 2020** the following API exists:
+
+    Dictionaries.return_array_of_translated_words_from_online_leo('cat')
+    Dictionaries.return_array_of_translated_words_from_online_leo('dog')
+    Dictionaries.return_array_of_translated_words_from_online_leo('human')
+
+This will return an Array of german names. It does not work 100% perfectly
+as it is based on a regex; and using a regex to parse HTML is never a
+trivial way. But if you just want to get the first entry, just call
+.first on it, and in most cases this is the best, most likely
+translation available.
+
+The regex has to find matches to entries such as the following one:
+
+    </repr><words><word>der Jazzfan</word></words>
+
+Anyone to come up with a more accurate regex is welcome to share it. :)
+
+This functionality was specifically necessary because I needed to
+use this in the ruby-gtk bindings for this project.
+
+## Dictionaries.return_unique_words_from_this_file
+
+This method will return all words that are presently not registered
+in the english dictionary.
+
+The idea here is for me to slowly add more english words into the
+yaml file. I won't add every english word that exists, but I will
+try to aim for a seizable number in the long run, such as 
+5000 english words - already halfway there. \o/
+
+## GUI component
+
+The **GUI component** of the dictionaries gem defaults to
+**GTK3** finally. It is not a very advanced GUI, though.
+
+First, install the gtk3 gem:
+
+    gem install gtk3
+
+Then install the gtk_paradise project:
+
+    gem install gtk_paradise
+
+Now you should be able to start the GUI component if the above
+has worked:
+
+    dictionaries --gui
+
+See also the help options.
+
+    dictionaries --help
+
+You may need to install some .h files if you use a specific
+Linux distribution; look at the relevant -dev packages for
+this. Or just compile from source. :)
+
+The current version of ruby-gtk3 in October 2021 looks like
+this:
+
+<img src="https://i.imgur.com/K430Kae.png" style="margin-left: 2em">
+
+Yes, this isn't very pretty; I just wanted to focus a bit on
+the functionality. Tons of things are missing, such as 
+switching to other .yml files from within the GUI itself.
+I just wanted to showcase a demo - the convert from
+english-to-german functionality is working, though, so
+the GUI is functional, even if not super-pretty.
+
+In **February 2022** this was improved a little bit. It's still
+not extremely pretty, but you can see a few small improvements.
+In the long run I will add functionality to switch between 
+different .yml files (thus, different dictionaries, such as
+english, italian and so forth) - but it is a hobby project.
+I won't have enough time to add all dictionaries into this
+project as-is. I will, however had, add the possibility to
+load custom .yml files and other formats in the long run,
+so others can adapt the project to suit their needs.
+
+<img src="https://i.imgur.com/ChFJmfo.png" style="margin-left: 2em">
+
+## sinatra
+
+To start the sinatra interface of the dictionaries gem, do:
+
+    dictionaries --sinatra
+
+You can then visit it on the localhost and it may look like
+this:
+
+<img src="https://i.imgur.com/uhzbXZ1.png" style="margin: 0.5em; margin-left: 2em">
+
+You can then input an english word into the form, or the
+URL area in your browser. If this word is registered in
+the .yml file then the following result can be seen:
+
+<img src="https://i.imgur.com/i1RqRmr.png" style="margin: 0.5em; margin-left: 2em">
+
+This is really just very basic - I wanted to show the
+functionality. You may have to adapt the code if you
+have a more realistic use case, so consider the images
+above just as examples of how this <b>could</b> be
+used in a website.
+
+## Generating a .pdf file containing the translations
+
+Since as of <b>July 2022</b> you can generate a .pdf file
+with all the translated words. This functionality depends
+on the <b>prawn</b> gem right now, so make sure that
+this gem is installed before invoking the ruby code
+that generates the .pdf file.
+
+The toplevel API for creating the .pdf file is as follows:
+
+    Dictionaries.generate_pdf_file
+
+## Licence
+
+Until the 17th of October 2019, this project was using the **GPLv2
+licence** (no later clause).
+
+However had, I believe that the GPLv2 licence is not great for
+a project that focuses on existing words in **real languages**,
+aka dictionaries. Thus, I have decided to change the licence into
+the **MIT licence** on that day (**17.11.2019**, in dd.mm.yyyy notation).
+
+So the gem is now MIT licenced. There may be dragons! \o/
+
+For a description of that licence, see
+https://opensource.org/licenses/MIT.
+
+ADD_CONTACT_INFORMATION

data/doc/todo/todo.md

@@ -0,0 +1,5 @@
+- Add italian, and GUI support for that.
+
+- AND add stats to the main README, via macro or so,
+  aka "contains 5000 english words, 3000 italian
+  words" or so. Split by <br> I think.

data/lib/dictionaries/ask_english_word.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Dictionaries::AskEnglishWord
+#
+# Use this class to ask a random english word.
+#
+# There are two ways to use this class:
+#
+# - Pass in an optional argument to it, which we will use to query this
+#   word from the database.
+#
+# - Pass nothing to it, in which case we load a random entry.
+#
+# Specific usage examples:
+#
+#   require 'dictionaries'
+#   Dictionaries::AskEnglishWord.new
+#   Dictionaries.ask_english_word
+#
+# =========================================================================== #
+# require 'dictionaries/ask_english_word.rb'
+# Dictionaries.path_to_the_english_file?
+# =========================================================================== #
+require 'dictionaries/class/ask_word_from_dictionary.rb'
+
+module Dictionaries
+
+class AskEnglishWord < AskWordFromDictionary
+
+  # ========================================================================= #
+  # === DATA
+  # ========================================================================= #
+  if defined?(DATA) == 'constant'
+    if DATA.respond_to? :read
+      _ = DATA.read
+    else
+      e 'DATA does not respond to :read'
+    end
+  else
+    _ = ''
+  end
+
+  # ========================================================================= #
+  # === DEFAULT_DELAY
+  # ========================================================================= #
+  if _.to_s.empty? # Next, define the default delay.
+    DEFAULT_DELAY = 2.2 # How long to wait before asking a question.
+  else
+    _ = _.first if _.is_a? Array
+    DEFAULT_DELAY = _.strip.to_f
+  end
+
+  # ========================================================================= #
+  # === AskEnglishWord::THIS_FILE
+  # ========================================================================= #
+  THIS_FILE = THIS_FILE_HERE = __FILE__.to_s
+
+  unless ENV['DICTIONARIES_FILE'] and File.exist?(ENV['DICTIONARIES_FILE'])
+    Dictionaries.set_main_file(THIS_FILE) # Assign it at once.
+  end
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV
+    )
+    super(commandline_arguments, self.class.main_file?)
+  end
+
+  # ========================================================================= #
+  # === Dictionaries::AskEnglishWord.main_file?
+  # ========================================================================= #
+  def self.main_file?
+    Dictionaries.main_file?
+  end
+
+  # ========================================================================= #
+  # === Dictionaries::AskEnglishWord.dataset?
+  #
+  # Note that this method will load the dataset from the main file anew
+  # whenever you invoke it.
+  # ========================================================================= #
+  def self.dataset?
+    YAML.load_file(self.main_file?)
+  end
+
+  # ========================================================================= #
+  # === Dictionaries::AskEnglishWord.n_entries?
+  #
+  # Feedback how many entries are registered.
+  # ========================================================================= #
+  def self.n_entries?
+    _ = dataset?
+    n_entries = _.size
+    return n_entries
+  end; self.instance_eval { alias n_questions? n_entries? } # === AskEnglishWord.n_questions?
+
+  # ========================================================================= #
+  # === Dictionaries::AskEnglishWord[]
+  # ========================================================================= #
+  def self.[](i)
+    self.new(i)
+  end
+
+end
+
+# =========================================================================== #
+# === Dictionaries.ask_english_word
+# =========================================================================== #
+def self.ask_english_word
+  AskEnglishWord.new
+end
+
+# =========================================================================== #
+# === Dictionaries.path_to_the_english_file?
+#
+# This method may return a String, as a file path, such as
+# "/home/Programs/Ruby/2.7.2/lib/ruby/site_ruby/2.7.0/dictionaries/yaml/english.yml".
+# =========================================================================== #
+def self.path_to_the_english_file?
+  Dictionaries.main_file?
+end
+
+# =========================================================================== #
+# === Dictionaries.n_entries?
+# =========================================================================== #
+def self.n_entries?
+  ::Dictionaries::AskEnglishWord.n_entries?
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Dictionaries::AskEnglishWord.new(ARGV)
+end # askeng
+# This is the delay to use for this class.
+__END__
+1.8