- commit
- 8f60259291637d849077fd2a2e0b604dda318272
- parent
- 9047839dd90fd1f049c25c2c903bda429f69313e
- Author
- Tobias Bengfort <tobias.bengfort@posteo.de>
- Date
- 2020-07-12 18:44
add README
Diffstat
| A | README.md | 120 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 files changed, 120 insertions, 0 deletions
diff --git a/README.md b/README.md
@@ -0,0 +1,120 @@
-1 1 # boon - unix terminal framework
-1 2
-1 3 Boon is an alternative to curses. It occupies a similar level of abstraction
-1 4 (somewhere between terminfo and your application), but uses different concepts.
-1 5 It is just over 100loc and has no dependencies outside the standard library.
-1 6
-1 7 The high level API aims to be declarative and is partly inspired by react. The
-1 8 lines of the terminal are represented as a list of strings. On each update,
-1 9 this list is regenerated and compared to the previous version. Only the lines
-1 10 that have changed are rendered to the terminal.
-1 11
-1 12 Boon does not provide utilities for color and styling. You can either use the
-1 13 low level API or a third party library such as
-1 14 [colorama](https://github.com/tartley/colorama/) or
-1 15 [blessings](https://github.com/erikrose/blessings/).
-1 16
-1 17
-1 18 ## Example
-1 19
-1 20 ```python
-1 21 import boon
-1 22
-1 23 class Example(boon.App):
-1 24 def render(self):
-1 25 yield 'Hello World'
-1 26
-1 27 def on_key(self, key):
-1 28 if key == 'q':
-1 29 self.running = False
-1 30
-1 31 example = Example()
-1 32 example.run()
-1 33 ```
-1 34
-1 35
-1 36 ## High level API
-1 37
-1 38 ### `App.run()`
-1 39
-1 40 Call to start the main loop.
-1 41
-1 42 ### `App.running`
-1 43
-1 44 Set to `False` to stop the main loop.
-1 45
-1 46 ### `App.rows` / `App.cols`
-1 47
-1 48 The current size of the terminal.
-1 49
-1 50 ### `App.render()`
-1 51
-1 52 Overwrite to define your view. For every line in the UI, this functions should
-1 53 yield a string.
-1 54
-1 55 ### `App.on_key(key)`
-1 56
-1 57 Overwrite to react to key presses. `key` is a string containing either a
-1 58 character or an escape sequence. Boon contains constants for the most common
-1 59 escape sequences:
-1 60
-1 61 - `KEY_BACKSPACE`
-1 62 - `KEY_ESC`
-1 63 - `KEY_HOME`
-1 64 - `KEY_END`
-1 65 - `KEY_PPAGE`
-1 66 - `KEY_NPAGE`
-1 67 - `KEY_UP`
-1 68 - `KEY_DOWN`
-1 69 - `KEY_RIGHT`
-1 70 - `KEY_LEFT`
-1 71
-1 72 Note that boon reads all available input, so in rare occasions `key` might
-1 73 contain more than one key. This should not be an issue in practice though.
-1 74
-1 75
-1 76 ## Low level API
-1 77
-1 78 ### `get_cap(cap, *args) -> str`
-1 79
-1 80 Get a capability from the terminfo database. If stdout is not a tty or if the
-1 81 capability is not supported by the terminal this returns an empty string. The
-1 82 full list of capabilities is available in the [terminfo
-1 83 manpage](http://manpages.ubuntu.com/manpages/man5/terminfo.5.html)
-1 84
-1 85 ```python
-1 86 print(get_cap('setaf', 13) + 'foo' + get_cap('sgr0'))
-1 87 ```
-1 88
-1 89 ### `move(y, x)`
-1 90
-1 91 Move the cursor to the given position.
-1 92
-1 93 ### `get_size() -> (rows, cols)`
-1 94
-1 95 Get the current size of the terminal. This is more reliable than
-1 96 `get_cap('rows')` / `get_cap('cols')`.
-1 97
-1 98 ### `tty_restore(fd)`
-1 99
-1 100 Context manager that restores tty settings after the nested block.
-1 101
-1 102 ```python
-1 103 def getpass(prompt):
-1 104 fd = sys.stdin.fileno()
-1 105 with tty_restore(fd):
-1 106 flags = termios.tcgetattr(fd)
-1 107 flags[3] &= ~termios.ECHO
-1 108 termios.tcsetattr(fd, termios.TCSADRAIN, flags)
-1 109 return input(prompt)
-1 110 ```
-1 111
-1 112 ### `fullscreen()`
-1 113
-1 114 Context manager that enters cup and cbreak mode and also hides the cursor.
-1 115 Everything is restored to the previous state after the nested block.
-1 116
-1 117 ### `getch(timeout=0.5) -> string`
-1 118
-1 119 Reads from stdin. If no keys are available within the given timeout, `None` is
-1 120 returned. See `App.on_key()` for details on the return value.