feat: stylize text inside backticks when appearing in example description (#254)

* Stylize italics in helptext using ANSI escapes

* Ensure example styles are still applied and not completely reset

* Remove unused import

---------

Co-authored-by: K.B.Dharun Krishna <[email protected]>

Author: kyluca

tests/data/jq_rendered

@@ -10,7 +10,7 @@
   - Output all elements from arrays (or all the values from objects) in a JSON file:
     jq '.[]' file.json
 
-  - Read JSON objects from a file into an array, and output it (inverse of `jq .[]`):
+  - Read JSON objects from a file into an array, and output it (inverse of jq .[]):
     jq --slurp . file.json
 
   - Output the first element in a JSON file:
@@ -19,7 +19,7 @@
   - Output the value of a given key of each element in a JSON text from stdin:
     cat file.json | jq 'map(.key_name)'
 
-  - Output the value of multiple keys as a new JSON object (assuming the input JSON has the keys `key_name` and `other_key_name`):
+  - Output the value of multiple keys as a new JSON object (assuming the input JSON has the keys key_name and other_key_name):
     cat file.json | jq '{my_new_key: .key_name, my_other_key: .other_key_name}'
 
   - Combine multiple filters:

tldr.py

@@ -369,6 +369,8 @@ def get_page(
 
 LEADING_SPACES_NUM = 2
 
+EXAMPLE_SPLIT_REGEX = re.compile(r'(?P<example>`.+?`)')
+EXAMPLE_REGEX = re.compile(r'(?:`)(?P<example>.+?)(?:`)')
 COMMAND_SPLIT_REGEX = re.compile(r'(?P<param>{{.+?}*}})')
 PARAM_REGEX = re.compile(r'(?:{{)(?P<param>.+?)(?:}})')
 
@@ -414,6 +416,11 @@ def colors_of(key: str) -> Tuple[str, str, List[str]]:
 
 
 def output(page: str, plain: bool = False) -> None:
+    def emphasise_example(x: str) -> str:
+        # Use ANSI escapes to enable italics at the start and disable at the end
+        # Also use the color yellow to differentiate from the default green
+        return "\x1B[3m" + colored(x.group('example'), 'yellow') + "\x1B[23m"
+
     if not plain:
         print()
     for line in page:
@@ -422,23 +429,48 @@ def output(page: str, plain: bool = False) -> None:
         if plain:
             print(line)
             continue
+
         elif len(line) == 0:
             continue
+
+        # Handle the command name
         elif line[0] == '#':
             line = ' ' * LEADING_SPACES_NUM + \
                 colored(line.replace('# ', ''), *colors_of('name')) + '\n'
             sys.stdout.buffer.write(line.encode('utf-8'))
+
+        # Handle the command description
         elif line[0] == '>':
             line = ' ' * (LEADING_SPACES_NUM - 1) + \
                 colored(
                     line.replace('>', '').replace('<', ''),
                     *colors_of('description')
                 )
             sys.stdout.buffer.write(line.encode('utf-8'))
+
+        # Handle an example description
         elif line[0] == '-':
-            line = '\n' + ' ' * LEADING_SPACES_NUM + \
-                colored(line, *colors_of('example'))
+
+            # Stylize text within backticks using yellow italics
+            if '`' in line:
+                elements = ['\n', ' ' * LEADING_SPACES_NUM]
+
+                for item in EXAMPLE_SPLIT_REGEX.split(line):
+                    item, replaced = EXAMPLE_REGEX.subn(emphasise_example, item)
+                    if not replaced:
+                        item = colored(item, *colors_of('example'))
+                    elements.append(item)
+
+                line = ''.join(elements)
+
+            # Otherwise, use the same colour for the whole line
+            else:
+                line = '\n' + ' ' * LEADING_SPACES_NUM + \
+                    colored(line, *colors_of('example'))
+
             sys.stdout.buffer.write(line.encode('utf-8'))
+
+        # Handle an example command
         elif line[0] == '`':
             line = line[1:-1]  # Remove backticks for parsing