Package: dollar-lambda
$λprovides an alternative toargparsebased on parser combinators and functional first principles. Arguably,$λis way more expressive than any reasonable
person would ever need... but even if it's not the parser that we need, it's the parser we deserve.Installationpip install dollar-lambdaDocumentationHighlights$λcomes with syntactic sugar that can make building parsers completely boilerplate-free.
For complex parsing situations that exceed the expressive capacity of this syntax,
the user can also drop down to the lower-level syntax that lies behind the sugar, which can
handle any reasonable amount of logical complexity.The@commanddecorator
For the vast majority of parsing patterns,@commandis the most concise way to define a parser:fromdollar_lambdaimportcommand@command()defmain(x:int,dev:bool=False,prod:bool=False):print(dict(x=x,dev=dev,prod=prod))Here is the help text generated by this parser:main("-h")usage: -x X --dev --prod
dev: (default: False)
prod: (default: False)Ordinarily you provide no arguments tomainand it would get them from the command line.
The explicit arguments in this Readme are for demonstration purposes only.
Here is how the main function handles input:main("-x","1","--dev"){'x': 1, 'dev': True, 'prod': False}Use theparsersargument to add custom logic using the lower-level syntax:fromdollar_lambdaimportflag@command(parsers=dict(kwargs=flag("dev")|flag("prod")))defmain(x:int,**kwargs):print(dict(x=x,**kwargs))This parser requires either a--devor--prodflag and maps it to thekwargsargument:main("-h")usage: -x X [--dev | --prod]This assigns{'dev': True}to thekwargsargument:main("-x","1","--dev"){'x': 1, 'dev': True}This assigns{'prod': True}to thekwargsargument:main("-x","1","--prod"){'x': 1, 'prod': True}This fails because the parser requires one or the other:main("-x","1")usage: -x X [--dev | --prod]
The following arguments are required: --devCommandTreefor dynamic dispatchFor many programs, a user will want to use one entrypoint for one set of
arguments, and another for another set of arguments. Returning to our example,
let's say we wanted to executeprod_functionwhen the user provides the--prodflag, anddev_functionwhen the user provides the--devflag:fromdollar_lambdaimportCommandTreetree=CommandTree()@tree.command()defbase_function(x:int):print("Ran base_function with arguments:",dict(x=x))@base_function.command()defprod_function(x:int,prod:bool):print("Ran prod_function with arguments:",dict(x=x,prod=prod))@base_function.command()defdev_function(x:int,dev:bool):print("Ran dev_function with arguments:",dict(x=x,dev=dev))Let's see how this parser handles different inputs.
If we provide the--prodflag,$λautomatically invokesprod_functionwith the parsed arguments:tree("-x","1","--prod")# usually you provide no arguments and tree gets them from sys.argvRan prod_function with arguments: {'x': 1, 'prod': True}If we provide the--devflag,$λinvokesdev_function:tree("-x","1","--dev")Ran dev_function with arguments: {'x': 1, 'dev': True}With this configuration, the parser will runbase_functionif neither--prodnor--devare given:tree("-x","1")Ran base_function with arguments: {'x': 1}There are many other ways to useCommandTree.
To learn more, we recommend theCommandTreetutorial.Lower-level syntax@commandandCommandTreecover many use cases,
but they are both syntactic sugar for a lower-level interface that is far
more expressive.Suppose you want to implement a parser that first tries to parse an option
(a flag that takes an argument),-x Xand if that fails, tries to parse the input as a variadic sequence of
floats:fromdollar_lambdaimportargument,optionp=option("x",type=int)|argument("y",type=float).many()We go over this syntax in greater detail in thetutorial.
For now, suffice to say thatargumentdefines a positional argument,manyallows parsers to be applied
zero or more times, and|expresses alternatives.Here is the help text:p.parse_args("-h")# usually you provide no arguments and parse_args gets them from sys.argvusage: [-x X | [Y ...]]As promised, this succeeds:p.parse_args("-x","1"){'x': 1}And this succeeds:p.parse_args("1","2","3"){'y': [1.0, 2.0, 3.0]}ThanksSpecial thanks to"Functional Pearls"by Graham Hutton and Erik Meijer for bringing these topics to life.