#!/bin/env python

"""Basic linguistic hirearchy

This module illustrates how a simple model for English words can be
represented as a Python class hirearchy.

All words have a base form.  Nouns and verbs are kinds of words.
Nouns and verbs have different sets of inflected forms: nouns
distinguish between singular and plural; verb distinguish between
present and past tense.

This module captures these basic distinctions by making Noun and Verb
both subclasses of Word which add relevant attributes.  Inflected
forms are spelled out with the __str__ stringification function.  The
__repr__ stringification function gives output more suited for
debugging purposes.
"""


class Word(object):
    """An English word

    Words have base forms, e.g. what you would look up in a
    dictionary.
    """
    def __init__(self, base):
        """Constructor

        >>> w = words.Word('dog')
        """
        self.base = base

    def __repr__(self):
        """Interactive mode stringification

        >>> w = words.Word('dog')
        >>> w
        <Word dog>
        """
        # self.__class__.__name__ is a property of any object that
        # contains the name of the class, e.g. "Word".
        return "<%s %s>" % (self.__class__.__name__, self.base)

    def __str__(self):
        """Verbose stringification
        
        For words print the base form

        >>> w = words.Word('dog')
        >>> print w
        dog
        """
        return self.base


class Noun(Word):
    """An English noun

    A Noun is a kind of Word that makes a distinction between singular
    and plural forms.
    """
    # SG and PL are class instance variables.  They are accessible as
    # Noun.SG and Noun.PL (or self.SG and self.PL if self contains an
    # instance of the Noun class).
    #
    # Class instance variables are often used to Python to give names
    # to constant values.  By convention, they are written in
    # UPPERCASE.
    SG = 0
    PL = 1
    
    def __init__(self, base, number):
        """Constructor

        >>> n = words.Noun('boy', words.Noun.PL)
        """
        # This line calls the __init__ function of the parent class of
        # Noun using the instance variable stored in self.
        super(Noun, self).__init__(base)
        # After we've used the parent class' constructor to do generic
        # Word initialization, we initialize the attributes specific
        # to nouns.
        self.number = number

    def __repr__(self):
        """Interactive mode stringification

        >>> n = words.Noun('boy', words.Noun.PL)
        >>> n
        <Noun boy plural>
        """
        # self.__class__.__name__ is a property of any object that
        # contains the name of the class, e.g. "Noun".
        if self.number == self.SG:
            n = "singular"
        else:
            n = "plural"
        return "<%s %s %s>" % (self.__class__.__name__, self.base, n)

    def __str__(self):
        """Stringification

        If the noun is plural, add an -s to the base form.

        >>> n = words.Noun('boy', words.Noun.PL)
        >>> print n
        boys
        """
        if self.number == self.PL:
            return self.base + 's'
        else:
            return self.base


class Verb(Word):
    """An English verb

    A Verb is a kind of Word that makes a distinction between present
    and past tense forms.
    """

    # PRES and PAST are class instance variables specific to the Verb
    # class.
    #
    # Note that the actual 0 and 1 values are arbitrary.  We just need
    # something so that Verb.PRES != Verb.PAST.
    PRES = 0
    PAST = 1
    
    def __init__(self, base, tense):
        """Constructor

        >>> v = words.Verb('faint', words.Verb.PAST)
        """
        # This line calls the __init__ function of the parent class of
        # Verb using the instance variable stored in self.
        super(Verb, self).__init__(base)
        # After we've used the parent class' constructor to do generic
        # Word initialization, we initialize the attributes specific
        # to verbs.
        self.tense = tense

    def __repr__(self):
        """Interactive mode stringification

        >>> v = words.Verb('faint', words.Verb.PAST)
        >>> v
        <Verb faint past>
        """
        # self.__class__.__name__ is a property of any object that
        # contains the name of the class, e.g. "Verb".
        if self.tense == self.PRES:
            t = "present"
        else:
            t = "past"
        return "<%s %s %s>" % (self.__class__.__name__, self.base, t)

    def __str__(self):
        """Verbose stringification

        If the verb is in the past tense, add an -ed to the base form.

        >>> v = words.Verb('faint', words.Verb.PAST)
        >>> print v
        fainted
        """
        if self.tense == self.PAST:
            return self.base + 'ed'
        else:
            return self.base


if __name__ == '__main__':
    # Singular noun boy
    boy_sg = Noun('boy', Noun.SG)
    print "Base form: %s, Inflected form: %s" % (boy_sg.base, boy_sg)

    # Plural noun boy
    boy_pl = Noun('boy', Noun.PL)
    print "Base form: %s, Inflected form: %s" % (boy_pl.base, boy_pl)

    # Present tense verb faint
    faint_pres = Verb('faint', Verb.PRES)
    print "Base form: %s, Inflected form: %s" % (faint_pres.base, faint_pres)

    # Past tense verb faint
    faint_past = Verb('faint', Verb.PAST)
    print "Base form: %s,  Inflected form: %s" % (faint_past.base, faint_past)