src/lib/fostr/README.md

# fostr: Output Formatting

fostr is an ostream formatting library that provides the following:

* support for indented formatting (indent.h)
* hex dumps (hex_dump.h)
* formatting for public/lib/fidl types (fidl_types.h)
* formatting for zircon zx:: types (zx_types.h)
* generated formatting for FIDL types

fostr is not part of the Fuchsia SDK.

## FIDL type formatting

Currently, structs, tables, unions, arrays, vectors, and enums can be formatted.
Support for formatting serialized messages is also intended.

To use an existing formatter for FIDL types (say, for fuchsia.foo), add the
dependency to your BUILD.gn file, which will look like this:

```
//src/lib/fostr/fidl/fuchsia.foo
```

Includes look like this:

```
#include "src/lib/fostr/fidl/fuchsia/foo/formatting.h"
```

Adding a new FIDL library is pretty simple: just add a new fostr/fidl/xxx
subdirectory with a BUILD.gn (see existing files for an example). The target
must depend on the fostr/fidl targets for the libraries on which
xxx depends. This means you may have to add formatting support for
libraries that your FIDL library depends on.

If you have hand-rolled formatters for a library, they
can be accommodated. Look for directories containing a file called
'amendments.json' for examples of this.

If you have formatters for all the types in your library, you can just provide
a formatting.h and skip the amendments business. There are currently no
examples of this.

### FIDL containers properly print `int8` and `uint8` as integers

All FIDL containers (structs, tables, unions, arrays, and vectors) print `int8`
and `uint8` FIDL primitives as integers. Structs, tables and unions interpret
these as 32-bit types for printing. Arrays and vectors use hex formatting.

Note that if you choose to print an 8-bit data type directly, the C++
STL interprets these as `char` types, so you'll have to cast it yourself:

```
uint8_t my_fidl_data = get_some_uint8();
os << static_cast<uint32_t>(my_fidl_data);
```

## Implementation notes

### Code-generation templates

The corresponding code-generation templates are located in the sibling directory:

```sdk/lib/fostr/build```