Commands

Command

Commands are used to do a simple action.

As every other commands, it will be available on the commandBar and you will be able to bind it.

Here an example of a helloworld command:

from devparrot.core.command import Command
@Command()
def helloworld1():
    print("helloworld")

Command can also take arguments:

from devparrot.core.command import Command
@Command()
def helloworld2(text):
    print("input text is", text)

Command provide a useful wait of specify some constraints on the arguments. This is useful to:

For example:

from devparrot.core.command import Command
from devparrot.core import constraints

@Command(
    input_file=constraints.File()
)
def helloworld3(input_file):
    print("the input file is", input_file)

By using tho File constraint, you tell Devparrot that the argument input_file of helloworld3 has to be a file path.

This way:

Constraint can be put on vararg argument also:

fom devparrot.core.command import Command
from devparrot.core import constraints

@Command(
    args = constraints.Integer()
)
def helloworld4(*args):
    for integer in args:
        print("user provide interger %i"%integer)

Constraint can have default:

from devparrot.core.command import Command
from devparrot.core import constraints

@Command(
     arg = constraints.Integer(default= lambda : 55)
)
def helloworld5(arg):
     print("input is", arg)

Note that the default is a function returning the awaiting default value. This provide a more useful way of defining default as default can vary according to the context.

Of course you better should provide some help:

from devparrot.core.command import Command
from devparrot.core import constraints

@Command(
    arg = constraints.Default(help="arg is a simple text with no constraint on it")
)
def helloworld6(arg):
    """ helloworld5 simply print the value it get in argument"""
    print(arg)

Let's try it: start a new devparrot session and ask for the help about helloworld6:

help helloworld6

Some time is usefull to regroup commands in one main one:

from devparrot.core.command import MasterCommand, SubCommand

class master(MasterCommand):
    """This is a master command"""

    @SubCommand()
    def command1():
        print("command1")

    @SubCommand()
    def command2(arg)
        print("command2", arg)

This master command can be use in the command bar in the following way:

master command1
master command2 arg

Stream

Stream are used to pipe commands together

To return a stream, a command just have to return a iterable:

from devparrot.core.command import Command

@Command()
def hellostream1():
    """ return a simple list"""
    return [1, 2, 3]

@Command()
def hellostream2():
   """ yield values instead of return an iterable"""
   for i in xrange(3):
       yield i

To get a input stream, a command have to specifie a argument with the special constraint Stream:

from devparrot.core.command import Command
from devparrot.core import constraints

@Command(
    inputStream = constraints.Stream()
   )
    def hellostream3(inputStream, otherarg):
        for i in inputStream:
            print(otherarg,i)

All of this can be used this way:

hellostream2 | hellostream3 foo

All user command are internally piped to a pseudo command consumming all values of a potential command stream. This ensure you that all the values yield from your command will be consumed even if the command is not piped to another one.

Command section

It is sometime interresting to create some kind of intermediate/internal commands. Those command are used to be composited together to provide a full fonctionnality. However, they are not intented to be directly used by users.

To do so, Devparrot provide a command section. A section regroup a set of commands together. Those commands are callable as any other commands but, as they are intent to be private, they are not include in the completion system nor the help command.

The syntax is a bit more complex:

from devparrot.core.command import Command

@Command(
_section = "private",
arg = constraints.AConstraint()
)
def private_command(arg):
    do_something()
    return may_return_a_stream()

It is now possible to access the private command this way:

private.private_command "bar"