diff --git a/.gitignore b/.gitignore index ca81134..186a08e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ course-definition-tester .history/ # MacOS -.DS_Store \ No newline at end of file +.DS_Store diff --git a/course-definition.yml b/course-definition.yml index 76735e8..77e2377 100644 --- a/course-definition.yml +++ b/course-definition.yml @@ -68,6 +68,17 @@ extensions: Along the way, you'll learn about how to implement the `-o` flag. + - slug: "highlighting" + name: "Highlighting" + description_markdown: | + In this challenge extension, you'll add support for [highlighting][1] to your Grep implementation. + + Along the way, you'll learn about [ANSI escape codes][2], and more. + + [1]: https://linuxcommando.blogspot.com/2007/10/grep-with-color-output.html + [2]: https://en.wikipedia.org/wiki/ANSI_escape_code + + - slug: "file-search" name: "File Search" description_markdown: | @@ -356,3 +367,39 @@ stages: difficulty: medium marketing_md: |- In this stage, you'll add support for processing multiple input lines to print all matching texts. + + # Highlighting + - slug: "bm2" + primary_extension_slug: "highlighting" + name: "Highlighting a single match" + difficulty: easy + marketing_md: |- + In this stage, you'll add support for highlighting a single match in your grep implementation. + + - slug: "eq0" + primary_extension_slug: "highlighting" + name: "Highlighting multiple matches" + difficulty: easy + marketing_md: |- + In this stage, you'll add support for highlighting multiple matches in your grep implementation. + + - slug: "wg2" + primary_extension_slug: "highlighting" + name: "Highlighting in multiple lines" + difficulty: easy + marketing_md: |- + In this stage, you'll add support for highlighting matches in multiple lines. + + - slug: "jk4" + primary_extension_slug: "highlighting" + name: "Disabling highlighting" + difficulty: easy + marketing_md: |- + In this stage, you'll add support for disabling the highlighting in your grep implementation using the `never` coloring option. + + - slug: "na5" + primary_extension_slug: "highlighting" + name: "Auto highlighting option" + difficulty: medium + marketing_md: |- + In this stage, you'll add support for `auto` coloring option in the `--color` flag in your grep implementation. diff --git a/stage_descriptions/highlighting-01-bm2.md b/stage_descriptions/highlighting-01-bm2.md new file mode 100644 index 0000000..2e609ca --- /dev/null +++ b/stage_descriptions/highlighting-01-bm2.md @@ -0,0 +1,81 @@ +In this stage, you'll add support for highlighting a single match in your grep implementation. + +### Highlighting the matched text + +When `--color=always` option is used with grep, it always highlights the matched text in its output. + +Example usage: + + +
+$ echo -n "I have 1 apple" | grep --color=always -E '\d'
+I have 1 apple
+
+ + +Grep uses [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) to add color to terminal output. These are special character sequences that terminals interpret as formatting commands rather than regular text. + +The default color used by grep for the matched text is bold red. For example, grep uses the following ANSI escape sequences for wrapping the matched text: + +``` +\033[01;31m +... +\033[m +``` + +**Exaple Opening Sequence: `\033[01;31m`** + +| Component | Meaning | +|-----------|---------| +| `\033` | Escape character that introduces the ANSI control sequence | +| `[` | Start marker for [Select Graphic Rendition (SGR)](https://vt100.net/docs/vt510-rm/SGR.html) parameters | +| `01;31` | SGR codes: `01` = bold/bright text, `31` = red foreground color (separated by `;`) | +| `m` | Terminates the SGR sequence | + +**Example Closing Sequence: `\033[m`** + +| Component | Meaning | +|-----------|---------| +| `\033` | Escape character that introduces the ANSI control sequence | +| `[` | Start marker for SGR parameters | +| *(empty)* | No parameters = reset all attributes to default | +| `m` | Terminates the SGR sequence | + +### Tests + +The tester will execute your program like this: + + +
+$ echo -n "I have 3 apples" | grep --color=always -E '\d'
+I have 3 apples
+
+ + +If the input does not match the pattern, your program must: +- Exit with the code 1 +- Exit with no printed output + +If the input text matches the pattern, your program must: +- Exit with the code 0 +- Print the input text to the standard output +- Highlight the matched text in the input using the grep's default color. + +### Notes + +1. You only need to handle the case of single match. We'll get to highlighting multiple matches in the later stages. + +2. The matched text should highlighted using the bold (`01`) and red (`31`) attributes. You may use any combination of ANSI codes to achieve this highlighting effect. For example, to produce the following output: + + +
+hellomatchedworld
+
+ + +Any of the following sequences can be used + +``` +hello\033[31;01mmatched\033[mworld +hello\033[01;31mmatched\033[mworld +``` \ No newline at end of file diff --git a/stage_descriptions/highlighting-02-eq0.md b/stage_descriptions/highlighting-02-eq0.md new file mode 100644 index 0000000..31fd8b6 --- /dev/null +++ b/stage_descriptions/highlighting-02-eq0.md @@ -0,0 +1,44 @@ +In this stage, you'll add support for highlighting multiple matches in your grep implementation. + +### Highlighting multiple matches + +Grep highlights all the matching texts it can find in each line. + +Example usage: + + +
+$ echo -n "dogs and cats are pets" | grep --color=always -E '(dogs|cats)'
+dogs and cats are pets
+
+ + +### Tests + +The tester will execute your program like this: + + +
+$ echo -n "jekyll and hyde" | grep --color=always -E '(jekyll|hyde)'
+jekyll and hyde
+

+$ echo -n "2025" | grep --color=always -E '\d'
+2025
+ + +If the input does not match the pattern, your program must: +- Exit with the code 1 +- Exit with no printed output + +If the input text matches the pattern, your program must: +- Exit with the code 0 +- Print the input text to the standard output +- Highlight all the matched texts in the input using the grep's default color. + +### Notes + +- You only need to handle the case of single line. We'll get to highlighting matches in multiple lines in the later stages. + +- The tester accepts multiple valid ANSI-encoded representations of the same highlighted text. To display the bold red text: 2025, any equivalent combination is acceptable. Example of valid ANSI sequences: + - `\033[01;31m2025\033[m` + - `\033[31;01m2025\033[m` diff --git a/stage_descriptions/highlighting-03-wg2.md b/stage_descriptions/highlighting-03-wg2.md new file mode 100644 index 0000000..f093beb --- /dev/null +++ b/stage_descriptions/highlighting-03-wg2.md @@ -0,0 +1,46 @@ +In this stage, you'll add support for highlighting matches in multiple lines. + +### Highlighting multiple matches + +Grep highlights all the matching texts it can find in each line. + +Example usage: + + +
+$ echo -n "dogs and cats are pets\ndogs are nice" | grep --color=always -E '(dogs|cats)'
+dogs and cats are pets
+dogs are nice
+
+ + +### Tests + +The tester will execute your program like this: + + +
+$ echo -n "Tiger in the wild\nBird in the sky" | grep --color=always -E '(Tiger|Bird)'
+Tiger in the wild
+Bird in the sky
+

+$ echo -n "Now: 2025\nNext: 2026" | grep --color=always -E '\d\d\d\d'
+2025
+2026
+
+ + +If the input does not match the pattern, your program must: +- Exit with the code 1 +- Exit with no printed output + +If the input text matches the pattern, your program must: +- Exit with the code 0 +- Print each line that contains the match +- Highlight every match in every printed line + +### Notes + +- The tester accepts multiple valid ANSI-encoded representations of the same highlighted text. To display the bold red text: apple, any equivalent combination is acceptable. Example of valid ANSI sequences: + - `\033[01;31mapple\033[m` + - `\033[31;01mapple\033[m` diff --git a/stage_descriptions/highlighting-04-jk4.md b/stage_descriptions/highlighting-04-jk4.md new file mode 100644 index 0000000..194738d --- /dev/null +++ b/stage_descriptions/highlighting-04-jk4.md @@ -0,0 +1,30 @@ +In this stage, you'll add support for disabling the highlighting in your grep implementation using the `never` coloring option. + +### The `--color=never` option + +When a line is matched, grep only prints the matched line to the standard output. It does not highlight the matched text. + +Example usage: + +```bash +$ echo -n "Sally has 3 parrots" | grep --color=never -E "par+ots?" +Sally has 3 parrots +``` + +### Tests + +The tester will execute your program like this: + +```bash +$ echo -n "I have 5 vegetables" | grep --color=never -E '\d' +I have 5 vegetables +``` + +If the input matches the pattern, your program must: +- Exit with the code 0 +- Print the input line to the standard output +- No highlights should be placed in the output text because `--color=never` option is being used. + +If the input does not match the pattern, your program must: +- Exit with the code 1 +- Exit with no printed output \ No newline at end of file diff --git a/stage_descriptions/highlighting-05-na5.md b/stage_descriptions/highlighting-05-na5.md new file mode 100644 index 0000000..91c9241 --- /dev/null +++ b/stage_descriptions/highlighting-05-na5.md @@ -0,0 +1,82 @@ +In this stage, you'll add support for `auto` coloring option in the `--color` flag in your grep implementation. + +### The `auto` color option + +When `--color=auto` option is used with grep, it behaves in the following manner: + +- If the output stream is a [TTY device](https://www.ibm.com/docs/en/aix/7.1.0?topic=communications-tty-terminal-device), like the terminal, highlighting is enabled. + +- If the output stream is not a TTY device, for example, the output is piped to another command, or being redirected to a non-TTY device, highlighting is disabled. + +Example usage: + + +
+$ echo -n "I have 3 cows" | grep --color=auto -E 'cows'
+I have 3 cows
+$ echo -n "I have 4 cows" | grep --color=auto -E 'cows' >> /dev/tty
+I have 4 cows
+
+ + +The output text is highlighted in this case since the output in both cases is a TTY device. + +When the output stream is piped to another command, or redirected to a non-TTY device, the ANSI highlighting sequences are not placed in the output text. + +```bash +# Output stream is piped to another command +$ echo -n "I have 3 apples" | grep --color=auto -E '\d' | hexdump -C +00000000 49 20 68 61 76 65 20 33 20 61 70 70 6c 65 73 0a |I have 3 apples.| +00000010 + +# Output stream is redirected to a non-TTY device +$ echo -n "I have 4 apples" | grep --color=auto -E '\d' >> output.txt + +$ hexdump -C output.txt +00000000 49 20 68 61 76 65 20 34 20 61 70 70 6c 65 73 0a |I have 4 apples.| +00000010 +``` + +### Tests + +The tester will execute your program like this: + + +
+$ echo -n "I have 4 cats" | grep --color=auto -E 'cats'
+I have 4 cats
+$ echo -n "I have 5 cats" | grep --color=auto -E 'cats' >> /dev/tty
+I have 5 cats
+
+ + +If the input does not match the pattern, your program must: +- Exit with the code 1 + +If the input text matches the pattern, your program must: +- Exit with the code 0 +- Print the input text to the standard output +- The matched text in the output should be highlighted + +The tester will also execute your program like this: + +```bash +# Redirection to a non-tty device +$ echo -n "I have 3 horses" | grep --color=auto -E '\d' >> file.txt + +# Piping to another command +$ echo -n "He has 9 rabbits" | grep --color=auto -E '\d' | another_command +``` + +For both of these cases, +If the input does not match the pattern, your program must: +- Exit with the code 1 +- Exit with no printed output + +If the input text matches the pattern, your program must exit with the code 0 and +- The input text should be written to the file `file.txt`, or be supplied to another command, depending on the case. +- The ANSI escape sequence for highlighting should not be present inside the file, or supplied to another command, depending on the case. + +### Notes + +- You might find it helpful to use the equivalent of [`isatty()`](https://man7.org/linux/man-pages/man3/isatty.3.html) function in your programming language to check whether the output stream is a TTY device. \ No newline at end of file