libcaca documentation

# libcucul importers/exporters from/to various formats

## Functions
long int | cucul_import_memory (cucul_canvas_t *, void const *, unsigned long int, char const *)
| Import a memory buffer into a canvas.
long int | cucul_import_file (cucul_canvas_t *, char const *, char const *)
| Import a file into a canvas.
char const *const * | cucul_get_import_list (void)
| Get available import formats.
void * | cucul_export_memory (cucul_canvas_t *, char const *, unsigned long int *)
| Export a canvas into a foreign format.
char const *const * | cucul_get_export_list (void)
| Get available export formats.

## Detailed Description

These functions import various file formats into a new canvas, or export the current canvas to various text formats.

## Function Documentation

long int cucul_import_memory | ( | cucul_canvas_t * | cv,
|  | void const * | data,
|  | unsigned long int | len,
|  | char const * | format |
| ) |  |  |

Import a memory buffer into the given libcucul canvas's current frame. The current frame is resized accordingly and its contents are replaced with the imported data.

Valid values for `format` are:

- `""`: attempt to autodetect the file format.
- `"caca"`: import native libcaca files.
- `"text"`: import ASCII text files.
- `"ansi"`: import ANSI files.
- `"utf8"`: import UTF-8 files with ANSI colour codes.

The number of bytes read is returned. If the file format is valid, but not enough data was available, 0 is returned.

If an error occurs, -1 is returned and errno is set accordingly:

- `ENOMEM` Not enough memory to allocate canvas.
- `EINVAL` Invalid format requested.

Parameters:

  | cv | A libcucul canvas in which to import the file.
  | data | A memory area containing the data to be loaded into the canvas.
  | len | The size in bytes of the memory area.
  | format | A string describing the input format.

Returns:
  The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

long int cucul_import_file | ( | cucul_canvas_t * | cv,
|  | char const * | filename,
|  | char const * | format |
| ) |  |  |

Import a file into the given libcucul canvas's current frame. The current frame is resized accordingly and its contents are replaced with the imported data.

Valid values for `format` are:

- `""`: attempt to autodetect the file format.
- `"caca"`: import native libcaca files.
- `"text"`: import ASCII text files.
- `"ansi"`: import ANSI files.
- `"utf8"`: import UTF-8 files with ANSI colour codes.

The number of bytes read is returned. If the file format is valid, but not enough data was available, 0 is returned.

If an error occurs, -1 is returned and errno is set accordingly:

- `ENOSYS` File access is not implemented on this system.
- `ENOMEM` Not enough memory to allocate canvas.
- `EINVAL` Invalid format requested. cucul_import_file() may also fail and set errno for any of the errors specified for the routine fopen().

Parameters:

  | cv | A libcucul canvas in which to import the file.
  | filename | The name of the file to load.
  | format | A string describing the input format.

Returns:
  The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

char const* const* cucul_get_import_list | ( | void |  | ) |

Return a list of available import formats. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the import format, to be used with cucul_import_canvas(), and a string containing the natural language description for that import format.

This function never fails.

Returns:
  An array of strings.

void* cucul_export_memory | ( | cucul_canvas_t * | cv,
|  | char const * | format,
|  | unsigned long int * | bytes |
| ) |  |  |

This function exports a libcucul canvas into various foreign formats such as ANSI art, HTML, IRC colours, etc. The returned pointer should be passed to free() to release the allocated storage when it is no longer needed.

Valid values for `format` are:

- `"caca"`: export native libcaca files.
- `"ansi"`: export ANSI art (CP437 charset with ANSI colour codes).
- `"html"`: export an HTML page with CSS information.
- `"html3"`: export an HTML table that should be compatible with most navigators, including textmode ones.
- `"irc"`: export UTF-8 text with mIRC colour codes.
- `"ps"`: export a PostScript document.
- `"svg"`: export an SVG vector image.
- `"tga"`: export a TGA image.

If an error occurs, NULL is returned and errno is set accordingly:

- `EINVAL` Unsupported format requested.
- `ENOMEM` Not enough memory to allocate output buffer.

Parameters:

  | cv | A libcucul canvas
  | format | A string describing the requested output format.
  | bytes | A pointer to an unsigned long integer where the number of allocated bytes will be written.

Returns:
  A pointer to the exported memory area, or NULL in case of error.

char const* const* cucul_get_export_list | ( | void |  | ) |

Return a list of available export formats. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the export format, to be used with cucul_export_memory(), and a string containing the natural language description for that export format.

This function never fails.

Returns:
  An array of strings.