README.py

# ---
# jupyter:
#   jupytext:
#     formats: py:percent,ipynb
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.13.8
#   kernelspec:
#     display_name: Python 3 (ipykernel)
#     language: python
#     name: python3
# ---

# %% [markdown]
# <p align="center">
#   <img height="300" src="https://dollar-lambda.readthedocs.io/en/latest/_static/logo.png">
# </p>
#
# [$λ](https://dollar-lambda.readthedocs.io/) provides an alternative to [`argparse`](https://docs.python.org/3/library/argparse.html)
# based 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.
#
# # Installation
# ```
# pip install dollar-lambda
# ```
#
# # [Documentation](https://dollar-lambda.readthedocs.io/)
#
# # Highlights
# `$λ` 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 [`@command`](https://dollar-lambda.readthedocs.io/en/latest/api.html?highlight=command#dollar_lambda.decorators.command)
# decorator
# For the vast majority of parsing patterns,
# [`@command`](https://dollar-lambda.readthedocs.io/en/latest/api.html?highlight=command#dollar_lambda.decorators.command)
# is the most concise way to define a parser:


# %%
from dollar_lambda import command


@command()
def main(x: int, dev: bool = False, prod: bool = False):
    print(dict(x=x, dev=dev, prod=prod))


# %% [markdown]
# Here is the help text generated by this parser:
# %%
main("-h")
# %% [markdown]
# Ordinarily you provide no arguments to `main` and 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")
# %% [markdown]
# Use the `parsers` argument to add custom logic using the lower-level syntax:
# %%
from dollar_lambda import flag


@command(parsers=dict(kwargs=flag("dev") | flag("prod")))
def main(x: int, **kwargs):
    print(dict(x=x, **kwargs))


# %% [markdown]
# This parser requires either a `--dev` or `--prod` flag and maps it to the `kwargs` argument:
# %%
main("-h")
# %% [markdown]
# This assigns `{'dev': True}` to the `kwargs` argument:
# %%
main("-x", "1", "--dev")
# %% [markdown]
# This assigns `{'prod': True}` to the `kwargs` argument:
# %%
main("-x", "1", "--prod")
# %% [markdown]
# This fails because the parser requires one or the other:
# %%
main("-x", "1")

# %% [markdown]
# ## [`CommandTree`](https://dollar-lambda.readthedocs.io/en/latest/commandtree.html) for dynamic dispatch
# For 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 execute `prod_function` when the user provides the
# `--prod` flag, and `dev_function` when the user provides the `--dev` flag:

# %%
from dollar_lambda import CommandTree

tree = CommandTree()


@tree.command()
def base_function(x: int):
    print("Ran base_function with arguments:", dict(x=x))


@base_function.command()
def prod_function(x: int, prod: bool):
    print("Ran prod_function with arguments:", dict(x=x, prod=prod))


@base_function.command()
def dev_function(x: int, dev: bool):
    print("Ran dev_function with arguments:", dict(x=x, dev=dev))


# %% [markdown]
# Let's see how this parser handles different inputs.
# If we provide the `--prod` flag, `$λ` automatically invokes
#  `prod_function` with the parsed arguments:

# %%
tree(
    "-x", "1", "--prod"
)  # usually you provide no arguments and tree gets them from sys.argv

# %% [markdown]
# If we provide the `--dev` flag, `$λ` invokes `dev_function`:

# %%
tree("-x", "1", "--dev")

# %% [markdown]
# With this configuration, the parser will run `base_function` if neither
# `--prod` nor `--dev` are given:

# %%
tree("-x", "1")

# %% [markdown]
# There are many other ways to use [`CommandTree`](https://dollar-lambda.readthedocs.io/en/latest/commandtree.html).
# To learn more, we recommend the [`CommandTree` tutorial](https://dollar-lambda.readthedocs.io/en/latest/command_tree.html).
#
# ## Lower-level syntax
# [`@command`](https://dollar-lambda.readthedocs.io/en/latest/api.html?highlight=command#dollar_lambda.decorators.command)
# and [`CommandTree`](https://dollar-lambda.readthedocs.io/en/latest/api.html#dollar_lambda.decorators.CommandTree)
# cover 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 X` and if that fails, tries to parse the input as a variadic sequence of
# floats:

# %%
from dollar_lambda import argument, option

p = option("x", type=int) | argument("y", type=float).many()

# %% [markdown]
# We go over this syntax in greater detail in the [tutorial](https://dollar-lambda.readthedocs.io/en/latest/tutorial.html).
# For now, suffice to say that [`argument`](https://dollar-lambda.readthedocs.io/en/latest/api.html?highlight=argument#dollar_lambda.parsers.argument)
#  defines a positional argument,
# [`many`](https://dollar-lambda.readthedocs.io/en/latest/variations.html?highlight=many#many) allows parsers to be applied
# zero or more times, and [`|`](https://dollar-lambda.readthedocs.io/en/latest/api.html?highlight=__or__#dollar_lambda.parsers.Parser.__or__) expresses alternatives.
#
# Here is the help text:

# %%
p.parse_args(
    "-h"
)  # usually you provide no arguments and parse_args gets them from sys.argv

# %% [markdown]
# As promised, this succeeds:

# %%
p.parse_args("-x", "1")

# %% [markdown]
# And this succeeds:

# %%
p.parse_args("1", "2", "3")

# %% [markdown]
# ### Thanks
# Special thanks to ["Functional Pearls"](https://www.cs.nott.ac.uk/~pszgmh/pearl.pdf) by Graham Hutton and Erik Meijer for bringing these topics to life.