# Emitter Definitions

## Data Structures

struct | yaml_emitter_s
| The emitter structure. More...

## Typedefs

typedef int | yaml_write_handler_t (void *data, unsigned char *buffer, size_t size)
| The prototype of a write handler.
typedef enum yaml_emitter_state_e | yaml_emitter_state_t
| The emitter states.
typedef struct yaml_emitter_s | yaml_emitter_t
| The emitter structure.

## Enumerations

enum

yaml_emitter_state_e {
YAML_EMIT_STREAM_START_STATE,
YAML_EMIT_FIRST_DOCUMENT_START_STATE,
YAML_EMIT_DOCUMENT_START_STATE,
YAML_EMIT_DOCUMENT_CONTENT_STATE,
YAML_EMIT_DOCUMENT_END_STATE,
YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
YAML_EMIT_FLOW_MAPPING_KEY_STATE,
YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
YAML_EMIT_END_STATE
}

| The emitter states. More...

## Functions

int | yaml_emitter_initialize (yaml_emitter_t *emitter)
| Initialize an emitter.
void | yaml_emitter_delete (yaml_emitter_t *emitter)
| Destroy an emitter.
void | yaml_emitter_set_output_string (yaml_emitter_t *emitter, unsigned char *output, size_t size, size_t *size_written)
| Set a string output.
void | yaml_emitter_set_output_file (yaml_emitter_t *emitter, FILE *file)
| Set a file output.
void | yaml_emitter_set_output (yaml_emitter_t *emitter, yaml_write_handler_t *handler, void *data)
| Set a generic output handler.
void | yaml_emitter_set_encoding (yaml_emitter_t *emitter, yaml_encoding_t encoding)
| Set the output encoding.
void | yaml_emitter_set_canonical (yaml_emitter_t *emitter, int canonical)
| Set if the output should be in the "canonical" format as in the YAML specification.
void | yaml_emitter_set_indent (yaml_emitter_t *emitter, int indent)
| Set the intendation increment.
void | yaml_emitter_set_width (yaml_emitter_t *emitter, int width)
| Set the preferred line width.
void | yaml_emitter_set_unicode (yaml_emitter_t *emitter, int unicode)
| Set if unescaped non-ASCII characters are allowed.
void | yaml_emitter_set_break (yaml_emitter_t *emitter, yaml_break_t line_break)
| Set the preferred line break.
int | yaml_emitter_emit (yaml_emitter_t *emitter, yaml_event_t *event)
| Emit an event.
int | yaml_emitter_open (yaml_emitter_t *emitter)
| Start a YAML stream.
int | yaml_emitter_close (yaml_emitter_t *emitter)
| Finish a YAML stream.
int | yaml_emitter_dump (yaml_emitter_t *emitter, yaml_document_t *document)
| Emit a YAML document.
int | yaml_emitter_flush (yaml_emitter_t *emitter)
| Flush the accumulated characters to the output.

## Typedef Documentation

typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size)

The prototype of a write handler.

The write handler is called when the emitter needs to flush the accumulated characters to the output. The handler should write size bytes of the buffer to the output.

Parameters:

  `[in,out]` | data | A pointer to an application data specified by yaml_emitter_set_output().
  `[in]` | buffer | The buffer with bytes to be written.
  `[in]` | size | The size of the buffer.

Returns:
  On success, the handler should return `1`. If the handler failed, the returned value should be `0`.

typedef enum yaml_emitter_state_e yaml_emitter_state_t

The emitter states.

typedef struct yaml_emitter_s yaml_emitter_t

The emitter structure.

All members are internal. Manage the structure using the `yaml_emitter_` family of functions.

## Enumeration Type Documentation

enum yaml_emitter_state_e

The emitter states.

Enumerator:

  YAML_EMIT_STREAM_START_STATE | Expect STREAM-START.
  YAML_EMIT_FIRST_DOCUMENT_START_STATE | Expect the first DOCUMENT-START or STREAM-END.
  YAML_EMIT_DOCUMENT_START_STATE | Expect DOCUMENT-START or STREAM-END.
  YAML_EMIT_DOCUMENT_CONTENT_STATE | Expect the content of a document.
  YAML_EMIT_DOCUMENT_END_STATE | Expect DOCUMENT-END.
  YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE | Expect the first item of a flow sequence.
  YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE | Expect an item of a flow sequence.
  YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE | Expect the first key of a flow mapping.
  YAML_EMIT_FLOW_MAPPING_KEY_STATE | Expect a key of a flow mapping.
  YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE | Expect a value for a simple key of a flow mapping.
  YAML_EMIT_FLOW_MAPPING_VALUE_STATE | Expect a value of a flow mapping.
  YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE | Expect the first item of a block sequence.
  YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE | Expect an item of a block sequence.
  YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE | Expect the first key of a block mapping.
  YAML_EMIT_BLOCK_MAPPING_KEY_STATE | Expect the key of a block mapping.
  YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE | Expect a value for a simple key of a block mapping.
  YAML_EMIT_BLOCK_MAPPING_VALUE_STATE | Expect a value of a block mapping.
  YAML_EMIT_END_STATE | Expect nothing.

## Function Documentation

int yaml_emitter_initialize | ( | yaml_emitter_t * | emitter | ) |

Initialize an emitter.

This function creates a new emitter object. An application is responsible for destroying the object using the yaml_emitter_delete() function.

Parameters:

  `[out]` | emitter | An empty parser object.

Returns:
  `1` if the function succeeded, `0` on error.

void yaml_emitter_delete | ( | yaml_emitter_t * | emitter | ) |

Destroy an emitter.

Parameters:

  `[in,out]` | emitter | An emitter object.

void yaml_emitter_set_output_string | ( | yaml_emitter_t * | emitter,
|  | unsigned char * | output,
|  | size_t | size,
|  | size_t * | size_written |
| ) |  |  |

Set a string output.

The emitter will write the output characters to the output buffer of the size size. The emitter will set size_written to the number of written bytes. If the buffer is smaller than required, the emitter produces the YAML_WRITE_ERROR error.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | output | An output buffer.
  `[in]` | size | The buffer size.
  `[in]` | size_written | The pointer to save the number of written bytes.

void yaml_emitter_set_output_file | ( | yaml_emitter_t * | emitter,
|  | FILE * | file |
| ) |  |  |

Set a file output.

file should be a file object open for writing. The application is responsible for closing the file.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | file | An open file.

void yaml_emitter_set_output | ( | yaml_emitter_t * | emitter,
|  | yaml_write_handler_t * | handler,
|  | void * | data |
| ) |  |  |

Set a generic output handler.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | handler | A write handler.
  `[in]` | data | Any application data for passing to the write handler.

void yaml_emitter_set_encoding | ( | yaml_emitter_t * | emitter,
|  | yaml_encoding_t | encoding |
| ) |  |  |

Set the output encoding.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | encoding | The output encoding.

void yaml_emitter_set_canonical | ( | yaml_emitter_t * | emitter,
|  | int | canonical |
| ) |  |  |

Set if the output should be in the "canonical" format as in the YAML specification.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | canonical | If the output is canonical.

void yaml_emitter_set_indent | ( | yaml_emitter_t * | emitter,
|  | int | indent |
| ) |  |  |

Set the intendation increment.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | indent | The indentation increment (1 < . < 10).

void yaml_emitter_set_width | ( | yaml_emitter_t * | emitter,
|  | int | width |
| ) |  |  |

Set the preferred line width.

`-1` means unlimited.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | width | The preferred line width.

void yaml_emitter_set_unicode | ( | yaml_emitter_t * | emitter,
|  | int | unicode |
| ) |  |  |

Set if unescaped non-ASCII characters are allowed.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | unicode | If unescaped Unicode characters are allowed.

void yaml_emitter_set_break | ( | yaml_emitter_t * | emitter,
|  | yaml_break_t | line_break |
| ) |  |  |

Set the preferred line break.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in]` | line_break | The preferred line break.

int yaml_emitter_emit | ( | yaml_emitter_t * | emitter,
|  | yaml_event_t * | event |
| ) |  |  |

Emit an event.

The event object may be generated using the yaml_parser_parse() function. The emitter takes the responsibility for the event object and destroys its content after it is emitted. The event object is destroyed even if the function fails.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in,out]` | event | An event object.

Returns:
  `1` if the function succeeded, `0` on error.

int yaml_emitter_open | ( | yaml_emitter_t * | emitter | ) |

Start a YAML stream.

This function should be used before yaml_emitter_dump() is called.

Parameters:

  `[in,out]` | emitter | An emitter object.

Returns:
  `1` if the function succeeded, `0` on error.

int yaml_emitter_close | ( | yaml_emitter_t * | emitter | ) |

Finish a YAML stream.

This function should be used after yaml_emitter_dump() is called.

Parameters:

  `[in,out]` | emitter | An emitter object.

Returns:
  `1` if the function succeeded, `0` on error.

int yaml_emitter_dump | ( | yaml_emitter_t * | emitter,
|  | yaml_document_t * | document |
| ) |  |  |

Emit a YAML document.

The documen object may be generated using the yaml_parser_load() function or the yaml_document_initialize() function. The emitter takes the responsibility for the document object and destoys its content after it is emitted. The document object is destroyedeven if the function fails.

Parameters:

  `[in,out]` | emitter | An emitter object.
  `[in,out]` | document | A document object.

Returns:
  `1` if the function succeeded, `0` on error.

int yaml_emitter_flush | ( | yaml_emitter_t * | emitter | ) |

Flush the accumulated characters to the output.

Parameters:

  `[in,out]` | emitter | An emitter object.

Returns:
  `1` if the function succeeded, `0` on error.