NAME

Lingua::Phonology::Features - a module to handle a set of hierarchical features.

SYNOPSIS

	use Lingua::Phonology;

	my $phono = new Lingua::Phonology;
	my $features = $phono->features;

    # Add features programmatically
    $features->add_feature(
        Node =>      { type => 'privative', children => ['Scalar', 'Binary', 'Privative'] },
        Scalar =>    { type => 'scalar' },
        Binary =>    { type => 'binary' },
        Privative => { type => 'privative' }
    );

    # Drop features
    $features->drop_feature('Privative');

    # Load feature definitions from a file
	$features->loadfile('phono.xml');

    # Load default features
    $features->loadfile;

DESCRIPTION

Lingua::Phonology::Features allows you to create a hierarchy of features of various types, and includes methods for adding and deleting features and changing the relationships between them.

By "heirarchical features" we mean that some features dominate some other features, as in a tree. By having heirarchical features, it becomes possible to set multiple features at once by assigning to a node, and to indicate conceptually related features that are combined under the same node. This module, however, does not instantiate values of features, but only establishes the relationships between features.

Lingua::Phonology::Features recognizes multiple types of features. Features may be privative (which means that their legal values are either true or undef), binary (which means they may be true, false, or undef), or scalar (which means that their legal value may be anything). You can freely mix different kinds of features into the same set of features.

Finally, while this module provides a full set of methods to add and delete features programmatically, it also provides the option of reading feature definitions from a file. This is usually faster and more convenient. The method to do this is "loadfile". Lingua::Phonology::Features also comes with an extensive default feature set.

METHODS

new

my $features = Lingua::Phonology::Features->new();

This method creates and returns a new Features object. It takes no arguments.

add_feature

Adds a new feature to the current list of features. Accepts a list of arguments of the form "feature_name => { ... }", where the value assigned to each feature name must be a hash reference with one or more of the following keys:

type

The type must be one of 'privative', 'binary', 'scalar', or 'node'. The feature created is of the type specified. This key must be defined for all features. As of version 0.3, the 'node' type is deprecated, and is considered synonymous with 'privative'.
child

The value for this key is a reference to an array of feature names. The features named will be assigned as the children of the feature being defined. Note that any type of feature may have children, and children may be of any type. (This is new in version 0.3.)
parent

The inverse of child. The value for this key must be a reference to an array of feature names that are assigned as the parents of the feature being added.

Note that the features named in parent or child must already be defined when the new feature is added. Thus, trying to add parents and children as part of the same call to add_feature() will almost certainly result in errors.

This method return true on success and false if any error occurred.

Example:

	$features->add_feature(
        anterior => { type => 'binary' },
        distributed => { type => 'binary' }
    );
	$features->add_feature( 
        Coronal => { type => 'privative', child => ['anterior', 'distributed']}
    );

Note that if you attempt to add a feature that already exists, the preexisting feature will be dropped before the new feature is added.

WARNING: The features SYLL, Rime, onset, nucleus, coda, SON are used by Lingua::Phonology::Syllable. They may be defined as part of a user feature set if you insist, but their original definitions may be overwritten, since Lingua::Phonology::Syllable will forcibly redefine those features when it is used. You have been warned.

feature

my $feature = $features->feature('name');

Given the name of a feature, returns a hash reference showing the current settings for that feature. The hash reference will at least contain the key type, naming the feature type, and may contain the keys child and/or parent if the feature has some children or parents. If you ask for a feature that doesn't exist, this method will return undef and emit a warning.

feature_exists

my $bool = $features->feature_exists('name');

Given the name of the feature, returns a simple truth value indicating whether or not any such feature with that name currently exists. Unlike feature(), this method never gives an error, and does not return the feature reference on success. This can be used by programs that want to quickly check for the existence of a feature without printing warnings.

all_features

my %features = $features->all_features();

Takes no arguments. Returns a hash with feature names as its keys, and the parameters for those features as its values. The values will be hash references the same as those returned from feature();

drop_feature

$features->drop_feature('name');
$features->drop_feature(@names);

Given one or more feature names, deletes the given feature(s) from the current list of features. Note that deleting a feature does not cause its children to be deleted--it just causes them to revert to being undominated. This method returns true on success, otherwise false with an error.

change_feature

This method works identically to add_feature(), but it first checks to see that the feature being changed already exists. If it doesn't, it will give an error. If there are no errors, the method returns true.

The add_feature() method can also be used to change existing features. Using change_feature(), however, allows you to modify an existing feature without losing existing settings for that feature. For example, consider the following:

$features->add_feature(foo => { type => 'privative', child => ['bar', 'baz'] });
$features->change_feature(foo => { type => 'scalar' });
# foo is still the parent of bar and baz

If add_feature() had been used in place of change_feature(), foo would not be the parent of anything, because the original settings for its children would have been lost.

children

my @children = $features->children('name');

Takes one argument, the name of a feature. Returns a list of all of the features that are children of the feature given.

add_child

$features->add_child('parent', 'child');
$features->add_child('parent', @children);

Takes two or more arguments. The first argument to this method should be the name of a feature. The remaining arguments are the names of features to be assigned as children to the first feature. If all children are added without errors, this function returns true, otherwise false with a warning.

drop_child

$features->drop_child('parent', 'child');
$features->drop_child('parent', @children);

Like add_child, the first argument to this function should be the name of a feature, and the remaining arguments are the names of children of that feature. The child features so named will be deleted from the list of children for that node. This function returns true on success, false w/ a warning on any error.

parents

my @parents = $features->parents('name');

Takes one argument, the name of a feature. Returns a list of the current parent features of that feature.

add_parent

$features->add_parent('child', 'parent');
$features->add_parent('child', @parents);

Takes two or more arguments. The first argument is the name of a feature, and the remaining arguments are the names of features that should be parents of that feature. Returns true if all of the attempted operations succeeded, otherwise returns false.

drop_parent

$features->drop_parent('child', 'parent');
$features->drop_parent('child', @parents);

Takes two or more arguments. The first is a feature name, and the remaining arguments are the names of features that are currently parents of that feature. Those features will cease to be parents of the first feature. Returns true on success, false on error.

type

# Get a feature type
$features->type('name');
# Set a feature's type to 'binary', for example
$features->type('name', 'binary');

Takes one or two arguments. The first argument must be the name of a feature. If there is only one argument, the type for that feature is return. If there are two arguments, the type is set to the second argument and returned.

loadfile

# Load defaults
$features->loadfile();

# Load from a file
$features->loadfile('phono.xml');

Takes one argument, the path and name of a file. Reads the lines of the file and adds all of the features defined therein. The file should be an XML file following the format described in Lingua::Phonology::FileFormatPOD. Consult that module if you need to write an appropriate file by hand.

You can also call this method with no arguments, in which case the default feature set is loaded. The default set is described in "THE DEFAULT FEATURE SET".

If this method is unable to parse its input as an XML file, it will then pass the file off to old_loadfile(), where it will attempt to parse the the file according to the old, deprecated file format. If you have an existing script that loads a file in the old file format with loadfile(), there's nothing that needs to be done immediately since the file will still be parsed correctly. However, you will get warnings telling you that the format you're using is deprecated.

old_loadfile

$features->old_loadfile('filename');

Loads a file in the old (pre-version 0.2) and currently deprecated file format. This format is described below.

Feature definition lines should be in this format:

feature_name   [1 or more tabs]   type   [1 or more tabs]   children (separated by spaces)

You can order your features any way you want in the file. The method will take care of ensuring that parents are defined before their children are added and make sure no conflicts result.

Lines beginning with a '#' are assumed to be comments and are skipped.

This method does NOT load the default features any more. Only loadfile() does that.

graph

my $g = $features->graph();

Takes no arguments. Returns an object in the Graph class indicating the structure of the current Lingua::Phonology::Features object. You may use this graph for printing or other analysis, if you'd like.

You must have the Graph module installed for this function to work. If you do not have Graph installed, you will get an error.

number_form

my $num = $features->number_form('name', $text);

Takes two arguments. The first argument is the name of a feature, and the second is a value to be converted into the appropriate numeric format for that feature. This function is provided for convenience, to allow Lingua::Phonology to convert between common textual linguistic notation and its internal numeric representation.

The conversion from input value to numeric value depends on what type of feature the feature given in the first argument is. A few general text conventions are recognized to make text parsing easier and to ensure that number_form and "text_form" can be used as inverses of each other. The conversions are as follows:

privatives

The string '*' is recognized as a synonym for undef in all circumstances. It always returns undef.
privative features return 1 if given any true true value (other than '*'), otherwise undef.
binary features return 1 in the case of a true value, 0 in case of a defined false value, and otherwise undef. The string '+' is a synonym for 1, and '-' is a synonym for 0. Thus, the following two lines both return 0:
```
print $features->number_form('binary_feature', 0); # prints 0
print $features->number_form('binary_feature', '-'); # prints 0
```
Note, however, if the feature given is a privative feature, the first returns undef and the second returns 1.
scalar features return the value that they're given unchanged (unless that value is '*', which is translated to undef).

text_form

my $text = $features->text_form('name', $number);

This function is the inverse of number_form. It takes two arguments, a feature name and a numeric value, and returns a text equivalent for the numeric value given. The exact translation depends on the type of the feature given in the first argument. The translations are:

Any undefined value or the string '*' returns '*'.
privative features return '*' for undef or logically false values, otherwise '' (an empty string).
binary features return '+' if true, '-' if false or equal to '-', and '*' if undefined.
scalar features return their values unchanged, except if they're undefined, in which case they return '*'.

THE DEFAULT FEATURE SET

If you call the method "loadfile" without any arguments, like this:

$features->loadfile

then the default feature set is loaded. The default feature set is a feature geometry tree based on Clements and Hume (1995), with some modifications. This set gratuitously mixes privative, binary, and scalar features, and may or may not be actually useful to you.

Within this feature set, we use the convention of putting top-level (undominated) nodes in ALL CAPS, putting intermediate nodes in Initial Caps, and putting terminal features in lowercase. The following shows the feature tree created, with the types of each feature in parenthesis:

	# True features
	ROOT (privative)
	 |
	 +-sonorant (privative)
	 +-approximant (privative)
	 +-vocoid (privative)
	 +-nasal (privative)
	 +-lateral (privative)
	 +-continuant (binary)
	 +-Laryngeal
	 |  |
	 |  +-spread (privative)
	 |  +-constricted (privative)
	 |  +-voice (privative)
	 |  +-ATR (binary)
	 |
	 +-Place
	    |
	    +-pharyngeal (privative)
		+-Oral
		   |
		   +-labial (privative)
		   +-Lingual
		   |  |
		   |  +-dorsal (privative)
		   |  +-Coronal
		   |     |
		   |     +-anterior (binary)
		   |     +-distributed (binary)
		   |
		   +-Vocalic
		      |
		      +-aperture (scalar)
			  +-tense (privative)
			  +-Vplace
			     |
			     +-labial (same as above)
				 +-Lingual (same as above)
	
	# Features dealing with syllable structure
	SYLL (privative)
     |
     +-onset (privative)
     +-Rime (privative)
        |
        +-nucleus (privative)
        +-coda (privative)
    SON (scalar)

This feature set is created from the following XML file, which can be treated as an example for creating your own feature sets.

<phonology>
  <features>

    <!-- True Features -->

    <feature name="ROOT" type="privative">
      <child name="sonorant" />
      <child name="approximant" />
      <child name="vocoid" />
      <child name="nasal" />
      <child name="lateral" />
      <child name="continuant" />
      <child name="Laryngeal" />
      <child name="Place" />
    </feature>
    <feature name="sonorant" type="privative" />
    <feature name="approximant" type="privative" />
    <feature name="vocoid" type="privative" />
    <feature name="nasal" type="privative" />
    <feature name="lateral" type="privative" />
    <feature name="continuant" type="binary" />

    <feature name="Laryngeal" type="privative">
      <child name="spread" />
      <child name="constricted" />
      <child name="voice" />
      <child name="ATR" />
    </feature>
    <feature name="spread" type="privative" />
    <feature name="constricted" type="privative" />
    <feature name="voice" type="privative" />
    <feature name="ATR" type="binary" />

    <feature name="Place" type="privative">
      <child name="pharyngeal" />
      <child name="Oral" />
    </feature>
    <feature name="pharyngeal" type="privative" />

    <feature name="Oral" type="privative">
      <child name="labial" />
      <child name="Lingual" />
      <child name="Vocalic" />
    </feature>
    <feature name="labial" type="privative" />

    <feature name="Lingual" type="privative">
      <child name="Coronal" />
      <child name="dorsal" />
    </feature>
    <feature name="dorsal" type="privative" />

    <feature name="Coronal" type="privative">
      <child name="anterior" />
      <child name="distributed" />
    </feature>
    <feature name="anterior" type="binary" />
    <feature name="distributed" type="binary" />

    <feature name="Vocalic" type="privative">
      <child name="Vplace" />
      <child name="aperture" />
      <child name="tense" />
    </feature>
    <feature name="aperture" type="scalar" />
    <feature name="tense" type="binary" />

    <feature name="Vplace" type="privative">
      <child name="labial" />
      <child name="Lingual" />
    </feature>

    <!-- Syllabification Features -->

    <feature name="SYLL" type="scalar">
      <child name="onset" />
      <child name="Rime" />
    </feature>

    <feature name="onset" type="privative" />
    <feature name="Rime" type="privative">
      <child name="nucleus" />
      <child name="coda" />
    </feature>
    <feature name="nucleus" type="privative" />
    <feature name="coda" type="privative" />

    <feature name="SON" type="scalar" />

  </features>
</phonology>

TO DO

Improve the default feature set. As it is, it cannot handle uvulars or pharyngeals, and has some quirks in its relationships that lead to strange results. Though some of this is the fault of phonologists who can't make up their minds about how things are supposed to go together.

REFERENCES

Clements, G.N and E. Hume. "The Internal Organization of Speech Sounds." Handbook of Phonological Theory. Ed. John A. Goldsmith. Cambridge, Massachusetts: Blackwell, 2001. 245-306.

This article is a terrific introduction to the concept of feature geometry, and also describes ways to write rules in a feature-geometric system.

AUTHOR

Jesse S. Bangs <jaspax@cpan.org>

LICENSE

This module is free software. You can distribute and/or modify it under the same terms as Perl itself.

To install Lingua::Phonology, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Lingua::Phonology

CPAN shell

perl -MCPAN -e shell
install Lingua::Phonology

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)