Module checkRDbg

Checks input options from sys.argv and returns the tuple of resulting
debug parameters. The options are removed from sys.argv by default.

The options are kept as provided, or when missing filled with default values.
The final resolution of the values like file system globs is performed within
the PyDevRDC class.

The following options are checked and removed from sys.argv, thus by default
has to be added by the caller application again when required for following
nested calls:

    --rdbg [[host]:[port]]:

        Enables debugging of subprocesses via RemoteDebugServer. By default
        for local instance 'localhost:5679', provides optionally altered
        connection parameters:

            host: Host address, DNS or IP.

            port: Port number.

    --rdbg-env:

        Forces or disables the use of specific environment variables.
            ::

                RDBGROOT, RDBGSUB

            * True: Forces the use of present variables

            * False: disables use

            * default: Applied in normal order when scanning the filesystem

    --rdbg-forward [<depth>]:

        Defines forwarding of debugging state, either by passing
        the current instance, or by additionally debugging the next level(s)
        of nested subprocesses. The value of <depth> is one of:

            #hopcnt:  Number of levels for nested subprocesses.

            'all': All nested levels.

            label: The subprocesses with matching label only.

        The design of passing options into nested calls is considered as
        insertion of the forwarded options before the first option of the next
        level caller:
          ::

            epyu --rdbg --rdbg-froward=2 nextlevel -a --bxy ....

        This results in:
          ::

            nextlevel --rdbg --rdbg-froward=2 -a --bxy ....

        In case of optional sub-parameters the temination option '--'
        could be applied:
          ::

            epyu --rdbg --rdbg-froward=2 nextlevel -- arguments

        results in:
          ::

            nextlevel --rdbg --rdbg-froward=2  -- arguments

        The current version requiresthis to be proceeded by the application,
        refer to 'epyu..py'.

    --rdbg-root (<rootforscan>|<FQDN>|<path-glob>):

        Defines the initial root path for scan, the following defaults
        are scanned initially when this parameter is provided without
        a value.

            Linux, BSD, and Unix:
                ::

                    $HOME/eclipse

            Mac-OS:
                ::

                    $HOME/eclipse

            Windows:
                ::

                    C:\eclipse

            Cygwin:
                ::

                    /cygdrive/c/eclipse

        When the value is not found, the additional defaults
        are scanned as provided by 'PyDevRDC.scanEclipseForPydevd'.

        Each root is searched by the the following order of
        sub-pattern matching.
            ::

                0. plugins/<rdbgsub>

                1. dropins/<rdbgsub>

                2. dropins/*/plugins/<rdbgsub>

        For details refer to 'pydevrdc.scanEclipseForPydevd'
        `[see] <pydeverdbg.html#scaneclipseforpydevd>`_.

    --rdbg-sub (<literal>|<path-glob>):

        Defines the initial subpath within the Eclipse installation.
        When not present, the extended defaults are scanned, for
        further details refer to 'PyDevRDC.scanEclipseForPydevd':
            ::

                pydevd_subpath = "org.python.pydev_[0-9]*.[0-9]*.[0-9]*/pysrc/pydevd.py"

Test options and flags:

    --pderd_inTestMode_suppress_init:

        Control initialization of the preconfigured debug stub.
        It is foreseen to be the only instance under normal
        circumstances.

    --pderd_debug_self:

        Enabled debugging messages for debug, this also includes
        the pre-debug initialization of the remote debug server.

    --pderd_unit_self:

        Enabled log messages for unittests.

    --pderd_testflags:

        Sets specific testflags, valid values for testflags are:

        ignorePydevd: ignores loaded pydevd.py, for search test only

        ignorePydevdSysPath: ignores sys.path, for search test only

        ignorePydevdCallParam: ignores call parameters

Environment variables:

    The provided environment variables are read out, when no related
    option is available. In case both are not provided, the hard-coded
    defaults are applied. The read of environment variables could be
    supressed in general by the option 'noenv'/'--no-env'.

        RDBGROOT => --rdbg-root

        RDBGSUB => --rdbg-sub

Args:

    argv: Alternative argv, default:=sys.argv

    **kargs:

        debug:

            Same as '--debug', developer output.

        fpname:

            The file path name of the main file for the current
            process, default:=callname.

        label:

            The label identifying the current process, default:=callname.

        noargv:

            Suppresses argv processing completely for the previous
            arguments. The testflags are still processed.

        rdbg:

            Same as '--rdbg', for additional processing see 'noargv'.

        rdbgsrv:

            Same as '--rdbg'srv, for additional processing see 'noargv'.

        rdbgforward:

            Same as '--rdbg-forward', for additional processing see 'noargv'.

        rdbgroot:

            Same as '--rdbg-root', for additional processing see 'noargv'.

        rdbgsub:

            Same as '--rdbg-sub', for additional processing see 'noargv'.

        verbose:

            Same as '--verbose', user output.

Returns:
    When successful returns tuple of the following debug parameters. The
    options are removed from 'sys.argv'.

    return/value := ( rdbgthis, rdbg, rdbgfwd, rdbgroot, rdbgsub, )

        rdbgthis = (True|False): Debugging of current process/thread is enabled.

        rdbg = [host][:port]: Connection parameter of peer RemoteDebugServer

        rdbgfwd = <partialprocessed>: Forward debug parameters

            partialprocessed: One of:

                hop = hopcnt - 1

                'all'

                label

        rdbgroot = <rootforscan>: Base for search, when None the defaults apply.

        rdbgsub = <eclipse-subpath>: Subpath within Eclipse.

Raises:

Checks presence of '--rdbg' option.

Args:

argv:

Alternative argv, default:=sys.argv.

Returns:

When present True, else False.

Raises:

Returns the current defaults.

Args:

res:

Result, the type of 'res' defines the return type. The default when 'None' is tuple.

Returns:

Returns the collection of default. The following options are available:

res == None: (default)

result is a new created tuple:

res := ( )

res in (tuple, list,):

see default, container type as provided.

res == dict:

res := {

}

res is epyunit.Namespace

Similar to argparse.Namespace, foreseen to be used also as predefined default input for 'epyunit.debug.checkRDbg'.