Accept formatted text in the display text of completions.

Author: jonathanslenders

examples/prompts/auto-completion/colored-completions-with-formatted-text.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+"""
+Demonstration of a custom completer class and the possibility of styling
+completions independently by passing formatted text objects to the "display"
+and "display_meta" arguments of "Completion".
+"""
+from __future__ import unicode_literals
+from prompt_toolkit.completion import Completion, Completer
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.shortcuts import prompt, CompleteStyle
+
+
+animals = [
+ 'alligator', 'ant', 'ape', 'bat', 'bear', 'beaver', 'bee', 'bison',
+ 'butterfly', 'cat', 'chicken', 'crocodile', 'dinosaur', 'dog', 'dolphin',
+ 'dove', 'duck', 'eagle', 'elephant',
+]
+
+animal_family = {
+ 'alligator': 'reptile',
+ 'ant': 'insect',
+ 'ape': 'mammal',
+ 'bat': 'mammal',
+ 'bear': 'mammal',
+ 'beaver': 'mammal',
+ 'bee': 'insect',
+ 'bison': 'mammal',
+ 'butterfly': 'insect',
+ 'cat': 'mammal',
+ 'chicken': 'bird',
+ 'crocodile': 'reptile',
+ 'dinosaur': 'reptile',
+ 'dog': 'mammal',
+ 'dolphin': 'mammal',
+ 'dove': 'bird',
+ 'duck': 'bird',
+ 'eagle': 'bird',
+ 'elephant': 'mammal',
+}
+
+family_colors = {
+ 'mammal': 'ansimagenta',
+ 'insect': 'ansigreen',
+ 'reptile': 'ansired',
+ 'bird': 'ansiyellow',
+}
+
+meta = {
+ 'alligator': HTML('An <ansired>alligator</ansired> is a <u>crocodilian</u> in the genus Alligator of the family Alligatoridae.'),
+ 'ant': HTML('<ansired>Ants</ansired> are eusocial <u>insects</u> of the family Formicidae.'),
+ 'ape': HTML('<ansired>Apes</ansired> (Hominoidea) are a branch of Old World tailless anthropoid catarrhine <u>primates</u>.'),
+ 'bat': HTML('<ansired>Bats</ansired> are mammals of the order <u>Chiroptera</u>.'),
+ 'bee': HTML('<ansired>Bees</ansired> are flying <u>insects</u> closely related to wasps and ants.'),
+ 'beaver': HTML('The <ansired>beaver</ansired> (genus Castor) is a large, primarily <u>nocturnal</u>, semiaquatic <u>rodent</u>.'),
+ 'bear': HTML('<ansired>Bears</ansired> are carnivoran <u>mammals</u> of the family Ursidae.'),
+ 'butterfly': HTML('<ansiblue>Butterflies</ansiblue> are <u>insects</u> in the macrolepidopteran clade Rhopalocera from the order Lepidoptera.'),
+ # ...
+}
+
+
+class AnimalCompleter(Completer):
+ def get_completions(self, document, complete_event):
+ word = document.get_word_before_cursor()
+ for animal in animals:
+ if animal.startswith(word):
+ if animal in animal_family:
+ family = animal_family[animal]
+ family_color = family_colors.get(family, 'default')
+
+ display = HTML(
+ '%s<b>:</b> <ansired>(<' + family_color + '>%s</' + family_color + '>)</ansired>'
+ ) % (animal, family)
+ else:
+ display = animal
+
+ yield Completion(
+ animal,
+ start_position=-len(word),
+ display=display,
+ display_meta=meta.get(animal)
+ )
+
+
+def main():
+ # Simple completion menu.
+ print('(The completion menu displays colors.)')
+ prompt('Type an animal: ', completer=AnimalCompleter())
+
+ # Multi-column menu.
+ prompt('Type an animal: ', completer=AnimalCompleter(),
+ complete_style=CompleteStyle.MULTI_COLUMN)
+
+ # Readline-like
+ prompt('Type an animal: ', completer=AnimalCompleter(),
+ complete_style=CompleteStyle.READLINE_LIKE)
+
+
+if __name__ == '__main__':
+ main()

prompt_toolkit/completion/base.py

@@ -23,10 +23,10 @@ class Completion(object):
  :param start_position: Position relative to the cursor_position where the
  new text will start. The text will be inserted between the
  start_position and the original cursor position.
- :param display: (optional string) If the completion has to be displayed
- differently in the completion menu.
- :param display_meta: (Optional string) Meta information about the
- completion, e.g. the path or source where it's coming from.
+ :param display: (optional string or formatted text) If the completion has
+ to be displayed differently in the completion menu.
+ :param display_meta: (Optional string or formatted text) Meta information
+ about the completion, e.g. the path or source where it's coming from.
  This can also be a callable that returns a string.
  :param style: Style string.
  :param selected_style: Style string, used for a selected completion.
@@ -36,19 +36,18 @@ def __init__(self, text, start_position=0, display=None, display_meta=None,
  style='', selected_style=''):
  assert isinstance(text, text_type)
  assert isinstance(start_position, int)
- assert display is None or isinstance(display, text_type)
- assert display_meta is None or isinstance(display_meta, text_type)
  assert isinstance(style, text_type)
  assert isinstance(selected_style, text_type)
 
+ from prompt_toolkit.formatted_text import to_formatted_text
  self.text = text
  self.start_position = start_position
  self._display_meta = display_meta
 
  if display is None:
- self.display = text
- else:
-  self.display = display
+ display = text
+
+ self.display = to_formatted_text(display)
 
  self.style = style
  self.selected_style = selected_style
@@ -74,18 +73,23 @@ def __eq__(self, other):
  def __hash__(self):
  return hash((self.text, self.start_position, self.display, self._display_meta))
 
+ @property
+ def display_text(self):
+ " The 'display' field as plain text. "
+ from prompt_toolkit.formatted_text import fragment_list_to_text
+ return fragment_list_to_text(self.display)
+
  @property
  def display_meta(self):
  " Return meta-text. (This is lazy when using a callable). "
- meta = self._display_meta
+ from prompt_toolkit.formatted_text import to_formatted_text
+ return to_formatted_text(self._display_meta)
 
- if meta is None:
- return ''
-
- if callable(meta):
- return meta()
-
- return meta
+ @property
+ def display_meta_text(self):
+ " The 'meta' field as plain text. "
+ from prompt_toolkit.formatted_text import fragment_list_to_text
+ return fragment_list_to_text(self.display_meta)
 
  def new_completion_from_position(self, position):
  """

prompt_toolkit/completion/word_completer.py

@@ -14,7 +14,8 @@ class WordCompleter(Completer):
 
  :param words: List of words or callable that returns a list of words.
  :param ignore_case: If True, case-insensitive completion.
- :param meta_dict: Optional dict mapping words to their meta-information.
+ :param meta_dict: Optional dict mapping words to their meta-text. (This
+ should map strings to strings or formatted text.)
  :param WORD: When True, use WORD characters.
  :param sentence: When True, don't complete by comparing the word before the
  cursor, but by comparing all the text before the cursor. In this case,

prompt_toolkit/key_binding/bindings/completion.py

@@ -85,7 +85,7 @@ def _display_completions_like_readline(app, completions):
  # completions. (Keep in mind that completions are displayed
  # alphabetically column-wise.)
  max_compl_width = min(term_width,
- max(get_cwidth(c.text) for c in completions) + 1)
+ max(get_cwidth(c.display_text) for c in completions) + 1)
  column_count = max(1, term_width // max_compl_width)
  completions_per_page = column_count * (term_height - 1)
  page_count = int(math.ceil(len(completions) / float(completions_per_page)))
@@ -107,9 +107,11 @@ def display(page):
  try:
  completion = page_columns[c][r]
 
- result.extend(to_formatted_text(
- completion.text.ljust(max_compl_width),
- style=completion.style))
+ result.extend(to_formatted_text(completion.display, style=completion.style))
+
+ # Add padding.
+ padding = max_compl_width - get_cwidth(completion.display_text)
+ result.append((completion.style, ' ' * padding,))
  except IndexError:
  pass
  result.append(('', '\n'))