katsuyou 1.0.0

data/README.md

@@ -0,0 +1,175 @@
+# Katsuyou / 活用 (lit. "Conjugation")
+
+An API for conjugating Japanese words
+
+## Installation
+
+Stick this in your Gemfile and 吸う it:
+
+```
+gem "katsuyou"
+```
+
+## Usage
+
+### `Katsuyou.conjugate(word, type:)`
+
+This gem generates conjugations for ichidan ("る") and godan ("う") verbs, as
+well as the two notable exceptions in suru (する) and kuru (来る). Other verbs
+exist (like [nidan
+verbs](https://en.wiktionary.org/wiki/Category:Japanese_nidan_verbs)), but as
+they're (apparently, I'm no expert) archaisms, I didn't bother implementing
+them.
+
+``` ruby
+Katsuyou.conjugate("食べる", type: :ichidan_verb)
+Katsuyou.conjugate("聞く", type: :godan_verb)
+Katsuyou.conjugate("学ぶ", type: "v5b")
+
+# Our special cases
+Katsuyou.conjugate("する", type: :suru_verb)
+Katsuyou.conjugate("勉強", type: :suru_verb)
+Katsuyou.conjugate("来る", type: :kuru_verb)
+```
+
+(By the way, if you're not sure what type of verb a given word is, consult a
+[primer on verb
+groups](https://www.tofugu.com/japanese-grammar/verb-conjugation-groups/) and a
+[dictionary](https://jisho.org) to be sure)
+
+And you'll get back a [Struct](https://ruby-doc.org/core-2.7.0/Struct.html)
+subclass containing a number of conjugated forms:
+
+```ruby
+conjugations = Katsuyou.conjugate("見せる", type: :ichidan_verb)
+
+#  #<struct Katsuyou::VerbConjugation
+#   conjugation_type=
+#    #<struct Katsuyou::ConjugationType
+#     code="v1",
+#     description="Ichidan verb",
+#     category=:ichidan_verb,
+#     supported=true>,
+#   present="見せる",
+#   present_polite="見せます",
+#   present_negative="見せない",
+#   present_negative_polite="見せません",
+#   past="見せた",
+#   past_polite="見せました",
+#   past_negative="見せなかった",
+#   past_negative_polite="見せませんでした",
+#   conjunctive="見せて",
+#   conjunctive_polite="見せまして",
+#   conjunctive_negative="見せなくて",
+#   conjunctive_negative_polite="見せませんで",
+#   provisional="見せれば",
+#   provisional_negative="見せなければ",
+#   volitional="見せよう",
+#   volitional_polite="見せましょう",
+#   imperative="見せろ",
+#   imperative_negative="見せるな",
+#   potential="見せられる",
+#   potential_polite="見せられます",
+#   potential_negative="見せられない",
+#   potential_negative_polite="見せられません",
+#   passive="見せられる",
+#   passive_polite="見せられます",
+#   passive_negative="見せられない",
+#   passive_negative_polite="見せられません",
+#   causative="見せさせる",
+#   causative_polite="見せさせます",
+#   causative_negative="見せさせない",
+#   causative_negative_polite="見せさせません",
+#   causative_passive="見せさせられる",
+#   causative_passive_polite="見せさせられます",
+#   causative_passive_negative="見せさせられない",
+#   causative_passive_negative_polite="見せさせられません">
+```
+
+### `Katsuyou.conjugatable?(word, type:)`
+
+If you're not sure whether a particular word & type is supported, you can ask
+first with `conjugatable?` (note that `conjugate()` will raise if a conjugation
+type is unsupported or unknown)
+
+```
+Katsuyou.conjugatable?("食べる", type: :ichidan_verb) # => true
+Katsuyou.conjugatable?("買う", type: "v5u") # => true
+Katsuyou.conjugatable?("食", type: :ichidan_verb) # => false, all ichidan verbs end in る
+Katsuyou.conjugatable?("ぷす", type: "v9s") # => false, unknown type "v9s"
+```
+
+### Conjugation types
+
+The `conjugate(text, type:)` method **requires** you to supply a `type` value.
+There are two categories of values that the gem accepts.
+
+#### General conjugation types
+
+First, as illustarted at the outset, these _general_ conjugation types are
+supported:
+
+* `ichidan_verb` (e.g. 食べる)
+* `godan_verb` (e.g. 買う)
+* `kuru_verb` (e.g. 来る)
+* `suru_verb` (namely, する but also nouns that can take する like 勉強)
+
+If you provide one of the above conjugation types, the gem will attempt to
+translate it to a more specific conjugation form, which are identified by the
+same codes as listed under conjugate-able entries' parts of speech in
+[JMDict/EDICT](http://www.edrdg.org/jmdict/edict_doc.html).
+
+#### Specific conjugation codes
+
+As a result of the preceding, if you're passing in values from a JMDict-based
+dictionary, it probably makes more sense to pass the specific code (e.g.
+`Katsuyou.conjugate("請う", type: "v5u-s")`) to ensure that you get the most
+accurate results.
+
+You can find codes the gem knows about in `Katsuyou::CONJUGATION_TYPES`.
+
+For example to see the supported conjugation types:
+
+```ruby
+puts Katsuyou::CONJUGATION_TYPES.select(&:supported).map { |type| "#  • #{type.code}" }.join("\n")
+#  • v1
+#  • v1-s
+#  • v5aru
+#  • v5b
+#  • v5g
+#  • v5k
+#  • v5k-s
+#  • v5m
+#  • v5n
+#  • v5r
+#  • v5r-i
+#  • v5s
+#  • v5t
+#  • v5u
+#  • v5u-s
+#  • vk
+#  • vs
+#  • vs-s
+#  • vs-i
+```
+
+And likewise, for the known-but-unsupported ones:
+
+```ruby
+puts Katsuyou::CONJUGATION_TYPES.reject(&:supported).map { |type| "#  • #{type.code}" }.join("\n")
+#  • adj-i
+#  • adj-na
+#  • adj-t
+#  • adv-to
+#  • aux
+#  • aux-v
+#  • aux-adj
+#  • v2a-s
+#  • v4h
+#  • v4r
+#  • v5uru
+#  • vz
+#  • vn
+#  • vr
+#  • vs-c
+```

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.warning = false
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: [:test, "standard:fix"]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "katsuyou"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/katsuyou.gemspec

@@ -0,0 +1,22 @@
+require_relative "lib/katsuyou/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "katsuyou"
+  spec.version = Katsuyou::VERSION
+  spec.authors = ["Justin Searls"]
+  spec.email = ["searls@gmail.com"]
+
+  spec.summary = "Conjugates Japanese words"
+  spec.homepage = "https://github.com/searls/katsuyou"
+  spec.license = "GPL-3.0-only"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/katsuyou.rb

@@ -0,0 +1,17 @@
+require "katsuyou/version"
+require_relative "katsuyou/conjugates_verb"
+require_relative "katsuyou/checks_conjugability"
+
+module Katsuyou
+  class Error < StandardError; end
+  class UnsupportedConjugationTypeError < Error; end
+  class InvalidConjugationTypeError < Error; end
+
+  def self.conjugate(verb, type:)
+    ConjugatesVerb.new.call(verb, type: type)
+  end
+
+  def self.conjugatable?(verb, type:)
+    ChecksConjugability.new.call(verb, type: type)
+  end
+end

data/lib/katsuyou/checks_conjugability.rb

@@ -0,0 +1,65 @@
+require_relative "determines_type"
+
+module Katsuyou
+  class ChecksConjugability
+    def initialize
+      @determines_type = DeterminesType.new
+    end
+
+    def call(word, type:)
+      return false if any_not_present?(word, type)
+      return false unless (conjugation_type = @determines_type.call(text: word, type: type))
+      return false unless conjugation_type.supported?
+
+      case conjugation_type.category
+      when :ichidan_verb then valid_ichidan_verb?(word, conjugation_type)
+      when :godan_verb then valid_godan_verb?(word, conjugation_type)
+      when :kuru_verb then valid_kuru_verb?(word, conjugation_type)
+      when :suru_verb then valid_suru_verb?(word, conjugation_type)
+      else false
+      end
+    end
+
+    private
+
+    def valid_ichidan_verb?(word, conjugation_type)
+      word.end_with?("る")
+    end
+
+    def valid_godan_verb?(word, conjugation_type)
+      return false unless word.end_with?("ぶ", "ぐ", "く", "む", "ぬ", "る", "す", "つ", "う")
+      last_char = word[-1]
+      case conjugation_type.code
+      when "v5b" then last_char == "ぶ"
+      when "v5g" then last_char == "ぐ"
+      when "v5k" then last_char == "く"
+      when "v5k-s" then last_char == "く"
+      when "v5m" then last_char == "む"
+      when "v5n" then last_char == "ぬ"
+      when "v5r" then last_char == "る"
+      when "v5r-i" then last_char == "る"
+      when "v5s" then last_char == "す"
+      when "v5t" then last_char == "つ"
+      when "v5u" then last_char == "う"
+      end
+    end
+
+    def valid_kuru_verb?(word, conjugation_type)
+      word.end_with?("来る", "くる")
+    end
+
+    def valid_suru_verb?(word, conjugation_type)
+      if conjugation_type.code == "vs"
+        !word.end_with?("為る", "する")
+      else
+        word.end_with?("為る", "する")
+      end
+    end
+
+    def any_not_present?(*args)
+      args.any? { |arg|
+        arg.to_s.size.zero?
+      }
+    end
+  end
+end

data/lib/katsuyou/conjugates_verb.rb

@@ -0,0 +1,35 @@
+require_relative "determines_type"
+require_relative "verb_conjugation"
+require_relative "zips_endings"
+
+module Katsuyou
+  class ConjugatesVerb
+    def initialize
+      @determines_type = DeterminesType.new
+      @zips_endings = ZipsEndings.new
+    end
+
+    def call(verb, type:)
+      conjugation_type = @determines_type.call(text: verb, type: type)
+      ensure_valid_conjugation_type!(type, conjugation_type)
+
+      VerbConjugation.new({
+        conjugation_type: conjugation_type
+      }.merge(@zips_endings.call(verb, conjugation_type)))
+    end
+
+    private
+
+    def ensure_valid_conjugation_type!(user_type, conjugation_type)
+      if conjugation_type.nil?
+        raise InvalidConjugationTypeError.new(
+          "We don't know about conjugation type '#{user_type}'"
+        )
+      elsif !conjugation_type.supported
+        raise UnsupportedConjugationTypeError.new(
+          "Conjugation type '#{conjugation_type.code}' is not yet supported"
+        )
+      end
+    end
+  end
+end

data/lib/katsuyou/conjugation_type.rb

@@ -0,0 +1,12 @@
+module Katsuyou
+  class ConjugationType < Struct.new(:code, :description, :category, :supported, keyword_init: true)
+    def initialize(supported: true, **kwargs)
+      @supported = supported
+      super
+    end
+
+    def supported?
+      @supported
+    end
+  end
+end

data/lib/katsuyou/determines_type.rb

@@ -0,0 +1,96 @@
+require_relative "conjugation_type"
+require_relative "verb_ending"
+
+module Katsuyou
+  CONJUGATION_TYPES = [
+    ConjugationType.new(code: "adj-i", description: "adjective (keiyoushi)", category: :adjective, supported: false),
+    ConjugationType.new(code: "adj-na", description: "adjectival nouns or quasi-adjectives (keiyodoshi)", category: :adjective, supported: false),
+    ConjugationType.new(code: "adj-t", description: "`taru' adjective", category: :adjective, supported: false),
+    ConjugationType.new(code: "adv-to", description: "adverb taking the `to' particle", category: :adverb, supported: false),
+    ConjugationType.new(code: "aux", description: "auxiliary", category: :auxiliary, supported: false),
+    ConjugationType.new(code: "aux-v", description: "auxiliary verb", category: :auxiliary, supported: false),
+    ConjugationType.new(code: "aux-adj", description: "auxiliary adjective", category: :auxiliary, supported: false),
+    ConjugationType.new(code: "v1", description: "Ichidan verb", category: :ichidan_verb, supported: true),
+    ConjugationType.new(code: "v1-s", description: "Ichidan verb - kureru special class", category: :ichidan_verb, supported: true),
+    ConjugationType.new(code: "v2a-s", description: "Nidan verb with 'u' ending (archaic)", category: :other_verb, supported: false),
+    ConjugationType.new(code: "v4h", description: "Yodan verb with `hu/fu' ending (archaic)", category: :other_verb, supported: false),
+    ConjugationType.new(code: "v4r", description: "Yodan verb with `ru' ending (archaic)", category: :other_verb, supported: false),
+    ConjugationType.new(code: "v5aru", description: "Godan verb - -aru special class", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5b", description: "Godan verb with `bu' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5g", description: "Godan verb with `gu' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5k", description: "Godan verb with `ku' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5k-s", description: "Godan verb - Iku/Yuku special class", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5m", description: "Godan verb with `mu' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5n", description: "Godan verb with `nu' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5r", description: "Godan verb with `ru' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5r-i", description: "Godan verb with `ru' ending (irregular verb)", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5s", description: "Godan verb with `su' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5t", description: "Godan verb with `tsu' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5u", description: "Godan verb with `u' ending", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5u-s", description: "Godan verb with `u' ending (special class)", category: :godan_verb, supported: true),
+    ConjugationType.new(code: "v5uru", description: "Godan verb - Uru old class verb (old form of Eru)", category: :godan_verb, supported: false),
+    ConjugationType.new(code: "vz", description: "Ichidan verb - zuru verb (alternative form of -jiru verbs)", category: :ichidan_verb, supported: false),
+    ConjugationType.new(code: "vk", description: "Kuru verb - special class", category: :kuru_verb, supported: true),
+    ConjugationType.new(code: "vn", description: "irregular nu verb", category: :other_verb, supported: false),
+    ConjugationType.new(code: "vr", description: "irregular ru verb, plain form ends with -ri", category: :other_verb, supported: false),
+    ConjugationType.new(code: "vs", description: "noun or participle which takes the aux. verb suru", category: :suru_verb, supported: true),
+    ConjugationType.new(code: "vs-c", description: "su verb - precursor to the modern suru", category: :suru_verb, supported: false),
+    ConjugationType.new(code: "vs-s", description: "suru verb - special class", category: :suru_verb, supported: true),
+    ConjugationType.new(code: "vs-i", description: "suru verb - included", category: :suru_verb, supported: true)
+  ]
+
+  class DeterminesType
+    def self.type_for(code)
+      CONJUGATION_TYPES.find { |type| type.code == code }
+    end
+
+    def call(text:, type:)
+      type = type.to_s
+      if type == "ichidan_verb"
+        type_for("v1")
+      elsif type == "godan_verb"
+        guess_godan_type(text)
+      elsif type == "kuru_verb"
+        type_for("vk")
+      elsif type == "suru_verb"
+        guess_suru_type(text)
+      else
+        type_for(type)
+      end
+    end
+
+    private
+
+    def guess_godan_type(text)
+      if text.end_with?("行く", "いく")
+        type_for("v5k-s")
+      elsif text.end_with?("有る", "ある")
+        type_for("v5r-i")
+      else
+        case text[-1]
+        when "ぶ" then type_for("v5b")
+        when "ぐ" then type_for("v5g")
+        when "く" then type_for("v5k")
+        when "む" then type_for("v5m")
+        when "ぬ" then type_for("v5n")
+        when "る" then type_for("v5r")
+        when "す" then type_for("v5s")
+        when "つ" then type_for("v5t")
+        when "う" then type_for("v5u")
+        end
+      end
+    end
+
+    def guess_suru_type(text)
+      if text.end_with?("為る", "する")
+        type_for("vs-i")
+      else
+        type_for("vs")
+      end
+    end
+
+    def type_for(code)
+      self.class.type_for(code)
+    end
+  end
+end