Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
217 lines (187 loc) · 7.62 KB

DOCUMENTATION.md

File metadata and controls

217 lines (187 loc) · 7.62 KB

bullet : Documentation







👷 To fully customize your prompts, you'll have to take total control of formatting and colors. Here's what you need to know.

Table of Contents

General

Using bullet Objects

Always create an UI object with a prompt specified.

from bullet import Bullet, Check, YesNo, Input # and etc...
cli = Bullet(prompt = "Choose from the items below: ")  # Create a Bullet or Check object
result = cli.launch()  # Launch a prompt

Defining Choices

cli = Bullet(choices = ["first item", "second item", "third item"])

Customize Bullets, Checks, and Hidden Characters

cli = Bullet(bullet = "★")
cli = Check(check = "√")
cli = Password(hidden = "*")
cli = ScrollBar(pointer = "→")

You can also use emojis!

Customize Colors

It is recommended to EXPLICITLY specify ALL colors for an UI object.

from bullet import colors

🎨 The following colors (both background and foreground) are supported in bullets. Note that default is the color of your default terminal.

default, black, red, green, yellow, blue, magenta, cyan, white

🎨 Remember to specify foreground and background.

black_foreground = colors.foreground["black"]
white_background = colors.background["white"]

🎨 You can wrap a color with the bright function

bright_cyan = colors.bright(colors.foreground["cyan"])

🎨 Define the following colors when initializing the UI components.

  • Use foreground colors:
    • bullet_color
    • check_color
    • pointer_color
    • indicator_color
    • check_on_switch
    • word_color
    • word_on_switch
    • separator_color
  • Use background colors:
    • background_color
    • background_on_switch

Formatting

📐 Define the following UI components (not all is needed for some objects).

  • indent: distance from left-boundary to start of prompt.
  • pad_right: extended background length.
  • align: distance between bullet (or check) and start of prompt.
  • margin: distance between list item and bullets (or checks).
  • shift: number of new lines between prompt and first item.

Use Default Style Schemes

👷 Currently only styles for Bullet is supported.

from bullet import styles
client = Bullet(**styles.Greece)

bullet Objects

⌨️ Using Bullet Object

Single-choice prompt.

  • Define bullet when initializing Bullet object.
  • Move current position up and down using arrow keys.
  • Returns the chosen item after pressing enter.

⌨️ Using Check Object

Multiple-choice prompt.

  • Define check when initializing Check object.
  • Move current position up and down using arrow keys.
  • Check/Un-check an item by pressing space.
  • Returns the a list of chosen items after pressing enter.

⌨️ Using Input Object

Just vanilla user input.

  • strip: bool: whether to strip trailing spaces.
  • pattern: str: Default is "". If defined, user input should match pattern.

⌨️ Using YesNo Object

Guarded Yes/No question.

  • Only enter y/Y or n/N. Other invalid inputs will be guarded, and the user will be asked to re-enter.

⌨️ Using Password Object

Enter passwords.

  • Define hidden when initializing Password object. This would be the character shown on the terminal when passwords are entered.
  • In convention, space characters ' ' are guarded and should not be in a password.

⌨️ Using Numbers Object

Enter numeric values.

  • Non-numeric values will be guarded, and the user will be asked to re-enter.
  • Define type to cast return value. For example, type = float, will cast return value to float.

⌨️ Using Prompt Objects

Wrapping it all up.

Using VerticalPrompt Object

  • Stack bullet UI components into one vertically-rendered prompt.
  • Returns a list of tuples (prompt, result).
  • spacing: number of lines between adjacent UI components.
  • Or, if separator is defined, each UI will be separated by a sequence of separator characters.
  • See ./examples/prompt.py to get a better understanding.
cli = VerticalPrompt(
    [
        YesNo("Are you a student? "),
        Input("Who are you? "),
        Numbers("How old are you? "),
        Bullet("What is your favorite programming language? ",
              choices = ["C++", "Python", "Javascript", "Not here!"]),
    ],
    spacing = 1
)

result = cli.launch()

Using SlidePrompt Object

  • Link bullet UI components into a multi-stage prompt. Previous prompts will be cleared upon entering the next stage.
  • Returns a list of tuples (prompt, result).

For Prompt ojects, call summarize() after launching the prompt to print out user input.

⌨️ Using ScrollBar Object

Enhanced Bullet: Too many items? It's OK!

  • pointer: points to item currently selected.
  • up_indicator, down_indicator: indicators shown in first and last row of the rendered items.
  • height: maximum items rendered on terminal.
    • For example, your can have 100 choices (len(choices) = 100) but define height = 5.

More Customization: Extending Existing Prompts

See ./examples/check.py for the big picture of what's going on.

In bullet, you can easily inherit a base class (existing bullet objects) and create your customized prompt. This is done by introducing the keyhandler module to register user-defined keyboard events.

from bullet import keyhandler

Say you want the user to choose at least 1 and at most 3 items from a list of 5 items. You can inherit the Check class, and register a customized keyboard event as a method.

@keyhandler.register(NEWLINE_KEY)
def accept(self):
    # do some validation checks: chosen items >= 1 and <= 3.

Note that accept() is the method for all prompts to return user input. The binded keyboard event by default is NEWLINE_KEY pressed.

A List of Default Keyboard Events

See ./bullet/charDef.py

  • LINE_BEGIN_KEY : Ctrl + H
  • LINE_END_KEY: Ctrl + E
  • TAB_KEY
  • NEWLINE_KEY: Enter
  • ESC_KEY
  • BACK_SPACE_KEY
  • ARROW_UP_KEY
  • ARROW_DOWN_KEY
  • ARROW_RIGHT_KEY
  • ARROW_LEFT_KEY
  • INSERT_KEY
  • DELETE_KEY
  • END_KEY
  • PG_UP_KEY
  • PG_DOWN_KEY
  • SPACE_CHAR
  • INTERRUPT_KEY: Ctrl + C