| simpletext library v0.99.1 Compact variations of put/get write/read and print/scan for smaller program sizes

- Main Page
- Data Structures
- Files

- File List
- Globals

Data Structures | Typedefs | Functions
simpletext.h File Reference

This library provides a collection of functions for communicating with text devices such as SimpleIDE Terminal, serial peripheral devices, and even VGA displays. Libraries like serial, fdserial, and vgatext return pointer/identifiers that can be used with this library's dprint, dscan, and write/read function parameters that have text_t types. The identifier allows the application's code to specify which connection to use for sending and receiving formatted text. More...

`#include <propeller.h>`
`#include "serial.h"`
`#include <stdarg.h>`

Go to the source code of this file.

## Data Structures
struct | text_struct
| Structure that contains data used by simple text device libraries. More...

## Typedefs
typedef struct text_struct | text_t
| Structure that contains data used by simple text device libraries.
typedef text_t | terminal

## Functions
int | print (const char *format,...) __attribute__((format(printf
| Print format "..." args to the default simple terminal device. The output is limited to 256 bytes.
int int | scan (const char *fmt,...) __attribute__((format(printf
| Convert formatted simple terminal input to the "..." args. The input is limited to 256 bytes.
int int int | sprint (char *buffer, const char *format,...) __attribute__((format(printf
| Print format "..." args to the output buffer. The output buffer must be big enough for the output.
int int int int | sscan (const char *buffer, const char *fmt,...) __attribute__((format(printf
| Convert formatted buffer to the "..." args.
Print/Scan for Device Communication
int | dprint (text_t *device, const char *format,...) __attribute__((format(printf
| Print format "..." args to the device The output is limited to 256 bytes.
int int | dscan (text_t *device, const char *fmt,...) __attribute__((format(printf
| Convert formatted device input to the "..." args. The input is limited to 256 bytes.
Integer-Only Versions
For reduced program sizes if no floating point values are printed/scanned.
int | printi (const char *format,...) __attribute__((format(printf
| Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int | scani (const char *fmt,...) __attribute__((format(printf
| Convert formatted simple terminal input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.
int int int | dprinti (text_t *device, const char *format,...) __attribute__((format(printf
| Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int int int | dscani (text_t *device, const char *fmt,...) __attribute__((format(printf
| Convert formatted device input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.
int int int int int | sprinti (char *buffer, const char *format,...) __attribute__((format(printf
| Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.
int int int int int int | sscani (const char *buffer, const char *fmt,...) __attribute__((format(printf
| Convert formatted buffer to the "..." args. This version does not provide floating point conversions.
Output to Terminal
void | putChar (char c)
| Print a char to the debug port.
int | putStr (const char *str)
| Print string to the debug port.
void | putDec (int value)
| Print string representation of a decimal number to the debug port.
void | putFloat (float value)
| Print string representation of a 32 bit floating point number to the debug port.
void | putBin (int value)
| Print string representation of a binary number to the debug port.
void | putHex (int value)
| Print string representation of a hexadecimal number to the debug port.
int | putStrLen (char *str, int width)
| Send a string with a certain number of characters.
void | putDecLen (int value, int width)
| Print string representation of a decimal number to the debug port.
void | putFloatPrecision (float value, int width, int precision)
| Print string representation of a 32 bit floating point number to the debug port with a fixed number of digits.
void | putBinLen (int value, int digits)
| Print string representation of a binary number to debug port with a fixed number of digits.
void | putHexLen (int value, int digits)
| Print string representation of a hexadecimal number to the debug port with a fixed number of digits.
int | putln (const char *str)
| Print string + new line on the transmit debug port.
int | putLine (const char *str)
| Print string + new line on the transmit debug port. This is an alias of putln.
Input from Terminal
int | getBin (void)
| Get binary number from the debug port.
int | getChar (void)
| Get char from the debug port.
int | getDec (void)
| Get decimal number from the debug port.
float | getFloat (void)
| Get floating point number from the debug port.
int | getHex (void)
| Get hexadecimal number from the debug port.
char * | getStr (char *buffer, int max)
| Get string of chars from the debug port.
Output to Device
void | writeChar (text_t *device, char c)
| Send a character to the device.
int | writeStr (text_t *device, char *str)
| Send a string to the device.
void | writeDec (text_t *device, int value)
| Print string representation of a decimal number to output.
void | writeFloat (text_t *device, float value)
| Print string representation of a 32 bit floating point number to device.
void | writeBin (text_t *device, int value)
| Print string representation of a binary number to the receive device.
void | writeHex (text_t *device, int value)
| Print string representation of a hexadecimal number to output device.
int | writeStrLen (text_t *device, char *str, int width)
| Send a string to the device.
void | writeDecLen (text_t *device, int value, int width)
| Print string representation of a decimal number to output device with a fixed number of digits.
void | writeFloatPrecision (text_t *device, float value, int width, int precision)
| Print string representation of a 32 bit floating point number to device with a certain number of decimal point digits.
void | writeBinLen (text_t *device, int value, int digits)
| Print string representation of a binary number to output with a fixed number of digits.
void | writeHexLen (text_t *device, int value, int digits)
| Print string representation of a hexadecimal number to output device with a fixed number of digits.
int | writeLine (text_t *device, char *str)
| Send a string + new line to the device.
Input from Device
int | readChar (text_t *device)
| Get char from the device.
char * | readStr (text_t *device, char *buffer, int max)
| Get string of chars from the device.
int | readDec (text_t *device)
| Get decimal number from the device.
float | readFloat (text_t *device)
| Get floating point number from the device.
int | readBin (text_t *device)
| Get binary number from the device.
int | readHex (text_t *device)
| Get hexadecimal number from the device.
For Passing Terminal Control between Cogs and/or Devices
terminal * | simpleterm_open (void)
| Reopens the SimpleIDE Terminal connection if it was closed previously. The SimpleIDE Terminal connection transmits on P30 and receives on P31 at 115200 bps. The port is a simple serial driver running in the same cog, and does not buffer bytes.
void | simpleterm_close (void)
| Closes the SimpleIDE Terminal connection in one cog so that it can be opened in another cog with simpleterm_open, fdserial_open(30, 31, 0, 115200), or some other driver.
terminal * | simpleterm_reopen (int rxpin, int txpin, int mode, int baud)
| Closes and the simple terminal connection, and reopens it in the calling cog. Depending on the parameters used, it can also be used to switch from one terminal device to another.
terminal * | simpleterm_pointer (void)
| Get default device pointer to SimpleIDE Terminal.

## Detailed Description

This library provides a collection of functions for communicating with text devices such as SimpleIDE Terminal, serial peripheral devices, and even VGA displays. Libraries like serial, fdserial, and vgatext return pointer/identifiers that can be used with this library's dprint, dscan, and write/read function parameters that have text_t types. The identifier allows the application's code to specify which connection to use for sending and receiving formatted text.

Author
  Steve Denson

Copyright
  Copyright (C) Parallax, Inc. 2014. All Rights MIT Licensed.

Features:

- Generic IO devices support with reduced code size
- Supports IO devices with rxChar/txChar functions.
- Contains 2 built-in device drivers - fdserial and simpleserial.
- Can get and print decimal, binary, float, hex, char, and string.
- Supports print format values to buffer comparable to sprintf (printBuffFormat and sprint).
- Supports format values from buffer comparable to sscanf (scanBuffFormat and sscan).

Core Usage
  Functions in this library do not use any additional cores; however, the device driver library that returns a text_t pointer for use with this library might. For example, fdserial and vgatext each take launch a core. Check the device driver library's documentation for details.

Memory Models
  Use with CMM or LMM.

Version
  0.99.1 Correct scan function %s formatting flag bugs.
  0.99 Digits versions of put/get and write/read added for transmitting and receiving values with fixed numbers of digits. Floating point output functions updated to handle nan (not a number) and +/- inf (infinity). printi, dprinti, scani, dscani, sprinti, sscani functions added for supporting non-floating point with less program space. functions with Len in their names added for transmitting strings and values represented with a fixed number of characters.

## Typedef Documentation

typedef text_t terminal

By default the terminal will use simple serial for input/output It can be overloaded.

## Function Documentation

int dprint | ( | text_t * | device,
|  | const char * | format,
|  |  | ...
| ) |  |

Print format "..." args to the device The output is limited to 256 bytes.

Note
  See print for format specifiers.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  format | C printf comparable format string.
  ... | Arguments to use with the format string.

Returns
  Number of bytes placed into the buffer.

int int int dprinti | ( | text_t * | device,
|  | const char * | format,
|  |  | ...
| ) |  |

Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.

Note
  See print for format specifiers except f.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  format | C printf comparable format string.
  ... | Arguments to use with the format string.

Returns
  Number of bytes placed into the buffer.

int int dscan | ( | text_t * | device,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted device input to the "..." args. The input is limited to 256 bytes.

Note
  See scan for format specifiers.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

int int int int dscani | ( | text_t * | device,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted device input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.

Note
  See scan for format specifiers.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

int getBin | ( | void |  | ) |

Get binary number from the debug port.

Returns
  Value received.

int getChar | ( | void |  | ) |

Get char from the debug port.

Returns
  Character received as an integer.

int getDec | ( | void |  | ) |

Get decimal number from the debug port.

Returns
  Value received.

float getFloat | ( | void |  | ) |

Get floating point number from the debug port.

Returns
  Value received.

int getHex | ( | void |  | ) |

Get hexadecimal number from the debug port.

Returns
  Value received.

char* getStr | ( | char * | buffer,
|  | int | max
| ) |  |

Get string of chars from the debug port.

Parameters

  *buffer | array of chars with enough elements to hold the input string plus 2 null terminators.
  max | Maximum size to read and should be less or equal buffer size.

Returns
  Pointer to string received.

int print | ( | const char * | format,
|  |  | ...
| ) |  |

Print format "..." args to the default simple terminal device. The output is limited to 256 bytes.

Format specifiers for print dprint, and sprint:

%% Prints % sign to the output.

b Prints binary representation of an int parameter. Note: b is not an ANSI standard format specifier.

c Prints char representation of a char parameter.

d Prints decimal integer representation of an int parameter.

f Prints floating point representation of a float parameter.

s Prints string representation of a char* parameter.

u Prints unsigned integer representation of an unsigned int parameter.

x Prints hexadecimal integer representation of an int parameter.

Width and precision n.p cause n integer digits of a float to print, and p digits to the right of the decimal to print.

Parameters

  format | C printf comparable format string.
  ... | Arguments to use with the format string.

Returns
  Number of bytes placed into the buffer.

int printi | ( | const char * | format,
|  |  | ...
| ) |  |

Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.

Note
  See print for format specifiers except f.

Parameters

  format | C printf comparable format string.
  ... | Arguments to use with the format string.

Returns
  Number of bytes placed into the buffer.

void putBin | ( | int | value | ) |

Print string representation of a binary number to the debug port.

Parameters

  value | Number to print.

void putBinLen | ( | int | value,
|  | int | digits
| ) |  |

Print string representation of a binary number to debug port with a fixed number of digits.

Parameters

  value | Number to print.
  digits | Number of characters to print.

void putChar | ( | char | c | ) |

Print a char to the debug port.

Parameters

  c | Char to send.

void putDec | ( | int | value | ) |

Print string representation of a decimal number to the debug port.

Parameters

  value | Number to print.

void putDecLen | ( | int | value,
|  | int | width
| ) |  |

Print string representation of a decimal number to the debug port.

Parameters

  value | Number to print.
  width | Number of characters to print padded by zeroes.

void putFloat | ( | float | value | ) |

Print string representation of a 32 bit floating point number to the debug port.

Parameters

  value | Number to print.

void putFloatPrecision | ( | float | value,
|  | int | width,
|  | int | precision
| ) |  |

Print string representation of a 32 bit floating point number to the debug port with a fixed number of digits.

Parameters

  value | Number to print.
  width | Number of characters to print.
  precision | Number of decimal point digits to print.

void putHex | ( | int | value | ) |

Print string representation of a hexadecimal number to the debug port.

Parameters

  value | Number to print.

void putHexLen | ( | int | value,
|  | int | digits
| ) |  |

Print string representation of a hexadecimal number to the debug port with a fixed number of digits.

Parameters

  value | Number to print.
  digits | Number of hexadecimal characters to print padded by zeroes.

int putLine | ( | const char * | str | ) |

Print string + new line on the transmit debug port. This is an alias of putln.

Parameters

  *str | Null terminated string to send.

int putln | ( | const char * | str | ) |

Print string + new line on the transmit debug port.

Parameters

  *str | Null terminated string to send.

int putStr | ( | const char * | str | ) |

Print string to the debug port.

Parameters

  *str | Null terminated string to send.

int putStrLen | ( | char * | str,
|  | int | width
| ) |  |

Send a string with a certain number of characters.

Parameters

  str | Null terminated string to send.
  width | Number of characters to print padded by spaces.

int readBin | ( | text_t * | device | ) |

Get binary number from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.

Returns
  Number received.

int readChar | ( | text_t * | device | ) |

Get char from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.

Returns
  character received as an int value.

int readDec | ( | text_t * | device | ) |

Get decimal number from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.

Returns
  Number received.

float readFloat | ( | text_t * | device | ) |

Get floating point number from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.

Returns
  Number received.

int readHex | ( | text_t * | device | ) |

Get hexadecimal number from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.

Returns
  Number received.

char* readStr | ( | text_t * | device,
|  | char * | buffer,
|  | int | max
| ) |  |

Get string of chars from the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  buffer | Char array with enough elements to hold the input string.
  max | Maximum size to read and should be less or equal buffer size.

Returns
  string received.

int int scan | ( | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted simple terminal input to the "..." args. The input is limited to 256 bytes.

Format specifiers for scan, dscan, and sscan:

- %% Scan % sign to the input.

- b Scans binary representation to the int parameter. Note: b is not an ANSI standard format specifier.

- c Scans char representation to a char parameter.

- d Scans integer representation to an int parameter.

- f Scans floating point representation to a float parameter.

- s Scans string representation to a char* parameter.

- u Scans unsigned integer representation to an unsigned int parameter.

- x Scans hexadecimal integer representation to the int parameter.

Width and precision n.p cause n integer digits to scan to the left of the decimal point, p digits to the right.

Parameters

  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

int int scani | ( | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted simple terminal input to the "..." args. This version does not provide floating point conversions. The input is limited to 256 bytes.

Note
  See scan for format specifiers.

Parameters

  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

terminal* simpleterm_open | ( | void |  | ) |

Reopens the SimpleIDE Terminal connection if it was closed previously. The SimpleIDE Terminal connection transmits on P30 and receives on P31 at 115200 bps. The port is a simple serial driver running in the same cog, and does not buffer bytes.

Returns
  0 if port is already open, else returns term pointer.

terminal* simpleterm_pointer | ( | void |  | ) |

Get default device pointer to SimpleIDE Terminal.

Returns
  terminal* Pointer to SimpleIDE Terminal device.

Get the SimpleTerm default text_t pointer

terminal* simpleterm_reopen | ( | int | rxpin,
|  | int | txpin,
|  | int | mode,
|  | int | baud
| ) |  |

Closes and the simple terminal connection, and reopens it in the calling cog. Depending on the parameters used, it can also be used to switch from one terminal device to another.

Parameters

  rxpin | Serial input pin, receives serial data. The default on start- up is P31 for receiving characters from the host computer's terminal.
  txpin | Serial output pin, transmits serial data. The default on start-up is P30 for sending characters to the host computer's terminal.
  mode | Unused mode field (for fdserial compatibility).
  baud | Bit value transmit rate, 9600, 31250, etc... The default on start-up is 115200.

Returns
  simpleterm pointer for use as an identifier for serial and simpletext library functions that have serial or text_t parameter types.

int int int sprint | ( | char * | buffer,
|  | const char * | format,
|  |  | ...
| ) |  |

Print format "..." args to the output buffer. The output buffer must be big enough for the output.

Note
  See print for format specifiers.

Parameters

  buffer | Pointer to memory where formatted output can be stored.
  *format | is a C printf comparable format string.
  ... | is the arguments to use with the format string.

Returns
  the number of bytes placed into the buffer.

int int int int int sprinti | ( | char * | buffer,
|  | const char * | format,
|  |  | ...
| ) |  |

Print integer and char only format "..." args to the default simple terminal device. This version does not support floating point. The output is limited to 256 bytes.

Note
  See print for format specifiers except f.

Parameters

  buffer | Pointer to memory where formatted output can be stored.
  *format | C printf comparable format string.
  ... | Arguments to use with the format string.

Returns
  Number of bytes placed into the buffer.

int int int int sscan | ( | const char * | buffer,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted buffer to the "..." args.

Note
  See scan for format specifiers.

Parameters

  *buffer | Pointer to memory where formatted output can be stored.
  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

int int int int int int sscani | ( | const char * | buffer,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Convert formatted buffer to the "..." args. This version does not provide floating point conversions.

Note
  See scan for format specifiers.

Parameters

  buffer | Pointer to memory where formatted output can be stored.
  *fmt | C printf comparable format string.
  ... | Arguments where output will go and must be pointers.

Returns
  Number of bytes placed into the buffer.

void writeBin | ( | text_t * | device,
|  | int | value
| ) |  |

Print string representation of a binary number to the receive device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.

void writeBinLen | ( | text_t * | device,
|  | int | value,
|  | int | digits
| ) |  |

Print string representation of a binary number to output with a fixed number of digits.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.
  digits | Number of characters to print.

void writeChar | ( | text_t * | device,
|  | char | c
| ) |  |

Send a character to the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  c | Character to send.

void writeDec | ( | text_t * | device,
|  | int | value
| ) |  |

Print string representation of a decimal number to output.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.

void writeDecLen | ( | text_t * | device,
|  | int | value,
|  | int | width
| ) |  |

Print string representation of a decimal number to output device with a fixed number of digits.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.
  width | Number of characters to print padded by spaces.

void writeFloat | ( | text_t * | device,
|  | float | value
| ) |  |

Print string representation of a 32 bit floating point number to device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.

void writeFloatPrecision | ( | text_t * | device,
|  | float | value,
|  | int | width,
|  | int | precision
| ) |  |

Print string representation of a 32 bit floating point number to device with a certain number of decimal point digits.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  width | Number of characters to print.
  precision | Number of decimal point digits to print.
  value | Number to print.

void writeHex | ( | text_t * | device,
|  | int | value
| ) |  |

Print string representation of a hexadecimal number to output device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.

void writeHexLen | ( | text_t * | device,
|  | int | value,
|  | int | digits
| ) |  |

Print string representation of a hexadecimal number to output device with a fixed number of digits.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  value | Number to print.
  digits | Number of hexadecimal characters to print.

int writeLine | ( | text_t * | device,
|  | char * | str
| ) |  |

Send a string + new line to the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  str | Null terminated string to send.

int writeStr | ( | text_t * | device,
|  | char * | str
| ) |  |

Send a string to the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  str | Null terminated string to send.

int writeStrLen | ( | text_t * | device,
|  | char * | str,
|  | int | width
| ) |  |

Send a string to the device.

Parameters

  *device | Connection identifier to serial, fdserial, or other text_t compatible device that has been opened.
  str | Null terminated string to send.
  width | Number of characters to print padded by spaces.