Intro

This intro serves as a quick starting off point to see some of arc's most useful features.

Hello World

The simplest arc program would look like this

hello_world.py

import arc


@arc.command()
def main():
    arc.print("Hello World!")


main()

Which we can then execute directly!

$ python hello_world.py 
Hello World!

Let's break this down to better understand what exactly is going on.

1. @arc.command() is a Python decorator that transforms a function into an arc command.
2. def main() is just a simple Python function
3. main() while this make look like we're calling the main function, because the function has been transformed into a command, we're actualy executing the command.

Parameters

We can add parameters to the previous example by defining some Python argument. For example, instead of saying hello to the world, we can have the command say hello to a specific person that we can input:

examples/hello.py

import arc


@arc.command()
def hello(name: str):
    """My first arc program!"""
    arc.print(f"Hello {name}!")


hello()

$ python hello.py Joseph
Hello Joseph!

Documentation

Our argument and docstring get added automatcially to the --help output

$ python hello.py --help
USAGE
    hello.py [-h] [--] name

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

OPTIONS
    --help (-h)  Displays this help message

Type Hints

arc uses argument type hints for data validation / conversion. For example, say we want to write a command that can sum two numbers together:

examples/add.py

import arc


@arc.command()
def add(val1: int, val2: int):
    arc.print(f"The answer is: {val1 + val2}")


add()

$ python add.py 5 10
The answer is: 15

if the input fails to validate, arc will report a user-friendly error for the type

$ python add.py 5 not-a-number
USAGE
    add.py [-h] [--] val1 val2

invalid value for val2: must be an integer (invalid literal for int() with base 10: 'not-a-number')

Some note about types:

• if a parameter does not specify a type, arc implicitly types it as str.
• All builtin types are supported by arc, and many stdlib types
• Parameter Types contains a comprehensive list of all supported types.