Add docs for CLI Options with tests

README.md

@@ -98,7 +98,7 @@ Options:
   --show-completion     Show completion for the current shell, to copy it or customize the installation.
   --help                Show this message and exit.
 
-// You get a ✨ auto completion ✨ for free, installed with --install-completion
+// You get ✨ auto completion ✨ for free, installed with --install-completion
 
 // Now pass the NAME argument
 $ python main.py Camila

docs/css/custom.css

@@ -1,4 +1,9 @@
 .termynal-comment {
-    color: #999;
+    color: #4a968f;
     font-style: italic;
+    display: block;
+}
+
+.termy {
+    white-space: pre-wrap;
 }

docs/index.md

@@ -98,7 +98,7 @@ Options:
   --show-completion     Show completion for the current shell, to copy it or customize the installation.
   --help                Show this message and exit.
 
-// You get a ✨ auto completion ✨ for free, installed with --install-completion
+// You get ✨ auto completion ✨ for free, installed with --install-completion
 
 // Now pass the NAME argument
 $ python main.py Camila

docs/js/custom.js

@@ -6,6 +6,7 @@ document.querySelectorAll(".use-termynal").forEach(node => {
 });
 const progressLiteralStart = "---> 100%";
 const promptLiteralStart = "$ ";
+const customPromptLiteralStart = "# ";
 const termynalActivateClass = "termy";
 let termynals = [];
 
@@ -29,8 +30,8 @@ function createTermynals() {
                     if (isBlankSpace) {
                         dataValue["delay"] = 0;
                     }
-                    if (buffer.length > 1 && buffer[buffer.length - 1] === "") {
-                        // The last single <br> won't have effect
+                    if (buffer[buffer.length - 1] === "") {
+                        // A last single <br> won't have effect
                         // so put an additional one
                         buffer.push("");
                     }
@@ -55,12 +56,25 @@ function createTermynals() {
                     });
                 } else if (line.startsWith("// ")) {
                     saveBuffer();
-                    const value = line.replace("// ", "").trimEnd();
+                    const value = "💬 " + line.replace("// ", "").trimEnd();
                     useLines.push({
                         value: value,
                         class: "termynal-comment",
                         delay: 0
                     });
+                } else if (line.startsWith(customPromptLiteralStart)) {
+                    saveBuffer();
+                    const promptStart = line.indexOf(promptLiteralStart);
+                    if (promptStart === -1) {
+                        console.error("Custom prompt found but no end delimiter", line)
+                    }
+                    const prompt = line.slice(0, promptStart).replace(customPromptLiteralStart, "")
+                    let value = line.slice(promptStart + promptLiteralStart.length);
+                    useLines.push({
+                        type: "input",
+                        value: value,
+                        prompt: prompt
+                    });
                 } else {
                     buffer.push(line);
                 }

docs/js/termynal.js

@@ -243,12 +243,10 @@ class Termynal {
                 attrs += ` class=${line[prop]} `
                 continue
             }
-            attrs += this.pfx;
-
             if (prop === 'type') {
-                attrs += `="${line[prop]}" `
+                attrs += `${this.pfx}="${line[prop]}" `
             } else if (prop !== 'value') {
-                attrs += `-${prop}="${line[prop]}" `
+                attrs += `${this.pfx}-${prop}="${line[prop]}" `
             }
         }
 

docs/release-notes.md

@@ -3,7 +3,7 @@
 ## 0.0.5
 
 * Clean exports from Typer. Remove unneeded components from Click and add needed `Exit` exception. PR [#11](https://github.com/tiangolo/typer/pull/11).
-* Fix and document extracting help from a functions' docstring [First Steps: Document your CLI app](https://typer.tiangolo.com/tutorial/first-steps/#document-your-cli-app). PR [#10](https://github.com/tiangolo/typer/pull/10).
+* Fix and document extracting help from a function's docstring [First Steps: Document your CLI app](https://typer.tiangolo.com/tutorial/first-steps/#document-your-cli-app). PR [#10](https://github.com/tiangolo/typer/pull/10).
 * Update references to `--install-completion` and `--show-completion` in docs. PR [#9](https://github.com/tiangolo/typer/pull/9).
 * Fix testing utilities, add tests for First Steps examples. PR [#8](https://github.com/tiangolo/typer/pull/8).
 * Add auto completion options by default when [click-completion](https://github.com/click-contrib/click-completion) is installed: `--install-completion` and `--show-completion`. PR [#7](https://github.com/tiangolo/typer/pull/7).

docs/src/options/tutorial001.py

@@ -0,0 +1,21 @@
+import typer
+
+
+def main(
+    name: str,
+    lastname: str = typer.Option("", help="Last name of person to greet."),
+    formal: bool = typer.Option(False, help="Say hi formally."),
+):
+    """
+    Say hi to NAME, optionally with a --lastname.
+
+    If --formal is used, say hi very formally.
+    """
+    if formal:
+        typer.echo(f"Good day Ms. {name} {lastname}.")
+    else:
+        typer.echo(f"Hello {name} {lastname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/options/tutorial002.py

@@ -0,0 +1,9 @@
+import typer
+
+
+def main(name: str, lastname: str = typer.Option(...)):
+    typer.echo(f"Hello {name} {lastname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/options/tutorial003.py

@@ -0,0 +1,9 @@
+import typer
+
+
+def main(name: str, lastname: str = typer.Option(..., prompt=True)):
+    typer.echo(f"Hello {name} {lastname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/options/tutorial004.py

@@ -0,0 +1,12 @@
+import typer
+
+
+def main(
+    name: str,
+    lastname: str = typer.Option(..., prompt="Please tell me your last name"),
+):
+    typer.echo(f"Hello {name} {lastname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/options/tutorial005.py

@@ -0,0 +1,9 @@
+import typer
+
+
+def main(project_name: str = typer.Option(..., prompt=True, confirmation_prompt=True)):
+    typer.echo(f"Deleting project {project_name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/options/tutorial006.py

@@ -0,0 +1,9 @@
+import typer
+
+
+def main(fullname: str = typer.Option("Wade Wilson", show_default=True)):
+    typer.echo(f"Hello {fullname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/tutorial/first-steps.md

@@ -22,7 +22,7 @@ Hello World
 // Now check the --help
 $ python main.py --help
 
-Usage: tryit.py [OPTIONS]
+Usage: main.py [OPTIONS]
 
 Options:
   --install-completion  Install completion for the current shell.
@@ -174,16 +174,28 @@ $ ls --size ./myproject
 
 The main visual difference between a *CLI option* and and a *CLI argument* is that the *CLI option* has `--` prepended to the name, like in "`--size`".
 
-A *CLI option* doesn't depend on the order because it has a predefined name (here it's `--size`). This is because the CLI app is looking specifically for a literal `--size` parameter or "flag", with that specific "name" (here the specific name is "`--size`"). The CLI app will check if you typed it or not, it will be actively looking for `--size` even if you didn't type it (to check if it's there or not).
+A *CLI option* doesn't depend on the order because it has a predefined name (here it's `--size`). This is because the CLI app is looking specifically for a literal `--size` parameter (also known as "flag" or "switch"), with that specific "name" (here the specific name is "`--size`"). The CLI app will check if you typed it or not, it will be actively looking for `--size` even if you didn't type it (to check if it's there or not).
 
-In contrast, the CLI app is not actively looking for the *CLI argument* with a text "`./myproject`", it has no way to know if you would type `./myproject` or `./mysuperawesomeproject` or anything else. It's just waiting to get whatever you give it. The only way to know that you refer to a specific *CLI argument* is because of the order. The same way that it knows that the first *CLI argument* was the `name` and the second was the `lastname`, but if you mixed the order, it wouldn't be able to handle it.
+In contrast, the CLI app is not actively looking for the *CLI argument* with a text "`./myproject`", it has no way to know if you would type `./myproject` or `./my-super-awesome-project` or anything else. It's just waiting to get whatever you give it. The only way to know that you refer to a specific *CLI argument* is because of the order. The same way that it knows that the first *CLI argument* was the `name` and the second was the `lastname`, but if you mixed the order, it wouldn't be able to handle it.
 
 Instead, with a *CLI option*, the order doesn't matter.
 
 Also, by default, a *CLI option* is *optional* (not *required*).
 
+So, by default:
+
+* A *CLI argument* is **required**
+* A *CLI option* is **optional**
+
+But the *required* and *optional* defaults can be changed.
+
+So, the main and **most important** difference is that:
+
+* *CLI options* **start with `--`** and don't depend on the order
+* *CLI arguments* depend on the **sequence order**
+
 !!! tip
-    In this example above the *CLI option* `--size` is just a "flag", it's a boolean value, `True` or `False`.
+    In this example above the *CLI option* `--size` is just a "flag" or "switch" that will contain a boolean value, `True` or `False`, depending on if it was added to the command or not.
 
     This one doesn't receive any values. But *CLI options* can also receive values like *CLI arguments*. You'll see how later.
 
@@ -319,7 +331,7 @@ Now see it with the `--help` option:
 ```console
 $ python main.py --help
 
-Usage: tutorial006.py [OPTIONS] NAME
+Usage: main.py [OPTIONS] NAME
 
   Say hi to NAME, optionally with a --lastname.
 
@@ -394,11 +406,11 @@ And a parameter like `name`, that doesn't have a default value, is considered *r
 
 ### In CLIs
 
-When talking about command line interfaces/applications, the words "argument" and "parameter" are commonly used to refer to that data passed to a CLI app, those parameters.
+When talking about command line interfaces/applications, the words **"argument"** and **"parameter"** are commonly used to refer to that data passed to a CLI app, those parameters.
 
-But those words don't imply anything about the data being required, needing to be passed in a certain order, nor having a flag like `--lastname`.
+But those words **don't imply** anything about the data being required, needing to be passed in a certain order, nor having a flag like `--lastname`.
 
-The parameters that come with a flag like `--lastname` and a value (or  when the flag itself is the value, like `--formal`) are commonly optional, not required. So, when talking about CLIs it's common to call them *optional arguments* or *optional parameters*.
+The parameters that come with a name like `--lastname` (and optionally a value) are commonly optional, not required. So, when talking about CLIs it's common to call them **optional arguments** or **optional parameters**. Sometimes these *optional parameters* that start with `--` are also called a **flag** or a **switch**.
 
 In reality, the parameters that require an order can be made *optional* too. And the ones that come with a flag (like `--lastname`) can be *required* too.
 
@@ -408,6 +420,6 @@ To try and make it a bit easier, we'll normally use the words "parameter" or "ar
 
 We'll use ***CLI argument*** to refer to those *CLI parameters* that depend on an order. That are **required** by default.
 
-And we'll use ***CLI option*** to refer to those *CLI parameters* that depend on a flag (like `--lastname`). That are **optional** by default.
+And we'll use ***CLI option*** to refer to those *CLI parameters* that depend on a name that starts with `--` (like `--lastname`). That are **optional** by default.
 
 We will use ***CLI parameter*** to refer to both, *CLI arguments* and *CLI options*.