Class: FFI::Aspell::Speller

Inherits:
Object
  • Object
show all
Defined in:
lib/ffi/aspell/speller.rb

Overview

The Speller class is used for spell checking individual words as well as generating a list of suggestions.

Usage

First you'll have to create a new instance:

speller = FFI::Aspell::Speller.new

When creating a new instance you can specify the language as well as a set of arbitrary Aspell options (e.g. the personal wordlist file). The language can be set in the first parameter, other options are set as a hash in the second parameter:

speller = FFI::Aspell::Speller.new('nl', :personal => 'aspell.nl.pws')

Unlike Raspell the keys of the hash used for additional options can be both strings and symbols.

Once an instance has been created you can change the options, check the spelling of a word or retrieve a list of suggestions.

Options

There are four methods for dealing with Aspell options:

There are also two extra methods which can be used to set the suggestion mode, both these methods are simply shortcuts and use the #set() method for actually setting the values:

speller.suggestion_mode = 'fast'

if speller.suggestion_mode == 'fast'
  # ...
end

Setting an option:

speller.set('lang', 'en_US')

Retrieving an option:

speller.get('lang')

Resetting an option:

speller.reset('lang')

Checking a Word

Checking the spelling of a word is done using #correct?. This method takes a string containing the word to verify and returns true if the word is spelled correctly and false otherwise:

speller.correct?('cookie') # => true
speller.correct?('cookei') # => false

Suggestions

Suggestions can be generated using suggestions. This method returns an array containing all the possible suggestions based on the suggestion mode that is being used:

speller.suggestions('cookei') # => ["cookie", ...]

Cleaning up

When you're finished with the Speller object, you can let the finalizer automatically free resources, otherwise, call #close to explicitly free the underlying resources:

speller = FFI::Aspell::Speller.new
speller.correct?('cookie') # => true
speller.close

Alternatively, you can use the block form of Speller.open to automatically free the resources:

FFI::Aspell::Speller.open do |speller|
  puts speller.correct?('cookie') # => prints "true"
end

Speller.open takes the same parameters as Speller.new.

For more information see the documentation of the individual methods in this class.

Constant Summary collapse

SUGGESTION_MODES =

Array containing the possible suggestion modes to use.

Returns:

  • (Array) 
['ultra', 'fast', 'normal', 'bad-spellers']

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(language = nil, options = {}) ⇒ Speller

Creates a new instance of the class, sets the language as well as the options specified in the options hash.

Parameters:

  • language (String) (defaults to: nil) —

    The language to use.

  • options (Hash) (defaults to: {}) —

    A hash containing extra configuration options, such as the "personal" option to set.



155
156
157
158
159
160
161
162
163
 
# File 'lib/ffi/aspell/speller.rb', line 155

def initialize(language = nil, options = {})
  @config = Aspell.config_new

  options['lang'] = language if language

  options.each { |k, v| set(k, v) }

  update_speller
end

Class Method Details

.finalizer(config, speller) ⇒ Proc

Returns a proc for a finalizer, used for cleaning up native resources.

Parameters:

  • config (FFI::Pointer)
  • speller (FFI::Pointer)

Returns:

  • (Proc) 


139
140
141
142
143
144
 
# File 'lib/ffi/aspell/speller.rb', line 139

def self.finalizer(config, speller)
  return proc {
    Aspell.config_delete(config)
    Aspell.speller_delete(speller)
  }
end

.open(*args) {|speller| ... } ⇒ Speller

Creates a new instance of the class. If a block is given, the instance is yielded and automatically closed when exiting the block.

Yields:

  • If a block is given, the speller instance is yielded.

Yield Parameters:

  • speller (Speller) —

    The created speller. #close is automatically called when exiting the block.

Returns:

See Also:

  • [[#initialize]


118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/ffi/aspell/speller.rb', line 118

def self.open(*args)
  speller = self.new(*args)

  if block_given?
    begin
      yield speller
    ensure
      speller.close
    end
  end

  return speller
end

Instance Method Details

#check_closed ⇒ nil (private)

Raises error if speller is closed.

Returns:

  • (nil)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



396
397
398
399
400
 
# File 'lib/ffi/aspell/speller.rb', line 396

def check_closed
  if closed?
    raise(RuntimeError, 'This Speller object has already been closed')
  end
end

#close ⇒ Object

Closes the speller and frees underlying resources. Calling this is not absolutely required as the resources will eventually be freed by the finalizer.

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/ffi/aspell/speller.rb', line 172

def close
  check_closed

  # Remove finalizer since we're manually freeing resources.
  ObjectSpace.undefine_finalizer(self)

  Aspell.config_delete(@config)

  @config = nil

  Aspell.speller_delete(@speller)

  @speller = nil
end

#closed? ⇒ TrueClass|FalseClass

Checks if the speller is closed or not.

Returns:

  • (TrueClass|FalseClass) 


192
193
194
 
# File 'lib/ffi/aspell/speller.rb', line 192

def closed?
  return @config.nil?
end

#correct?(word) ⇒ TrueClass|FalseClass

Checks if the given word is correct or not.

Parameters:

  • word (String) —

    The word to check.

Returns:

  • (TrueClass|FalseClass)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ffi/aspell/speller.rb', line 203

def correct?(word)
  check_closed

  unless word.is_a?(String)
    raise(TypeError, "Expected String but got #{word.class} instead")
  end

  correct = Aspell.speller_check(
    @speller,
    handle_input(word.to_s),
    word.bytesize
  )

  return correct
end

#get(key) ⇒ String

Retrieves the value of the specified configuration item.

Parameters:

  • key (#to_s) —

    The configuration key to retrieve.

Returns:

  • (String)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.

  • (FFI::Aspell::ConfigError) —

    Raised when the configuration item does not exist.



308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/ffi/aspell/speller.rb', line 308

def get(key)
  check_closed

  value = Aspell.config_retrieve(@config, key.to_s)

  if value
    return value
  else
    raise(ConfigError, "The configuration item #{key} does not exist")
  end
end

#get_default(key) ⇒ String

Retrieves the default value for the given configuration key.

Parameters:

  • key (#to_s) —

    The name of the configuration key.

Returns:

  • (String)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.

  • (FFI::Aspell::ConfigError) —

    Raised when the configuration item does not exist.



329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/ffi/aspell/speller.rb', line 329

def get_default(key)
  check_closed

  value = Aspell.config_retrieve_default(@config, key.to_s)

  if value
    return value
  else
    raise(ConfigError, "The configuration item #{key} does not exist")
  end
end

#handle_input(word) ⇒ String (private)

Converts word to encoding expected in aspell from current ruby encoding

Parameters:

  • word (String) —

    The word to convert

Returns:

  • (String) —

    word



372
373
374
375
376
 
# File 'lib/ffi/aspell/speller.rb', line 372

def handle_input(word)
  enc = get('encoding')

  return word.encode(enc)
end

#handle_output(word) ⇒ String (private)

Converts word from aspell encoding to what ruby expects

Parameters:

  • word (String) —

    The word to convert

Returns:

  • (String) —

    word



384
385
386
387
388
 
# File 'lib/ffi/aspell/speller.rb', line 384

def handle_output(word)
  enc = get('encoding')

  return word.force_encoding(enc).encode
end

#reset(key) ⇒ Object

Resets a configuration item to its default value.

Parameters:

  • key (#to_s) —

    The name of the configuration item to reset.

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.

  • (FFI::Aspell::ConfigError) —

    Raised when the configuration item could not be reset.



349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/ffi/aspell/speller.rb', line 349

def reset(key)
  check_closed

  unless Aspell.config_remove(@config, key.to_s)
    raise(
      ConfigError,
      "The configuration item #{key} could not be reset, most likely " \
        "it doesn't exist"
    )
  end

  update_speller
end

#set(key, value) ⇒ Object

Sets a configuration option.

Parameters:

  • key (#to_s) —

    The configuration key to set.

  • value (#to_s) —

    The value of the configuration key.

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.

  • (FFI::Aspell::ConfigError) —

    Raised when the configuration value could not be set or when an incorrect suggestion mode was given.



285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/ffi/aspell/speller.rb', line 285

def set(key, value)
  check_closed

  if key == 'sug-mode' and !SUGGESTION_MODES.include?(value)
    raise(ConfigError, "The suggestion mode #{value} is invalid")
  end

  unless Aspell.config_replace(@config, key.to_s, value.to_s)
    raise(ConfigError, "Failed to set the configuration item #{key}")
  end

  update_speller
end

#suggestion_mode ⇒ String

Returns the suggestion mode that's currently used.

Returns:

  • (String)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



270
271
272
273
274
 
# File 'lib/ffi/aspell/speller.rb', line 270

def suggestion_mode
  check_closed

  return get('sug-mode')
end

#suggestion_mode=(mode) ⇒ Object

Sets the suggestion mode for #suggestions.

Parameters:

  • mode (String) —

    The suggestion mode to use.

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



258
259
260
261
262
 
# File 'lib/ffi/aspell/speller.rb', line 258

def suggestion_mode=(mode)
  check_closed

  set('sug-mode', mode)
end

#suggestions(word) ⇒ Array

Returns an array containing words suggested as an alternative to the specified word.

Parameters:

  • word (String) —

    The word for which to generate a suggestion list.

Returns:

  • (Array)

Raises:

  • (RuntimeError) —

    Raised if the speller is closed.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/ffi/aspell/speller.rb', line 227

def suggestions(word)
  check_closed

  unless word.is_a?(String)
    raise(TypeError, "Expected String but got #{word.class} instead")
  end

  list = Aspell.speller_suggest(
    @speller,
    handle_input(word),
    word.bytesize
  )

  suggestions = []
  elements    = Aspell.word_list_elements(list)

  while word = Aspell.string_enumeration_next(elements)
    suggestions << handle_output(word)
  end

  Aspell.string_enumeration_delete(elements)

  return suggestions
end

#update_speller ⇒ Object (private)

Updates the internal speller object to use the current config.



405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/ffi/aspell/speller.rb', line 405

def update_speller
  ObjectSpace.undefine_finalizer(self)

  Aspell.speller_delete(@speller)

  @speller = Aspell.speller_new(@config)

  ObjectSpace.define_finalizer(
    self,
    self.class.finalizer(@config, @speller)
  )
end