o

�
b�b�@s�dZd
dl
Z
d
dlZd
dlZd
dlmZ
d
dlmZmZm	Z	
d
dl
mZmZm
Z

d
dlmZ
dd�ZGd	d
�d
ej�ZGdd�d�ZGd
d�de�ZGdd�d�Zdd�Zdd�ZdS)a�
No public APIs are provided by this module. Internal use only.

This module implements dynamic tab-completion for any command that uses
twisted.python.usage. Currently, only zsh is supported. Bash support may
be added in the future.

Maintainer: Eric P. Mangold - twisted AT teratorn DOT org

In order for zsh completion to take place the shell must be able to find an
appropriate "stub" file ("completion function") that invokes this code and
displays the results to the user.

The stub used for Twisted commands is in the file C{twisted-completion.zsh},
which is also included in the official Zsh distribution at
C{Completion/Unix/Command/_twisted}. Use this file as a basis for completion
functions for your own commands. You should only need to change the first line
to something like C{#compdef mycommand}.

The main public documentation exists in the L{twisted.python.usage.Options}
docstring, the L{twisted.python.usage.Completions} docstring, and the
Options howto.
�N)
�
MethodType)�Dict�List�Set)�reflect�usage�util)
�ioTypecCs\
|rt|�
t
kr|j}|d
�d�
\}}t|�
}|d8}||}|dkr7||d�d�
r2|d8}n
n|dks$|d|�}t|dd�}|r�d}z
t�||j|j	�\}	}Wn
tj
y^


Yn
w|r�|jD]&\}
}}}
|d|
ksv|d|kr�|�}||_t
|||
|�}|��

dSqdd	}|�d�
r�d
}t||
|�}|j|d�

dSt||
|�}|��
dS)ao
    Perform shell completion.

    A completion function (shell script) is generated for the requested
    shell and written to C{shellCompFile}, typically C{stdout}. The result
    is then eval'd by the shell to produce the desired completions.

    @type config: L{twisted.python.usage.Options}
    @param config: The L{twisted.python.usage.Options} instance to generate
        completions for.

    @type cmdName: C{str}
    @param cmdName: The name of the command we're generating completions for.
        In the case of zsh, this is used to print an appropriate
        "#compdef $CMD" line at the top of the output. This is
        not necessary for the functionality of the system, but it
        helps in debugging, since the output we produce is properly
        formed and may be saved in a file and used as a stand-alone
        completion function.

    @type words: C{list} of C{str}
    @param words: The raw command-line words passed to use by the shell
        stub function. argv[0] has already been stripped off.

    @type shellCompFile: C{file}
    @param shellCompFile: The file to write completion data to.
    ����
:��
�
-N�subCommandsr
TF)
�genSubs)r	�str�buffer�split�int�
startswith�getattr�getopt�shortOpt�longOpt�errorr�parent�ZshSubcommandBuilder�write�
ZshBuilder)�config�cmdName�words�
shellCompFile�	shellName�position�cWordr�args�opts�cmd�short�parser�doc�
subOptions�genr�r.�;/usr/lib/python3/dist-packages/twisted/python/_shellcomp.py�
shellComplete'sL






�




�



�
�




r0c@seZ
dZd
d�ZdS)�SubcommandActioncCs|tj
krd
Std|���
�
)Nz*::subcmd:->subcmdzUnknown shellType )r�_ZSH�NotImplementedError)�self�optName�	shellTyper.r.r/�
_shellCode�s



zSubcommandAction._shellCodeN)�__name__�
__module__�__qualname__r7r.r.r.r/r1�s
r1c@s"eZ
dZd
Zdd�Zddd�
ZdS)	ra�
    Constructs zsh code that will complete options for a given usage.Options
    instance, possibly including a list of subcommand names.

    Completions for options to subcommands won't be generated because this
    class will never be used if the user is completing options for a specific
    subcommand. (See L{ZshSubcommandBuilder} below)

    @type options: L{twisted.python.usage.Options}
    @ivar options: The L{twisted.python.usage.Options} instance defined for this
        command.

    @type cmdName: C{str}
    @ivar cmdName: The name of the command we're generating completions for.

    @type file: C{file}
    @ivar file: The C{file} to write the completion function to.  The C{file}
        must have L{bytes} I/O semantics.
    cCs|
|_||_
||_dS�
N)�optionsr �file)r4r<r r=r.r.r/�__init__�s



zZshBuilder.__init__TcCs�|
rSt|j
d
d�du
rSt|j
|j|j�}|j�dt��
|��
|j�d�

|j
j	D]\}}}}|j�d|�
d�
d|�
d�
d�

q*|j�d	�

|j�d
�

dSt|j
|j|j�}|��
dS)a�

        Generate the completion function and write it to the output file
        @return: L{None}

        @type genSubs: C{bool}
        @param genSubs: Flag indicating whether or not completions for the list
            of subcommand should be generated. Only has an effect
            if the C{subCommands} attribute has been defined on the
            L{twisted.python.usage.Options} instance.
        rNr
s.local _zsh_subcmds_array
_zsh_subcmds_array=(
�
"�utf-8�
:s"
s)

s+_describe "sub-command" _zsh_subcmds_array
)rr<�ZshArgumentsGeneratorr r=�extraActions�insertr1rr�encode)r4rr-r(r)r*�descr.r.r/r�s






�

zZshBuilder.writeN)
T�r8r9r:�__doc__r>rr.r.r.r/r�s
rc@s eZ
dZd
Zdd�Zdd�ZdS)ra�

    Constructs zsh code that will complete options for a given usage.Options
    instance, and also for a single sub-command. This will only be used in
    the case where the user is completing options for a specific subcommand.

    @type subOptions: L{twisted.python.usage.Options}
    @ivar subOptions: The L{twisted.python.usage.Options} instance defined for
        the sub command.
    cGs|
|_t
j|g
|�
R�
dSr;)r,rr>)r4r,r&r.r.r/r>�s

zZshSubcommandBuilder.__init__c
CsHt|j
|j|j�}
|
j�d
t��
|
��
t|j|j|j�}
|
��
dS)zk
        Generate the completion function and write it to the output file
        @return: L{None}
        r
N)	rBr<r r=rCrDr1rr,)r4r-r.r.r/r�s



zZshSubcommandBuilder.writeNrGr.r.r.r/r�s

rc@s�eZ
dZd
Zdd�Zdd�Zdd�Zdd	�Zd
d�Zdd
�Z	dd�Z
d!dd�
Zdee
ee
ffdd�Zdd�Zdd�Zdd�Zdd�Zd"dd �ZdS)#rBa0	
    Generate a call to the zsh _arguments completion function
    based on data in a usage.Options instance

    The first three instance variables are populated based on constructor
    arguments. The remaining non-constructor variables are populated by this
    class with data gathered from the C{Options} instance passed in, and its
    base classes.

    @type options: L{twisted.python.usage.Options}
    @ivar options: The L{twisted.python.usage.Options} instance to generate for

    @type cmdName: C{str}
    @ivar cmdName: The name of the command we're generating completions for.

    @type file: C{file}
    @ivar file: The C{file} to write the completion function to.  The C{file}
        must have L{bytes} I/O semantics.

    @type descriptions: C{dict}
    @ivar descriptions: A dict mapping long option names to alternate
        descriptions. When this variable is defined, the descriptions
        contained here will override those descriptions provided in the
        optFlags and optParameters variables.

    @type multiUse: C{list}
    @ivar multiUse: An iterable containing those long option names which may
        appear on the command line more than once. By default, options will
        only be completed one time.

    @type mutuallyExclusive: C{list} of C{tuple}
    @ivar mutuallyExclusive: A sequence of sequences, with each sub-sequence
        containing those long option names that are mutually exclusive. That is,
        those options that cannot appear on the command line together.

    @type optActions: C{dict}
    @ivar optActions: A dict mapping long option names to shell "actions".
        These actions define what may be completed as the argument to the
        given option, and should be given as instances of
        L{twisted.python.usage.Completer}.

        Callables may instead be given for the values in this dict. The
        callable should accept no arguments, and return a C{Completer}
        instance used as the action.

    @type extraActions: C{list} of C{twisted.python.usage.Completer}
    @ivar extraActions: Extra arguments are those arguments typically
        appearing at the end of the command-line, which are not associated
        with any particular named option. That is, the arguments that are
        given to the parseArgs() method of your usage.Options subclass.
    cCs�
|
|_||_
||_i|_t�|_g|_i|_g|_t	t
�|
j�
�
D]-}t
|d
d�}|rN|j�|j�

|j�|j�

|j�|j�

|j�|j�

|jrN|j|_q!tj}g}g}||
jd|�
||
jd|�
t|�
D]\}	}
t|
�
dkrzt�d|
�||	<qht|�
D]\}	}
t|
�
dkr�t�d|
�||	<q||_||_i}|D]}
|
dd�||
d<q�||_i}|D]}
|
dd�||
d<q�||_i}
|
�|�

|
�|�

|
|_|��
|��
|��|_dS)N�compData�optFlags�
optParameters��r
r
)r<r r=�descriptions�set�multiUse�mutuallyExclusive�
optActionsrC�reversed�inspect�getmro�	__class__r�update�extendr�accumulateClassList�	enumerate�lenr�padTorJ�	optParams�paramNameToDefinition�flagNameToDefinition�allOptionsNameToDefinition�addAdditionalOptions�verifyZshNames�makeExcludesDict�excludes)r4r<r r=�cls�data�aCLrJr]�
i�optListr^r_r`r.r.r/r>
s`












�



�

�











zZshArgumentsGenerator.__init__c

Cs$|��
|�
�
|��
|��
d
S)zf
        Write the zsh completion code to the file given to __init__
        @return: L{None}
        N)�writeHeader�writeExtras�writeOptions�writeFooter�
r4r.r.r/r\
s


zZshArgumentsGenerator.writec

Cs |j�
d
|j�d�
d�

dS)z^
        This is the start of the code that calls _arguments
        @return: L{None}
        s	#compdef r@s

_arguments -s -A "-*" \
N)r=rr rErnr.r.r/rjf
s
�z!ZshArgumentsGenerator.writeHeaderc
Cs.t|j
���
}
|
��
|
D]}|�|�

q
d
S)z]
        Write out zsh code for each option in this command
        @return: L{None}
        N)�listr`�keys�sort�writeOpt)r4�optNames�longnamer.r.r/rlp
s



�z"ZshArgumentsGenerator.writeOptionsc
Csdt|j
�
D]*\}
}|jr|
t|j
�
d
krtd�
�
|j�t|�dt	j
��
�d�
�

|j�d�

qdS)a�

        Write out completion information for extra arguments appearing on the
        command-line. These are extra positional arguments not associated
        with a named option. That is, the stuff that gets passed to
        Options.parseArgs().

        @return: L{None}

        @raise ValueError: If C{Completer} with C{repeat=True} is found and
            is not the last item in the C{extraActions} list.
        r
zDCompleter with repeat=True must be last item in Options.extraActions�r@� \
N)rZrC�_repeatr[�
ValueErrorr=r�escaper7rr2rE)r4rh�actionr.r.r/rkz
s

� 
�z!ZshArgumentsGenerator.writeExtrasc

Cs|j�
d
�

dS)zj
        Write the last bit of code that finishes the call to _arguments
        @return: L{None}
        s&& return 0
N)r=rrnr.r.r/rm�
sz!ZshArgumentsGenerator.writeFooterc
sd�f
d
d�}
t�
�j�j�j�D]}|�jv
r|
|�

q�jD]}|D]}|�jv
r.|
|�

q#qdS)z�
        Ensure that none of the option names given in the metadata are typoed
        @return: L{None}
        @raise ValueError: If unknown option names have been found.
        c

std
|�j
f�
�
)NzJUnknown option name "%s" found while
examining Completions instances on %s)rxr<)
�namernr.r/�err�
s



��z1ZshArgumentsGenerator.verifyZshNames.<locals>.errN)�	itertools�chainrNrRrPr`rQ)r4r|r{�seqr.rnr/rb�
s


�




���z$ZshArgumentsGenerator.verifyZshNamesFcCs�|
|jvr
|j|
�
�}nt�}|
|jv
r-|d
ur(|�|
�
}|du
r'|�|�

n|�|
�

|s1dSg}|D]}t|�
dkrE|�d|�

q5|�d|�

q5|��
dd�	|�
S)	a�

        Generate an "exclusion string" for the given option

        @type longname: C{str}
        @param longname: The long option name (e.g. "verbose" instead of "v")

        @type buildShort: C{bool}
        @param buildShort: May be True to indicate we're building an excludes
            string for the short option that corresponds to the given long opt.

        @return: The generated C{str}
        FNrur
rz--z(%s)�
 )
rd�copyrOrP�getShortOption�addr[�appendrq�join)r4rt�
buildShort�
exclusionsr)�stringsr5r.r.r/�
excludeStr�
s&









�





z ZshArgumentsGenerator.excludeStr�returnc
	Cs�i}
t�
|j|j�D]}|d
dkr|d
|
|d<q
i}|jD]?}t|�
D]8\}}t|d|�||d
d��
}|��D]
}||
vrK|�|
|�

q>||vrZ||�	|�
||<q&|||<q&q |S)z�
        @return: A C{dict} that maps each option name appearing in
            self.mutuallyExclusive to a set of those option names that is it
            mutually exclusive with (can't appear on the cmd line with).
        r
Nr
)
r}r~r]rJrQrZrOr�r��union)	r4�longToShortrird�lstrhrt�tmpr{r.r.r/rc�
s$


�


 



�

�
z&ZshArgumentsGenerator.makeExcludesDictc	Cs
|
|jvr
d
|
}nd|
}|�
|
�
}|dkrd|}nd}|�|
�
}|�dd�}|�dd	�}d
|}|�|
�
}|
|jvr@d}nd}|�|
�
}	|rh|j|
dd
�}
|j�t	d|
||||f�
�
d�
�

|j�d�

|j�t	d|	||||f�
�
d�
�

|j�d�

dS)a

        Write out the zsh code for the given argument. This is just part of the
        one big call to _arguments

        @type longname: C{str}
        @param longname: The long option name (e.g. "verbose" instead of "v")

        @return: L{None}
        z--%sz--%s=Nrru�
[z\[�
]z\]z[%s]�
*T)
r�z
%s%s%s%s%sr@rv)r_r��getDescription�replace�	getActionrPr�r=rryrE)r4rt�	longFieldr)�
shortField�descr�descriptionField�actionField�
multiField�longExclusionsField�shortExclusionsFieldr.r.r/rr�
s\






















���	�





���	�zZshArgumentsGenerator.writeOptcCsX|
|jvrt
|j|
�
r|j|
�}n|j|
}|�|
tj�S|
|jvr*d
|
�d�SdS)z]
        Return a zsh "action" string for the given argument
        @return: C{str}
        rz:_filesru)rR�callabler7rr2r^)r4rtrzr.r.r/r�4s







zZshArgumentsGenerator.getActioncCs�|
|jvr
|j|
Sz	|j
|
d
}Wnty1


z	|j|
d}Wnty.


d}Yn
wYn
w|du
r8|S|
�dd�}t|jd|d�}|du
rUt|�
}|du
rU|S|
S)z]
        Return the description to be used for this argument
        @return: C{str}
        r
rNr�
_zopt_%s)rNr_�KeyErrorr^r�rr<�descrFromDoc)r4rtr��longMangled�objr.r.r/r�Ds*








���





z$ZshArgumentsGenerator.getDescriptioncCs|j|
}|d
p
dS)z[
        Return the short option letter or None
        @return: C{str} or L{None}
        r
N)
r`)r4rtrir.r.r/r�cs

z$ZshArgumentsGenerator.getShortOptionNc

Cs
i}
t�
|j|
d
�
i}|
��D]}t|�
dkr!|||
|<|
|=q|
��D][\}}|�dd�}||jvr6q&|�|�
}d}||vrE||}|j	j
j}	|	dkri|j�
||d|g�

|d|g|j|<|d|g|j|<q&|j�
|||g�

||g|j|<|d|g|j|<q&dS)z�
        Add additional options to the optFlags and optParams lists.
        These will be defined by 'opt_foo' methods of the Options subclass
        @return: L{None}
        �opt_r
r�rNr)r�accumulateMethodsr<r�r[�itemsr�r`r��__func__�__code__�co_argcountr]r�r^rJr_)
r4�methodsDict�
methodToShortr{�
methodName�	methodObjrtr�r)�reqArgsr.r.r/raks2





�












�z*ZshArgumentsGenerator.addAdditionalOptions)
F)r�N)r8r9r:rHr>rrjrlrkrmrbr�rrrrcrrr�r�r�rar.r.r.r/rB�s 
4D



*BrBc
Cs8|jd
us
|j�
�rd
Sdd�|j�d�
D�
}
d�|
�
S)zP
    Generate an appropriate description from docstring of the given object
    Nc
Ss g|]}
|
r|
��s|
�
��qSr.)�isspace�strip)�.0�
xr.r.r/�
<listcomp>�s z descrFromDoc.<locals>.<listcomp>�

r�)rHr�rr�)r��linesr.r.r/r��s


r�c
CsFd
|v
r
d
|d
Sd}
|D]}|dvr|
d}
|
|}
q|
d}
|
S)zw
    Shell escape the given string

    Implementation borrowed from now-deprecated commands.mkarg() in the stdlib
    �
'�
"z\$"`�
\r.)r��
s�
cr.r.r/ry�s








ry)rHrrTr}�typesr�typingrrr�twisted.pythonrrr�twisted.python.compatr	r0�	Completerr1rrrBr�ryr.r.r.r/�<module>
s$




d53