mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
166 lines
6.2 KiB
Markdown
166 lines
6.2 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/LineFormatter/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/LineFormatter/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/LineFormatter/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/LineFormatter/releases)
|
|
|
|
|
|
# LineFormatter
|
|
|
|
Arduino library to enhance the layout of tabular data on serial output,
|
|
|
|
|
|
# Description
|
|
|
|
LineFormatter is a wrapper class for Serial (and other streams) to enhance
|
|
layout of tabular data.
|
|
|
|
The class intercepts the **TAB (\t)** characters printed and replaces them with spaces to
|
|
the next defined tab-position. These positions can be created with **addTab(pos)**
|
|
for absolute positions and **addRelTab(n)** for relative positions.
|
|
|
|
Absolute tab positions must be added in **increasing** order as the class does not
|
|
check or sort the input. Adding the same tab position is not possible since 0.2.0.
|
|
Also position 0 will be ignored as tabStop.
|
|
|
|
The maximum number of tabs is defined by **MAX_TAB_STOPS** == 12 default.
|
|
This value can be overruled by -D compile flag or edited in the LineFormatter.h file.
|
|
|
|
All tab positions can be cleared in one call by **clearTabs()**.
|
|
Since 0.2.0 the library also supports **removeTab(pos)** to remove a single tab.
|
|
|
|
The function **autoNewLine(n)** prints a newline after every n lines automatically.
|
|
This makes it easier to count the lines in a table, e.g after every 10 lines.
|
|
Setting **n** to 0 disables this function.
|
|
|
|
The function **gotoPos(pos)** prints spaces until the cursor is on position **pos**.
|
|
If the current position is beyond **pos**, it does nothing (check the returned position!).
|
|
Besides for tabular data, this function can be used to make simple text based
|
|
graphs, e.g. a sine wave.
|
|
|
|
The function **repeat(n, s, nl)** which repeats a character or a string n times.
|
|
This is followed by **nl** newlines which is zero by default.
|
|
**repeat()** is useful to make separator lines or to print several newlines at once.
|
|
A simple histogram is easy to make.
|
|
|
|
The function **setMaxLength(n)** to cut off (brute force, no intelligence) lines
|
|
after n characters by injecting an extra newline. This prevents scrolling hundreds
|
|
of positions to the right.
|
|
Setting the value to 0 results in no maximum line length.
|
|
|
|
Note: the maximum line length is 255 as all internal positions are 8 bit.
|
|
A 16 bit lineFormatter is planned for future (on request).
|
|
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "LineFormatter.h"
|
|
```
|
|
|
|
#### Constructor
|
|
|
|
- **LineFormatter(Print\* stream = &Serial)** constructor.
|
|
Connects to a stream, default Serial.
|
|
- **reset()** reset internal variables to restart from default again.
|
|
|
|
|
|
#### Printing
|
|
|
|
- **size_t write(uint8_t c)** implements printing per character.
|
|
- **uint8_t gotoPos(uint8_t pos)** if position is smaller than pos, move to the right.
|
|
Returns the updated position.
|
|
- **void repeat(uint8_t n, char c, uint8_t newLine = 0)** repeat a char n times.
|
|
Typical used to create separation lines, or multiple line feeds.
|
|
The repeated string is optionally followed by a number of newlines.
|
|
- **void repeat(uint8_t n, const char\* str, uint8_t newLine = 0)** repeat a "string" n times.
|
|
The repeated string is optionally followed by a number of newlines.
|
|
Typical used to create separation lines.
|
|
|
|
|
|
#### Tab configuration
|
|
|
|
- **bool addTab(uint8_t n)** Add a tab at an absolute position.
|
|
Returns true on success.
|
|
Note: no tab can be set on position 0 (return false)
|
|
Note: existing tabs will be ignored (return false)
|
|
- **bool addRelTab(uint8_t n)** Add a tab at a relative position.
|
|
Returns true on success.
|
|
- **void clearTabs()** remove all the tabs.
|
|
- **bool removeTab(uint8_t pos)** remove a tab at given position.
|
|
Returns true if a tab exists at the position **pos**.
|
|
Returns false if no tab existed.
|
|
- **void tab(uint8_t n = 1)** print zero or more tabs, similar as e.g. "\t\t\t".
|
|
|
|
Note:
|
|
Removing a tab is non-reversible (for now), so one cannot insert a removed tab stop again.
|
|
Also replacing a tab can only be done by clear all the tabs and reinsert the new ones.
|
|
|
|
|
|
#### Line configuration
|
|
|
|
- **void setMaxLength(uint8_t maxPos)** set the maximum line length - bold cut off.
|
|
Will be disabled when set to 0.
|
|
Note: maximum line length == 255.
|
|
- **uint8_t getMaxLength()** return max line length set.
|
|
- **void setAutoNewLine(uint8_t n = 1)** n = 0 switches autoNewLine off.
|
|
- **uint8_t getAutoNewLine()** returns number of newlines set before.
|
|
|
|
|
|
#### Miscellaneous
|
|
|
|
For debugging and other purposes there are the following functions:
|
|
|
|
- **uint8_t getPos()** returns current position.
|
|
- **void resetLineCount()** sets internal lineCounter to zero.
|
|
- **uint32_t getLineCount()** returns current line number (since last reset).
|
|
- **uint8_t getTabCount()** get the number of tab positions.
|
|
- **uint8_t getTabStop(uint8_t n)** returns the position of the n-th tab.
|
|
- **void printRuler(uint8_t length)** prints a dotted line with 5 and 10 markers,
|
|
and # for tab positions.
|
|
Line is length long.
|
|
|
|
|
|
## Future
|
|
|
|
#### Must
|
|
|
|
- redo documentation misc/debug part
|
|
|
|
#### Should
|
|
|
|
- add sorting to **addTab()** 0.3.0?
|
|
- insert sort - bit like in removeTab()
|
|
- would allow dynamic inserting.
|
|
- add examples
|
|
- investigate correct working of maxPosition handling.
|
|
- investigate position 1 as tabStop?
|
|
- 0 is ignored but 1 is ambiguous
|
|
|
|
|
|
#### Could
|
|
|
|
- 0.3.0 ?
|
|
- addTab ==> addAbsoluteTab()
|
|
- addRelTab ==> addRelativeTab()
|
|
- error handling in addTab()?
|
|
- lineFormatter16
|
|
- or just make it 16 bit version to allow tables more than 255 chars wide
|
|
- uses more memory!
|
|
- separate class as 8 bit is everywhere
|
|
- right alignment for numbers
|
|
- point alignment for floats
|
|
- investigate macros again.
|
|
- filter for unprintable characters,
|
|
- isAscii() test
|
|
- define replace char, default point?
|
|
|
|
|
|
#### Wont
|
|
|
|
- check if print interface is completely covered.
|
|
- due to tab parsing it is, so no speed up.
|
|
|
|
|