/ 
Lingua-Generic-Interface-v0.01
/ Lingua::Generic::Interface::Word

NAME

Lingua::Generic::Interface::Word - module to interact with the words of any language

VERSION

version v0.01

SYNOPSIS

use parent 'Lingua::Generic::Interface::Word';

my Lingua::Generic::Interface::Word $word = Lingua::XXX::Word->new(string => 'mi');

say $word->as_string;

This module implements a generic interface to language specific implementations of a word object.

This module provides a base implementation for some of it's required methods. Methods which this module cannot provide a useful default implementation for will have an implementation that dies on call.

This module inherits from Data::Identifier::Interface::Simple, and Data::Identifier::Interface::Subobjects.

Package may also want to implement Data::Identifier::Interface::Known.

METHODS

new

my Lingua::Generic::Interface::Word $word = Lingua::XXX::Word->new($type => $value);
# e.g.:
my Lingua::Generic::Interface::Word $word = Lingua::XXX::Word->new(string => 'mi');

(since v0.01)

Constructs a new word. The word is normalised as part of this. This method deduplicate instances.

Currently the following types ($type) are defined:

from

(since v0.01)

Constructs a word from an object. $value should be a reference to an object from which the word is constructed. Which exact objects a word can be constructed from depends on the implementation.

If $value is not a reference the value is parsed as per string if it looks like a word string (experimental since v0.01).

ise

(since v0.01)

Constructs a word from a ISE (such as returned by "ise" in Data::Identifier::Interface::Simple).

string

(since v0.01)

Constructs a word from it's string representation.

Default implementation

The default implementation will return $value if from is used and the passed object is already an instance of this package. For string it will create a new object that will work with the rest of the default implementation. Such object will be a blessed hash reference with the string set in a key string.

It will fail in all other cases.

as_string

my $str = $word->as_string;

(since v0.01)

Returns the string representation of the word.

Default implementation

The default implementation will return the string value from the key string.

eq

my $bool = $word->eq($other); # $word must be non-undef
# or:
my $bool = Lingua::Generic::Interface::Word::eq($word, $other); # $word can be undef

(since v0.01)

Compares two words to be equal.

If both words are undef they are considered equal.

If $word or $other is not an instance of Lingua::Generic::Interface::Word or undef "new" with the type from is used.

The operators "eq" in perlop and "ne" in perlop are overloaded to this method.

Default implementation

The default implementation will force both sides to be a Lingua::Generic::Interface::Word. After that it will compare the actual packages, and then the string values as per "as_string".

cmp

my $val = $word->cmp($other); # $word must be non-undef
# or:
my $val = Lingua::Generic::Interface::Word::cmp($word, $other); # $word can be undef

(experimental since v0.01)

Compares the words similar to cmp. This method can be used to order words. To check for them to be equal see "eq".

The parameters are parsed the same way as "eq".

The operator "cmp" in perlop is overloaded to this method.

If this method is used for sorting the exact resulting order is not defined. However:

  • The order is stable

  • The order is the same for $a->cmp($b) as for - $b->cmp($a).

Default implementation

The default implementation will force both sides to be a Lingua::Generic::Interface::Word. After that it will compare the actual packages, and then the string values as per "as_string".

natural_language

my Data::Identifier $natural_language = $word->natural_language;

(since v0.01)

Returns the natural language this word is in. When no parameters are passed an instance of Data::Identifier must be returned.

The implementation must die if any parameters are passed.

Default implementation

The default implementation dies.

displayname

my $displayname = $word->displayname;

(since v0.01)

This method returns a string suitable to display to the user.

This is the same as "displayname" in Data::Identifier::Interface::Simple.

Default implementation

The default implementation is compatible with "displayname" in Data::Identifier::Interface::Simple. It will make use of "as_string" as good as possible, then fall back to calling "as" asking for a Data::Identifier to handle the request.

ise

my $ise = $word->ise(...)

(since v0.01)

This is the same as "ise" in Data::Identifier::Interface::Simple.

If an implementations implement this method or "as" in Data::Identifier::Interface::Simple as their primary method to create Data::Identifier objects this method might be overridden by the default implementation from Data::Identifier::Interface::Simple such as by:

sub ise { goto &Data::Identifier::Interface::Simple::ise } # overridden using tail-call

Default implementation

The default implementation will die.

register

$word->register;

(experimental since v0.01)

This should be implemented by packages that support registering words. A registered word object is kept alive indefinitely and may be used for deduplication. This is specifically useful when splitting texts into word objects, so common words do not get created over and over again.

This method returns the passed word (so it can be used in chain calls). This method must also be suitable to be used with use constant, see constant for details.

It is undefined if this method will also register related objects (such as the word's stem, modifiers, or related Data::Identifier objects).

Default implementation

Unimplemented. Future versions may provide a default implementation.

AUTHOR

Philipp Schafft <lion@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Philipp Schafft <lion@cpan.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)