Merge pull request #67 from codecrafters-io/completions-extension

Stage descriptions for `Completions` extension

course-definition.yml

@@ -941,7 +941,7 @@ stages:
   - slug: "ac1"
     primary_extension_slug: "completions"
     name: "Builtin completion"
-    difficulty: easy
+    difficulty: medium
     description_md: |-
       In this stage, you'll implement support for autocompleting builtin commands.
 
@@ -963,10 +963,10 @@ stages:
       2.  **Input:** `exi`<TAB>
           * The tester expects the prompt to display `exit` after the tab press.
 
-      The tester checks if the completion works as expected and if your shell outputs the correct output for echo and exit command.
+      The tester checks if the completion works as expected and if your shell outputs the correct output for `echo` and `exit` command.
 
     marketing_md: |-
-      In this stage, you'll add basic tab completion to your shell.
+      In this stage, you'll implement support for autocompleting builtin commands.
 
   - slug: "ac2"
     primary_extension_slug: "completions"
@@ -989,18 +989,19 @@ stages:
 
       The tests will simulate user input with tab presses and will execute builtin commands, similar to the previous stage, with added arguments:
 
-      1.  **Input:** `ech`<TAB><ENTER> `hello`<ENTER>
-          *   The tester expects the shell to first complete the `ech` to `echo` after `<TAB>`, and then execute `echo hello` after the second `<ENTER>`.
+      1.  **Input:** `ech`<TAB> `hello`<ENTER>
+          *   The tester expects the shell to first complete the `ech` to `echo` after `<TAB>`, then accept the `hello` argument, and after the `<ENTER>` key press, execute `echo hello`.
           *   The shell should output `hello`.
 
-      2.  **Input:** `typ`<TAB><ENTER> `type`<ENTER>
-           *   The tester expects the shell to first complete `typ` to `type` after `<TAB>`, and then execute `type type` after the second `<ENTER>`.
+      2.  **Input:** `typ`<TAB> `type`<ENTER>
+           *   The tester expects the shell to first complete `typ` to `type` after `<TAB>`, then accept the `type` argument, and after the `<ENTER>` key press, execute `type type`.
            *   The shell should output `type is a shell builtin`.
 
       The tester will verify that your shell properly completes the commands and executes the commands with the given arguments.
 
     marketing_md: |-
-      This stage enhances your shell's completion by allowing arguments to be used after completion. 
+      In this stage, you'll implement support for allowing arguments to be used after completion. 
+      
 
   - slug: "ac3"
     primary_extension_slug: "completions"
@@ -1026,20 +1027,21 @@ stages:
           *   The tester will first type `xyz` and then press `<TAB>`. The tester expects that the prompt still shows "xyz" and there is a bell sound.
 
       The tester will verify that your shell does not attempt completion on invalid commands, the bell is sent.
+      The bell is sent by printing the `\a` character.
 
     marketing_md: |-
-      This stage improves your shell's usability by handling invalid commands gracefully.
+      In this stage, you'll implement support for handling invalid commands gracefully.
 
   - slug: "ac4"
     primary_extension_slug: "completions"
     name: "Executable completion"
-    difficulty: easy
+    difficulty: medium
     description_md: |-
       In this stage, you'll extend your shell's tab completion to include external executable files in the user's `PATH`.
 
       Your shell should now be able to complete commands that are not built-ins, but exist as executable files in the directories listed in the `PATH` environment variable.
       When the user types the beginning of an external command and presses `<TAB>`, your shell should complete the command to the full executable file name.
-      This means that if you have a command "custom_executable" in the path and type "custom" and press `<TAB>`, the shell should complete that to "custom_executable".
+      This means that if you have a command `custom_executable` in the path and type `custom` and press `<TAB>`, the shell should complete that to `custom_executable`.
 
       ### Tests
 
@@ -1049,17 +1051,17 @@ stages:
       ./your_program.sh
       ```
 
-      Before executing your shell, the tester will create an executable file named `custom_exe` and add its directory to the `PATH`.
+      Before executing your shell, the tester will create an executable file named `custom_executable` and add its directory to the `PATH`.
 
       The test will simulate the user typing the start of the external command and pressing `<TAB>`:
 
       1.  **Input:** `custom`<TAB>
-          *   The tester types "custom" and presses `<TAB>`. The tester expects that the prompt line changes to `custom_exe`.
+          *   The tester types "custom" and presses `<TAB>`. The tester expects that the prompt line changes to `custom_executable`.
 
-      The tester will verify that your shell correctly completes the command to the external executable file name and then runs the executable.
+      The tester will verify that your shell correctly completes the command to the external executable file name.
 
     marketing_md: |-
-       This stage extends your shell's power by enabling completion of external executables.
+      In this stage, you'll implement support for autocompleting external executables.
 
   - slug: "ac5"
     primary_extension_slug: "completions"
@@ -1083,30 +1085,30 @@ stages:
       ./your_program.sh
       ```
 
-      It will then set up a specific `PATH` and place executables `xyz_bar`, `xyz_baz`, and `xyz_quz` into different directories in the `PATH`. Finally, it will type `xyz_`, and then press the Tab key twice.
+      It will then set up a specific `PATH` and place multiple executables starting with a common prefix into different directories in the `PATH`. Finally, it will type the common prefix, and then press the Tab key twice.
 
       ```bash
       $ ./your_program.sh
       $ xyz_<TAB><TAB>
+      xyz_bar  xyz_baz  xyz_quz
+      $ xyz_
       ```
 
       The tester will verify that:
 
-      1. Your shell displays the prompt `$ xyz_` after receiving the partial command.
+      1. Your shell displays the prompt with the common prefix after receiving the partial command.
       2. Upon the first Tab key press, your shell prints a bell character.
-      3. Upon the second Tab key press, your shell prints `xyz_bar xyz_baz xyz_quz` to standard output.
-      4. The prompt line matches `xyz_bar  xyz_baz  xyz_quz` after printing matches.
-      5. Your shell doesn't modify the prompt line after completion when the command is incomplete.
+      3. Upon the second Tab key press, your shell prints the list of matching executables separated by 2 spaces, on the next line, and follow it with the prompt on a new line.
 
     marketing_md: |-
-      In this stage, you'll add to your shell's usability by implementing multiple command completions.
+      In this stage, you'll implement support for handling multiple completions.
 
   - slug: "ac6"
     primary_extension_slug: "completions"
     name: "Completion with arguments"
-    difficulty: medium
+    difficulty: hard
     description_md: |-
-      In this stage, you'll implement tab completion to handle cases with multiple matching executables where one is a prefix of another. 
+      In this stage, you'll extend your shell's tab completion to handle cases with multiple matching executables where one is a prefix of another. 
 
       When the user types a partial command and presses the Tab key, your shell should attempt to complete the command name. If there are multiple executable files in the PATH that match the prefix, and one of those matches is a prefix of another, then the shell should complete to the longest common prefix of all matching executables. If there is only one match after performing completion, then the shell should complete the command name as in previous stages.
 
@@ -1130,7 +1132,9 @@ stages:
       $ xyz_<TAB>
       $ xyz_foo_<TAB>
       $ xyz_foo_bar_<TAB>
+      $ xyz_foo_bar_baz 
       ```
+      Note: The prompt lines above are on the same line.
 
       The tester will verify that:
 
@@ -1142,4 +1146,4 @@ stages:
       6. The prompt line matches `$ xyz_foo_bar_baz ` after the final completion.
 
     marketing_md: |-
-      In this stage, you'll enhance the tab completion feature of your shell to handle cases where multiple matching executables share a common prefix.
+      In this stage, you'll implement support for handling multiple completions with common prefixes.