# Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import keyword
import logging
import re

import task_loop
import wardmodem_exceptions as wme

class StateMachine(object):
    """
    Base class for all state machines in wardmodem.

    All derived objects bundled as part of wardmodem
        (1) Reside in state_machines/
        (2) Have their own module e.g., my_module
        (3) The main state machine class in my_module is called MyModule.

    """

    def __init__(self, state, transceiver, modem_conf):
        """
        @param state: The GlobalState object shared by all state machines.

        @param transceiver: The ATTransceiver object to interact with.

        @param modem_conf: A modem configuration object that contains
                configuration data for different state machines.

        @raises: SetupException if we attempt to create an instance of a machine
        that has not been completely specified (see get_well_known_name).

        """
        self._state = state
        self._transceiver = transceiver
        self._modem_conf = modem_conf

        self._logger = logging.getLogger(__name__)
        self._task_loop = task_loop.get_instance()

        self._state_update_tag = 0  # Used to tag logs of async updates to
                                    # state.

        # Will raise an exception if this machine should not be instantiated.
        self.get_well_known_name()

        # Add all wardmodem response functions used by this machine.
        self._add_response_function('wm_response_ok')
        self._add_response_function('wm_response_error')
        self._add_response_function('wm_response_ring')
        self._add_response_function('wm_response_text_only')


    # ##########################################################################
    # Subclasses must override these.
    def get_well_known_name(self):
        """
        A well known name of the completely specified state machine.

        The first derived class that completely specifies some state machine
        should implement this function to return the name of the defining module
        as a string.

        """
        # Do not use self._raise_setup_error because it causes infinite
        # recursion.
        raise wme.WardModemSetupException(
                'Attempted to get well known name for a state machine that is '
                'not completely specified.')


    # ##########################################################################
    # Protected convenience methods to be used as is by subclasses.

    def _respond(self, response, response_delay_ms=0, *response_args):
        """
        Respond to the modem after some delay.

        @param reponse: String response. This must be one of the response
                strings recognized by ATTransceiver.

        @param response_delay_ms: Delay in milliseconds after which the response
                should be sent. Type: int.

        @param *response_args: The arguments for the response.

        @requires: response_delay_ms >= 0

        """
        assert response_delay_ms >= 0
        dbgstr = self._tag_with_name(
                'Will respond with "%s(%s)" after %d ms.' %
                (response, str(response_args), response_delay_ms))
        self._logger.debug(dbgstr)
        self._task_loop.post_task_after_delay(
                self._transceiver.process_wardmodem_response,
                response_delay_ms,
                response,
                *response_args)


    def _update_state(self, state_update, state_update_delay_ms=0):
        """
        Post a (delayed) state update.

        @param state_update: The state update to apply. This is a map {string
                --> state enum} that specifies all the state components to be
                updated.

        @param state_update_delay_ms: Delay in milliseconds after which the
                state update should be applied. Type: int.

        @requires: state_update_delay_ms >= 0

        """
        assert state_update_delay_ms >= 0
        dbgstr = self._tag_with_name(
                '[tag:%d] Will update state as %s after %d ms.' %
                (self._state_update_tag, str(state_update),
                 state_update_delay_ms))
        self._logger.debug(dbgstr)
        self._task_loop.post_task_after_delay(
                self._update_state_callback,
                state_update_delay_ms,
                state_update,
                self._state_update_tag)
        self._state_update_tag += 1


    def _respond_ok(self):
        """ Convenience function to respond when everything is OK. """
        self._respond(self.wm_response_ok, response_delay_ms=0)


    def _respond_error(self):
        """ Convenience function to respond when an error occured. """
        self._respond(self.wm_response_error, response_delay_ms=0)


    def _respond_ring(self):
        """ Convenience function to respond with RING. """
        self._respond(self.wm_response_ring, response_delay_ms=0)


    def _respond_with_text(self, text):
        """ Send back just |text| as the response, without any AT prefix. """
        self._respond(self.wm_response_text_only, 0, text)


    def _add_response_function(self, function):
        """
        Add a response used by this state machine to send to the ATTransceiver.

        A state machine should register all the responses it will use in its
        __init__ function by calling
            self._add_response_function('wm_response_dummy')
        The response can then be used to respond to the transceiver thus:
            self._respond(self.wm_response_dummy)

        @param function: The string function name to add. Must be a valid python
                identifier in lowercase.
                Also, these names are conventionally named matching the re
                'wm_response_([a-z0-9]*[_]?)*'

        @raises: WardModemSetupError if the added response function is ill
                formed.

        """
        if not re.match('wm_response_([a-z0-9]*[_]?)*', function) or \
           keyword.iskeyword(function):
            self._raise_setup_error('Response function name ill-formed: |%s|' %
                                    function)
        try:
            getattr(self, function)
            self._raise_setup_error(
                    'Attempted to add response function %s which already '
                    'exists.' % function)
        except AttributeError:  # OK, This is the good case.
            setattr(self, function, function)


    def _raise_setup_error(self, errstring):
        """
        Log the error and raise WardModemSetupException.

        @param errstring: The error string.

        """
        errstring = self._tag_with_name(errstring)
        self._logger.error(errstring)
        raise wme.WardModemSetupException(errstring)


    def _raise_runtime_error(self, errstring):
        """
        Log the error and raise StateMachineException.

        @param errstring: The error string.

        """
        errstring = self._tag_with_name(errstring)
        self._logger.error(errstring)
        raise wme.StateMachineException(errstring)

    def _tag_with_name(self, log_string):
        """
        If possible, prepend the log string with the well know name of the
        object.

        @param log_string: The string to modify.

        @return: The modified string.

        """
        name = self.get_well_known_name()
        log_string = '[' + name + '] ' + log_string
        return log_string

    # ##########################################################################
    # Private methods not to be used by subclasses.

    def _update_state_callback(self, state_update, tag):
        """
        Actually update the state.

        @param state_update: The state update to effect. This is a map {string
                --> state enum} that specifies all the state components to be
                updated.

        @param tag: The tag for this state update.

        @raises: StateMachineException if the state update fails.

        """
        dbgstr = self._tag_with_name('[tag:%d] State update applied.' % tag)
        self._logger.debug(dbgstr)
        for component, value in state_update.iteritems():
            self._state[component] = value