# Copyright 2018 Open Source Foundries Limited.
#
# SPDX-License-Identifier: Apache-2.0

'''West's commands subpackage.

All commands should be implemented within modules in this package.
'''

from abc import ABC, abstractmethod

__all__ = ['CommandContextError', 'WestCommand']


class CommandContextError(RuntimeError):
    '''Indicates that a context-dependent command could not be run.'''


class WestCommand(ABC):
    '''Abstract superclass for a west command.

    All top-level commands supported by west implement this interface.'''

    def __init__(self, name, description, accepts_unknown_args=False):
        '''Create a command instance.

        `name`: the command's name, as entered by the user.
        `description`: one-line command description to show to the user.

        `accepts_unknown_args`: if true, the command can handle
        arbitrary unknown command line arguments in its run()
        method. Otherwise, passing unknown arguments will cause
        UnknownArgumentsError to be raised.
        '''
        self.name = name
        self.description = description
        self._accept_unknown = accepts_unknown_args

    def run(self, args, unknown):
        '''Run the command.

        `args`: known arguments parsed via `register_arguments()`
        `unknown`: unknown arguments present on the command line
        '''
        if unknown and not self._accept_unknown:
            self.parser.error('unexpected arguments: {}'.format(unknown))
        self.do_run(args, unknown)

    def add_parser(self, parser_adder):
        '''Registers a parser for this command, and returns it.
        '''
        self.parser = self.do_add_parser(parser_adder)
        return self.parser

    #
    # Mandatory subclass hooks
    #

    @abstractmethod
    def do_add_parser(self, parser_adder):
        '''Subclass method for registering command line arguments.

        `parser_adder` is an argparse argument subparsers adder.'''

    @abstractmethod
    def do_run(self, args, unknown):
        '''Subclasses must implement; called when the command is run.

        `args` is the namespace of parsed known arguments.

        If `accepts_unknown_args` was False when constructing this
        object, `unknown` will be empty. Otherwise, it is an iterable
        containing all unknown arguments present on the command line.
        '''