"""SCons.Executor

A module for executing actions with specific lists of target and source
Nodes.

"""

#
# __COPYRIGHT__
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#

__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"


from SCons.Debug import logInstanceCreation
import SCons.Util


class Executor:
    """A class for controlling instances of executing an action.

    This largely exists to hold a single association of an action,
    environment, list of environment override dictionaries, targets
    and sources for later processing as needed.
    """

    def __init__(self, action, env=None, overridelist=[],
                 targets=[], sources=[], builder_kw={}):
        if __debug__: logInstanceCreation(self)
        if not action:
            raise SCons.Errors.UserError, "Executor must have an action."
        self.action = action
        self.env = env
        self.overridelist = overridelist
        self.targets = targets
        self.sources = sources[:]
        self.builder_kw = builder_kw

    def get_build_env(self):
        """Fetch or create the appropriate build Environment
        for this Executor.
        """
        try:
            return self.build_env
        except AttributeError:
            # Create the build environment instance with appropriate
            # overrides.  These get evaluated against the current
            # environment's construction variables so that users can
            # add to existing values by referencing the variable in
            # the expansion.
            overrides = {}
            for odict in self.overridelist:
                overrides.update(odict)
            try:
                generate_build_dict = self.targets[0].generate_build_dict
            except (AttributeError, IndexError):
                pass
            else:
                overrides.update(generate_build_dict())

            import SCons.Defaults
            env = self.env or SCons.Defaults.DefaultEnvironment()
            self.build_env = env.Override(overrides)

            # Now update the build environment with the things that we
            # don't want expanded against the current construction
            # variables.
            self.build_env._update(SCons.Util.subst_dict(self.targets,
                                                         self.sources))
            return self.build_env

    def do_nothing(self, target, errfunc, **kw):
        pass

    def __call__(self, target, errfunc, **kw):
        """Actually execute the action list."""
        kw = kw.copy()
        kw.update(self.builder_kw)
        apply(self.action, (self.targets, self.sources,
                            self.get_build_env(), errfunc), kw)

    def cleanup(self):
        try:
            del self.build_env
        except AttributeError:
            pass

    def add_sources(self, sources):
        """Add source files to this Executor's list.  This is necessary
        for "multi" Builders that can be called repeatedly to build up
        a source file list for a given target."""
        slist = filter(lambda x, s=self.sources: x not in s, sources)
        self.sources.extend(slist)

    def __str__(self):
        try:
            return self.string
        except AttributeError:
            action = self.action
            self.string = action.genstring(self.targets,
                                           self.sources,
                                           self.get_build_env())
            return self.string

    def nullify(self):
        self.__call__ = self.do_nothing
        self.string = ''

    def get_contents(self):
        """Fetch the signature contents.  This, along with
        get_raw_contents(), is the real reason this class exists, so we
        can compute this once and cache it regardless of how many target
        or source Nodes there are.
        """
        try:
            return self.contents
        except AttributeError:
            action = self.action
            self.contents = action.get_contents(self.targets,
                                                self.sources,
                                                self.get_build_env())
            return self.contents

    def get_timestamp(self):
        """Fetch a time stamp for this Executor.  We don't have one, of
        course (only files do), but this is the interface used by the
        timestamp module.
        """
        return 0