voikko 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75cea670fe743bc6a519289cbed7089191dd23be56c8bf5391690c5a7ac8b847
-  data.tar.gz: 4d75c2e84b678dfa56d32aa423869926284c0c09cea9cea221f63615198bb0b8
+  metadata.gz: 3373dd013ef670ef919fcce3d9433ceed0e6db2cf5a0997e9748a6a049d0c1ea
+  data.tar.gz: 81808200246a3c053245da55a53301e7010f45eb1ade3c6b045b05aec6997b5a
 SHA512:
-  metadata.gz: 8fb7bbac4b9f7ed072e94a15476ca6189737c217dbd2ef1935ab0d469a139eca9a71cfd6de4a90afde7de7d8fb5b8cd7df58a8c6ba865d9f726fc4bc2240ca89
-  data.tar.gz: d87866cc079d8f7084d742b9e2e31045495829a3ae6c37d913d4a689a5c87b0152fbd959249908bc29a27532a49d1979f883ff55e5460d835e37c11c50d51e04
+  metadata.gz: afd59170b5903fb22a98d6e924e00bd7448b82a290f211612d8e76a90dbdf13b374d4e0616934f03f1cc6d15a69fc3bd23550480142d49ca7416d618f5ab7ea1
+  data.tar.gz: '075780f8e3f06ea76a6f7f6c1bfca7c24f5a9e86eac8d92037e67f1f37c6493725e9dbd96849f52afb44dd844f0837995c2f332912562bd8a8771f1abe927c6e'

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-15
+
+- `Analysis#morphemes` cuts the word into `Voikko::Morpheme`s decoded from `STRUCTURE`, and `Analysis` now holds the analysed `word`, so a hand-built `Analysis.new(attributes)` becomes `Analysis.new(word, attributes)`.
+- `Voikko#language` answers the language tag the handle was opened with.
+- `require 'voikko'` no longer needs libvoikko: the first `Voikko.new` or `Voikko.library_version` binds it, so a caller rescuing a missing library moves its `rescue LoadError` from the `require` to that call.
+
 ## [0.1.0] - 2026-10-14
 
 - Initial release: a `Voikko` handle on the system libvoikko (Ruby ≥ 3.3, Linux) whose `#analyze` returns `Voikko::Analysis` values and `#base_forms` a word's dictionary forms.

data/README.md

@@ -32,11 +32,19 @@ Voikko.open(language: 'fi') do |voikko|
   kadulla.sijamuoto                 #=> "ulkoolento"
   voikko.base_forms('voi')          #=> ["voida", "voi"]
   voikko.base_forms('HELSINGISSÄ')  #=> ["Helsinki"]
+
+  # A compound, cut into its parts as written:
+  voikko.analyze('tietokoneella').first.morphemes.map(&:text)  #=> ["tieto", "koneella"]
 end
 ```
 
 `Voikko.open` closes the handle after the block; `Voikko.new` leaves that to `#close`.
 
+`require 'voikko'` does not load libvoikko; the first `Voikko.new` does. So your tests can
+build a `Voikko::Analysis` by hand on a machine without libvoikko.
+
+The full API is documented on [rubydoc.info](https://rubydoc.info/gems/voikko).
+
 ## License
 
 MIT, see [LICENSE](LICENSE). The gem ships no Voikko code or data: libvoikko

data/lib/voikko/lib.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+class Voikko
+  # The C functions, bound by the versioned soname: the bare +libvoikko.so+ ships only with
+  # +libvoikko-dev+. A missing library re-raises +LoadError+, so a caller that makes the gem
+  # optional still rescues it, with the packages to install appended.
+  #
+  # Its own file, required on first use rather than by +voikko.rb+, so {Voikko::Analysis} and
+  # {Voikko::Morpheme} work where libvoikko is not installed.
+  module Lib
+    extend FFI::Library
+
+    begin
+      ffi_lib 'libvoikko.so.1'
+    rescue LoadError => e
+      raise LoadError, "#{e.message}\nlibvoikko is not installed: apt install libvoikko1 voikko-fi"
+    end
+
+    attach_function :voikkoGetVersion, [], :string
+    attach_function :voikkoInit, %i[pointer string string], :pointer
+    attach_function :voikkoTerminate, [:pointer], :void
+    attach_function :voikkoAnalyzeWordCstr, %i[pointer string], :pointer
+    attach_function :voikko_free_mor_analysis, [:pointer], :void
+    attach_function :voikko_mor_analysis_keys, [:pointer], :pointer
+    attach_function :voikko_mor_analysis_value_cstr, %i[pointer pointer], :pointer
+    attach_function :voikko_free_mor_analysis_value_cstr, [:pointer], :void
+  end
+  private_constant :Lib
+end

data/lib/voikko/version.rb

@@ -2,5 +2,5 @@
 
 class Voikko
   # @return [String] the gem's version.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/voikko.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'ffi'
 require_relative 'voikko/version'
 
 # A handle on libvoikko, the Finnish morphological analyser, bound through FFI to the system's
@@ -15,8 +14,17 @@ require_relative 'voikko/version'
 #
 # A handle holds about 0.5 MB of native memory that Ruby's GC cannot see: prefer {.open}, which
 # closes it after the block, or call {#close} yourself. A forgotten handle is still freed by a
-# finalizer once unreachable. After {#close}, every method but {#close} and {#closed?} raises
-# {Error}.
+# finalizer once unreachable. After {#close}, every method but {#close}, {#closed?} and
+# {#language} raises {Error}.
+#
+# +require 'voikko'+ loads no native code; the first {.new} or {.library_version} binds
+# libvoikko. So {Analysis} and {Morpheme} are plain Ruby wherever the gem is installed, and a
+# caller's tests can build one without libvoikko:
+#
+#   analysis = Voikko::Analysis.new('tietokoneella', { 'STRUCTURE' => '=ppppp=pppppppp' })
+#   analysis.morphemes.map(&:text)   #=> ["tieto", "koneella"]
+#
+# The braces are needed: bare, Ruby passes the +'STRUCTURE' =>+ hash as keywords.
 #
 # Named +Voikko+, not +Voikko::Analyzer+, because libvoikko also spells, hyphenates and checks
 # grammar; those methods (+#spell+, +#suggest+, +#hyphenate+) would sit here, and are not bound
@@ -31,10 +39,11 @@ class Voikko
   # libvoikko refused: a dictionary failed to open, or the handle is already closed.
   class Error < StandardError; end
 
-  # One reading of a word, as libvoikko gives it: a frozen +Hash{String => String}+ of its
-  # attributes, with a reader for each key libvoikko defines.
+  # One reading of a word, as libvoikko gives it: the word as analysed, and a frozen
+  # +Hash{String => String}+ of its attributes with a reader for each key libvoikko defines.
   #
   #   analysis = voikko.analyze('kadulla').first
+  #   analysis.word               #=> "kadulla"
   #   analysis.base_form          #=> "katu"
   #   analysis.word_class         #=> "nimisana"
   #   analysis.tense              #=> nil, a noun has none
@@ -46,11 +55,41 @@ class Voikko
   # +nil+ where the dictionary's backend or the word class has no such attribute; no key is
   # present for every backend. Values stay libvoikko's strings: +negative+ is +"true"+,
   # +"false"+ or +"both"+, +person+ is +"1"+. +FSTOUTPUT+ passes through like any other key.
-  # {#[]} and {#to_h} reach a key a later libvoikko adds.
+  # {#[]} and {#to_h} reach a key a later libvoikko adds. {#morphemes} decodes +STRUCTURE+.
   #
+  # @!attribute [r] word
+  #   @return [String] the word as passed to {Voikko#analyze}, in its case, frozen UTF-8; what
+  #     {#morphemes} cuts.
   # @!attribute [r] attributes
   #   @return [Hash{String => String}] libvoikko's attributes, keyed by its upper-case names.
-  Analysis = Data.define(:attributes)
+  Analysis = Data.define(:word, :attributes)
+
+  # One morpheme of {Analysis#word}, cut where libvoikko's +STRUCTURE+ starts a new one, from
+  # {Analysis#morphemes}:
+  #
+  #   voikko.analyze('tv-ohjelmassa').first.morphemes
+  #   #=> [#<data Voikko::Morpheme text="tv", standard_case="TV", hyphen_before=false, hyphen_after=true>,
+  #   #    #<data Voikko::Morpheme text="ohjelmassa", standard_case="ohjelmassa", hyphen_before=false, hyphen_after=false>]
+  #
+  # A hyphen belongs to the morpheme it follows, as libvoikko writes it (+-=+), so each character
+  # of the word lands in exactly one morpheme. +hyphen_before+ is therefore true only on the first
+  # morpheme of a word that starts with a hyphen (+-vuotias+). The word is the concatenation of
+  # each morpheme's +text+, a +-+ before it if +hyphen_before+ and after it if +hyphen_after+.
+  # A hyphen inside a morpheme stays in +text+, as does a colon (+YK:n+ is one morpheme).
+  #
+  # @!attribute [r] text
+  #   @return [String] the morpheme as written in the word, without its hyphens; frozen.
+  # @!attribute [r] standard_case
+  #   @return [String] +text+ in the case the reading's dictionary form spells it: +"Helsingissä"+
+  #     for +HELSINGISSÄ+; frozen.
+  # @!attribute [r] hyphen_before
+  #   @return [Boolean] whether a hyphen precedes the morpheme: only at the word's start.
+  # @!attribute [r] hyphen_after
+  #   @return [Boolean] whether a hyphen follows the morpheme.
+  Morpheme = Data.define(:text, :standard_case, :hyphen_before, :hyphen_after) do
+    alias_method :hyphen_before?, :hyphen_before
+    alias_method :hyphen_after?, :hyphen_after
+  end
 
   # Reopened rather than given as a +Data.define+ block: a constant inside that block would
   # land on {Voikko}.
@@ -76,35 +115,64 @@ class Voikko
     def [](key) = attributes[key]
 
     # @return [Hash{String => String}] the attributes themselves, not +Data+'s
-    #   +{attributes: {...}}+.
+    #   +{word: ..., attributes: {...}}+.
     def to_h = attributes
-  end
 
-  # The C functions, bound by the versioned soname: the bare +libvoikko.so+ ships only with
-  # +libvoikko-dev+. A missing library re-raises +LoadError+, so a caller that makes the gem
-  # optional still rescues it, with the packages to install appended.
-  module Lib
-    extend FFI::Library
+    # The word cut into its morphemes, decoded from +STRUCTURE+:
+    #
+    #   voikko.analyze('linja-autossa').first.morphemes.map(&:text)   #=> ["linja", "autossa"]
+    #   voikko.analyze('Wikipedia').first.morphemes.map(&:text)       #=> ["Wiki", "pedia"]
+    #
+    # Only a cut: no second analysis of each part, no case change. Not every morpheme boundary
+    # is marked: +yrityskirjautumisen+ is +yritys+ and +kirjautumisen+, the derivation
+    # unsplit. Upstream's format is in +R_structure_format+.
+    #
+    # @return [Array<Morpheme>, nil] the morphemes, or +nil+ when the backend gives no
+    #   +STRUCTURE+.
+    # @raise [Error] when +STRUCTURE+, its +=+ marks removed, is not one mark per character of
+    #   {#word}; libvoikko aims at that but only asserts it.
+    def morphemes
+      return unless structure
+      unless structure.delete('=').length == word.length
+        raise Error, "STRUCTURE #{structure.inspect} does not line up with #{word.inspect}"
+      end
 
-    begin
-      ffi_lib 'libvoikko.so.1'
-    rescue LoadError => e
-      raise LoadError, "#{e.message}\nlibvoikko is not installed: apt install libvoikko1 voikko-fi"
+      hyphen_before = structure.start_with?('-')
+      offset = hyphen_before ? 1 : 0
+      structure[offset..].split('=').reject(&:empty?).map do |marks|
+        text = word[offset, marks.length]
+        offset += marks.length
+        hyphen_after = marks.end_with?('-')
+        if hyphen_after
+          text = text.chop
+          marks = marks.chop
+        end
+        morpheme = Morpheme.new(text: text.freeze, standard_case: standard_case(text, marks),
+                                hyphen_before:, hyphen_after:)
+        hyphen_before = false
+        morpheme
+      end
     end
 
-    attach_function :voikkoGetVersion, [], :string
-    attach_function :voikkoInit, %i[pointer string string], :pointer
-    attach_function :voikkoTerminate, [:pointer], :void
-    attach_function :voikkoAnalyzeWordCstr, %i[pointer string], :pointer
-    attach_function :voikko_free_mor_analysis, [:pointer], :void
-    attach_function :voikko_mor_analysis_keys, [:pointer], :pointer
-    attach_function :voikko_mor_analysis_value_cstr, %i[pointer pointer], :pointer
-    attach_function :voikko_free_mor_analysis_value_cstr, [:pointer], :void
+    private
+
+    # +i+/+j+ mark a letter upper case in the dictionary form, +p+/+q+ lower case.
+    CASE_OF_MARK = { 'i' => :upcase, 'j' => :upcase, 'p' => :downcase, 'q' => :downcase }.freeze
+    private_constant :CASE_OF_MARK
+
+    def standard_case(text, marks)
+      text.each_char.zip(marks.each_char).map do |char, mark|
+        (change = CASE_OF_MARK[mark]) ? char.public_send(change) : char
+      end.join.freeze
+    end
   end
-  private_constant :Lib
 
   # @return [String] the system libvoikko's version: +"4.3.3"+.
-  def self.library_version = Lib.voikkoGetVersion
+  # @raise [LoadError] when libvoikko is not installed; the message names the packages.
+  def self.library_version
+    require_relative 'voikko/lib'
+    Lib.voikkoGetVersion
+  end
 
   # Opens a handle, yields it and closes it after the block, the way +File.open+ sits beside
   # +File.new+: the block form is where {#close} runs without the caller remembering it.
@@ -117,6 +185,7 @@ class Voikko
   # @yieldparam voikko [Voikko] the open handle.
   # @return [Object, Voikko] the block's value, or the open handle when no block is given.
   # @raise [TypeError] (see #initialize)
+  # @raise [LoadError] (see #initialize)
   # @raise [Error] (see #initialize)
   def self.open(language:, path: nil)
     voikko = new(language:, path:)
@@ -137,6 +206,7 @@ class Voikko
   #   ones; a directory that does not exist is ignored.
   # @raise [TypeError] when +language+ is not a String (+:fi+ is not), or +path+ neither a String
   #   nor +nil+.
+  # @raise [LoadError] when libvoikko is not installed; the message names the packages.
   # @raise [Error] when no installed dictionary serves +language+; the message names +voikko-fi+.
   def initialize(language:, path: nil)
     unless language.is_a?(String)
@@ -146,6 +216,7 @@ class Voikko
       raise TypeError, "path must be a String or nil, got #{path.inspect}"
     end
 
+    require_relative 'voikko/lib'
     error = FFI::MemoryPointer.new(:pointer)
     handle = Lib.voikkoInit(error, language, path)
     if handle.null?
@@ -156,8 +227,15 @@ class Voikko
     end
     @handle = FFI::AutoPointer.new(handle, Lib.method(:voikkoTerminate))
     @mutex = Mutex.new
+    @language = language.dup.freeze
   end
 
+  # The tag this handle was opened with, as passed: +'fi'+ and +'fi-FI'+ open the same
+  # dictionary but stay distinct here. Readable after {#close}.
+  #
+  # @return [String] frozen, e.g. +"fi"+.
+  attr_reader :language
+
   # Every reading libvoikko finds for +word+, in its order. Case is ignored, and one word often
   # has several readings:
   #
@@ -174,13 +252,13 @@ class Voikko
   #   word at, or cannot be read as UTF-8.
   # @raise [Error] when this handle is closed.
   def analyze(word)
-    word = utf8_word(word)
+    word = utf8_word(word).freeze
     with_handle do |handle|
       analyses = Lib.voikkoAnalyzeWordCstr(handle, word)
       next [] if analyses.null?
 
       begin
-        null_terminated(analyses).map { |analysis| Analysis.new(attributes_of(analysis)) }
+        null_terminated(analyses).map { |analysis| Analysis.new(word, attributes_of(analysis)) }
       ensure
         Lib.voikko_free_mor_analysis(analyses)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: voikko
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Martin Vysny
@@ -33,6 +33,7 @@ files:
 - LICENSE
 - README.md
 - lib/voikko.rb
+- lib/voikko/lib.rb
 - lib/voikko/version.rb
 homepage: https://github.com/mvysny/ruby-voikko
 licenses: