Text as Tokens#

click-repl employs tokenization to represent text for suggestions and the bottom bar, enabling semantic coloring based on their significance and purpose.

This module uses the TokenizedFormattedText class to achieve this.

TokenizedFormattedText#

The TokenizedFormattedText class inherits its functionality from FormattedText. It extends it with additional methods to facilitate easier manipulation. This class defines text along with an assigned token class assigned as a token to uniquely identify from other text groups. This text tokenization is widely used in this module to give semantic colouring to certain text portions. Consequently, users can customize their prompt’s color scheme accordingly.

Refer to Formatted text docs from the python-prompt-toolkit module to learn more about creating unique colour schemes for your text.

TokenizedFormattedText objects are used to tokenize the text that goes in display and display_meta parameters of the ReplCompletion class, and also for text sent to the Marquee class.

Marquee#

Marquee is responsible for generating text in the bottom bar to appear in the style of <marquee> html element.

It’s constructor has 2 parameters -

  • prefix - The text that remains at the left-most end of the bottom bar, and remains static.

  • text - This text gets displayed in marquee style if the terminal width is insufficient to display the entire text. Otherwise, the entire text is displayed statically.

Note

Both of these parameters expect to recieve only objects of type TokenizedFormattedText, because it uses TokenizedFormattedText’s special methods to slice the text provided within the list of tokens.

Refer to TokenizedFormattedText API docs <click_repl.tokenizer.TokenizedFormattedText> to learn more about those methods.

Token Class Hierarchy#

A constant set of token classes is used to label text generated from various aspects of this module, and they are classified in a hierarchy.

  • Token class names labelling text that are used for displaying suggestions fall under the autocompletion-menu root class by default. Every token class used within ClickCompleter falls under this root class. The root class can be changed in the parent_token_class_name attribute of ClickCompleter.

  • Similary, Token class names labeling text that are generated in bottom bar, falls under the bottom-bar root class by default. The root class can be changed in the parent_token_class_name attribute of BottomBar.

click-repl has default styles for text with certain tokens. These values can be overridden in the style_config_dict parameter of the get_default_prompt_kwargs() method.

Each token class is used along with its parent classes. For example, The token autocompletion-menu.parameter.option.name represents the below style format hierarchy:

autocompletion-menu
└─ parameter
   └─ option
      └─ name

This implies that the token that has class autocompletion-menu.parameter.option.name inherits its style from the classes autocompletion-menu, parameter, option, and name. However, each parent class’s style can be overridden by its child token class. In other words, the style configuration defined for autocompletion-menu can be overridden in parameter, option, or name classes.

Note

Token Class Hierarchy Tree#

Refer to (style, text) tuples to learn more about the styles that you can use for text.

For text in suggestions, each of these token classes represent:

autocompletion-menu - Parent/root class name for token classes that are used in autocompletion
│
├─ parameter - Parameter based objects
│  │
│  └─ type - ParamType based objects
│     │
│     ├─ bool - BOOL
│     │  ├─ totrue - Option name that has action as store_true (Default style: fg:#44e80e)
│     │  └─ tofalse - Option name that has action as store_false (Default style: fg:red)
│     │
│     ├─ path - Filesystem path (used in Path and File param types)
│     │  ├─ directory - Filesystem path of a directory
│     │  └─ file - Filesystem path of a file
│     │
│     ├─ range - Number Range based param types
│     │  ├─ integer - IntRange object
│     │  └─ float - FloatRange object
│     │
│     ├─ argument - Argument object
│     │  └─ name - Argument name
│     │
│     └─ option - Option object
│        └─ name - Option name
│           └─ separator - Character that's used to separate joined option names
│
├─ command - Command based objects
│  └─ name - Command name
│
├─ group - Group based objects
│  └─ name - Group name
│
├─ internalcommand - Internal Commands
│  └─ name - Name of the internal command
│
├─ symbol - Non-alphanumeric characters
│  └─ bracket - Brackets and Parentheses
│
└─ space - Space character

For text in bottom bar, each of these token classes represent:

bottom-bar - Parent/root class name for token classes that are used in bottom bar
│
├─ group - Group based objects
│  ├─ name - Group name (Default style: bold)
│  ├─ type - Group object's class name (Default style: bold)
│  └─ metavar - Metavar template text of the group
│
├─ command - Command based objects
│  ├─ name - Command name (Default style: bold)
│  ├─ type - (Default style: bold)
│  └─ metavar - Metavar template text of commands
│
├─ paramter - Parameter based objects
│  │
│  ├─ name - Name of the parameter
│  ├─ nargs - nargs of the paramter
│  │  └─ counter - counting option (Default style: fg:green)
│  │
│  ├─ usage - Usage state of the parameter
│  │  ├─ inuse - Parameter is now currently receiving values (Default style: bold underline)
│  │  ├─ used - Parameter has got its values (Default style: strike)
│  │  └─ unused - Parameter haven't received its values
│  │
│  ├─ type - ParamType based objects
│  │  │
│  │  ├─ usage - Usage state of the param type
│  │  │  ├─ inuse - Parameter is now currently receiving values. (Default style: bold underline)
│  │  │  ├─ used - Parameter has got its values. (Default style: strike)
│  │  │  └─ unused - Parameter haven't received its values
│  │  │
│  │  ├─ string - STRING object
│  │  ├─ integer - INT object
│  │  ├─ float - FLOAT object
│  │  ├─ range - Number Range based param types
│  │  │  ├─ integer - IntRange object
│  │  │  ├─ float - FloatRange object
│  │  │  └─ descriptor - Description text about the number range based param type
│  │  │
│  │  ├─ bool - BOOL object
│  │  ├─ choice - Choice object
│  │  ├─ composite - CompositeParamType objects
│  │  ├─ datetime - DateTime object
│  │  ├─ file - File object
│  │  ├─ path - Path object
│  │  ├─ unprocessed - UNPROCESSED object
│  │  └─ uuid - UUID object
│  │
│  ├─ argument - Argument object
│  │  └─ name - Argument name
│  │
│  └─ option - Option object
│     └─ name - Option name
│
├─ symbol - Non-alphanumeric characters
│  └─ bracket - Brackets and Parentheses
│
├─ error - Errors that are raised while generating auto-completions
│  ├─ exception-class-name - Class name of the Exception raised
│  └─ message - Message in the Exception class
│
├─ space - Space character
└─ ellipsis - Ellipsis (...) text that's used to represent None values