#! /usr/bin/env python
"""Encapsulate verses from the Bible and support quizzing over them.

The Verse class in this module is far superior to the one implemented in
Java. All quizzing/testing capabilities are imported from another module."""

################################################################################

__author__ = 'Stephen "Zero" Chappell <Noctis.Skytower@gmail.com>'
__date__ = '11 February 2010'
__version__ = '$Revision: 3 $'

################################################################################

import manager
import timeout
import compare

################################################################################

class Verse:

    """Give a helpful interface to the reference and text of a verse.

    The Verse class initially came from TestVerse, written in Java and
    ported into Python. The verse-checking implementation was extremely
    naive and has been reimplemented in another module for this version."""

    __manager = False

    @classmethod
    def init_manager(cls, sleep_interval):
        """Initialize an optional verse-checking management system.

        If a verse is checked with a positive timeout argument, then the
        entry is checked with a timeout. Execution is only guaranteed to
        terminate as the "ready" property is regularly polled. A manager
        initialized here can ensure termination regardless of the client."""
        # This is an optional system. It ensures that timeouts are called.
        # SessionManager(s) cannot be killed, so this is a one-way choice.
        assert not cls.__manager, 'Verse manager is already initialized!'
        cls.__timeout = manager.SessionManager(sleep_interval)
        cls.__timeout.daemon = True
        cls.__timeout.start()
        cls.__manager = True

################################################################################

    def __init__(self, addr, text):
        """Initialize the reference and text of a Verse instance."""
        self.__addr = addr
        self.__text = text
        self.__search = timeout.add_timeout(compare.search)

    def check(self, entry, limit=0, ident=''):
        """Check the entry against the verse's official text.

        Calls with a non-positive limit are blocking in nature. Those with
        a limit greater than zero are started asynchronously and run in a
        separate process. If a timeout manager is running, a cancellation
        method is registered using an IP address and the verse reference."""
        if limit <= 0:
            return compare.search(self.__text, entry)
        # We are working with a timeout call.
        self.__search = timeout.add_timeout(compare.search, limit)
        self.__search(self.__text, entry)
        if Verse.__manager:
            # The verse manager timeout system should be used.
            with Verse.__timeout:
                session = manager.Session(limit + 1, self.__search.cancel)
                Verse.__timeout[ident + ' -> ' + self.__addr] = session

################################################################################

    @property
    def addr(self):
        """Read-only address or reference property."""
        return self.__addr

    @property
    def text(self):
        """Read-only text (from the verse) property."""
        return self.__text

    @property
    def hint(self):
        """Read-only property that computes the hint."""
        return compare.empty_master(self.__text)

    @property
    def ready(self):
        """Read-only status property for a verse check."""
        return self.__search.ready

    @property
    def value(self):
        """Read-only return property for a verse check."""
        return self.__search.value