(v16)

Parse parameter file formats. More...

#include <stdbool.h>
#include <mpfr.h>

Include dependency graph for parse.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef bool	parser (const char *source, int length, mpfr_t cx, mpfr_t cy, mpfr_t cz)
	The type of parsers for a format. This typedef isn't actually used. It's purely to avoid boilerplate copying and pasting in the documentation markup.

Functions
bool	radius_is_valid (const mpfr_t radius)
	Check if a radius is valid. A radius \(r\) is valid when \(0 < r < +\infty\). NaN is not a valid radius.
mpfr_prec_t	precision_for_radius (const mpfr_t radius)
	Calculate a reasonable precision that suffices to accurately represent the center of a view of a given radius \(r\).
char *	load_file (const char filename, int length)
	Load a file's contents into memory.
char *	parse_separator (char **source, int separator)
	Split a string at the first occurence of a separator character.
char *	parse_line (char **source)
	Split a string at line endings and strip BOM.
bool	parse (const char *source, int length, mpfr_t cx, mpfr_t cy, mpfr_t cz)
	Parse a parameter file by trying all parsers in turn.
bool	load_parameter_file (const char *filename, mpfr_t cx, mpfr_t cy, mpfr_t cz)
	Load a parameter file and parse it.

Detailed Description

Parse parameter file formats.

This module handles loading parameter files, which are often line-based text formats containing coordinates and other information for specific programs. We are only interested in extracting the view, as center and radius.

A typical parser implementation might:

split a copy of the input into lines (for line-based formats)
check each line against known keywords and extract needed substrings
if the radius (or something convertible, like magnification) is present
- compute the radius from its string, storing it in cz
- p = precision_for_radius(cz) (precision needed to represent cx, cy)
- mpfr_set_prec(cx, p), mpfr_set_prec(cy, p)
- also set the precision of any required temporary variables as needed
- compute the view center, store real and imaginary parts in cx, cy
otherwise (eg corners representation)
- TODO: re-parse at successively higher precisions until radius > 0

If a format has variations, it might be clearer to write two parsers than try to combine them into one. Commonly needed functionality can be factored out into other functions.

Definition in file parse.h.

Typedef Documentation

typedef bool parser(const char *source, int length, mpfr_t cx, mpfr_t cy, mpfr_t cz)

The type of parsers for a format. This typedef isn't actually used. It's purely to avoid boilerplate copying and pasting in the documentation markup.

Parameters

source	A null-terminated input file already loaded into memory.
length	Length of the input file (without the extra null terminator).
cx	For output of the real part of the view center. It is already `mpfr_init2()`'d.
cy	For output of the imaginary part of the view center. It is already `mpfr_init2()`'d.
cz	For output of the view radius. It is already `mpfr_init2()`'d.

Returns: Success (true) or failure (false).

Definition at line 49 of file parse.h.

Function Documentation

char* load_file	(	const char *	filename,
		int *	length
	)

Load a file's contents into memory.

Load a file's contents into a newly allocated null-terminated buffer. The buffer may also have embedded nulls (for example when loading a binary image file).

Parameters

filename	The file to load.
length	The file size is stored here.

Returns: The file contents in memory, or null on failure.

Definition at line 41 of file parse.c.

Referenced by load_parameter_file().

Here is the caller graph for this function:

bool load_parameter_file	(	const char *	filename,
		mpfr_t	cx,
		mpfr_t	cy,
		mpfr_t	cz
	)

Load a parameter file and parse it.

Parameters

filename	The name of a file to load and parse.
cx	For output of the real part of the view center. It is already `mpfr_init2()`'d.
cy	For output of the imaginary part of the view center. It is already `mpfr_init2()`'d.
cz	For output of the view radius. It is already `mpfr_init2()`'d.

Returns: Success (true) or failure (false).

Definition at line 111 of file parse.c.

References load_file(), LOG_ERROR, log_message, LOG_NOTICE, and parse().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

bool parse	(	const char *	source,
		int	length,
		mpfr_t	cx,
		mpfr_t	cy,
		mpfr_t	cz
	)

Parse a parameter file by trying all parsers in turn.

Parse format-agnostically by trying every parser in in turn and picking the first that succeeds. Most formats don't overlap enough to cause any problems. Parse binary formats first, followed by text formats. Binary format parsers should be more reliable in file format identification, so will just fail on text input, while text format parsers might encounter things they don't expect amidst a jumble of binary data. In any case, parsing arbitrary binary data might fail in weird ways, so be wary.

Parameters

source	A null-terminated input file already loaded into memory.
length	Length of the input file (without the extra null terminator).
cx	For output of the real part of the view center. It is already `mpfr_init2()`'d.
cy	For output of the imaginary part of the view center. It is already `mpfr_init2()`'d.
cz	For output of the view radius. It is already `mpfr_init2()`'d.

Returns: Success (true) or failure (false).

Definition at line 93 of file parse.c.

References P.

Referenced by load_parameter_file().

Here is the caller graph for this function:

char* parse_line ( char ** source )

Split a string at line endings and strip BOM.

Split a string at the end of the line "\\n". If the previous character is carriage return "\\r", delete it by replacing with null. This shortens the string length by one character. The purpose is to handle different line ending conventions on different platforms: Linux and OS X use "\\n", Windows uses "\\n\\r", aka LF and CRLF. Also, some files in UTF-8 end up having a byte order marker (BOM) inserted even if the content is in the pure ASCII subset of UTF-8. This usually only occurs once, at the start of the file, but it's possible for it to occur anywhere. Here we strip the BOM from the start of lines, because that's the most likely place for it to occur when files are appended to each other.

Parameters

source Pointer to source string pointer. Updated as described in parse_separator().

Returns: Pointer to the first line.

Definition at line 80 of file parse.c.

References parse_separator().

Referenced by parse_kfr(), parse_mdz_center(), parse_mdz_corners(), parse_mm(), parse_ppar_center(), parse_ppar_corners(), parse_ppm(), and parse_sft().

Here is the call graph for this function:

Here is the caller graph for this function:

char* parse_separator	(	char **	source,
		int	separator
	)

Split a string at the first occurence of a separator character.

If the separator is found then the source pointer is updated to the following character, and the found separator is replaced with 0. This makes the original source pointer a null terminated string ending where the separator was found. The original source pointer is returned, and the source pointer is updated as described if the separator was found, or set to 0 otherwise. It is an error to pass in null or pointer to null as the source pointer.

Parameters

source	Pointer to source string pointer. Updated as described above.
separator	Charactor to split the string on.

Returns: Pointer to the first substring.

Definition at line 66 of file parse.c.

Referenced by parse_line(), and parse_ppar_center().

Here is the caller graph for this function:

mpfr_prec_t precision_for_radius ( const mpfr_t radius )

Calculate a reasonable precision that suffices to accurately represent the center of a view of a given radius \(r\).

Typically \(r < 1\), which makes \(\log_2 r < 0\). As logarithms compress a lot ( \(\log_2 10^{-300} > -1000\)), using mpfr_get_d is safe (overflow is exceedingly unlikely, maybe even impossible).

Parameters

radius A valid radius.

Returns: A sufficient precision for the center.

Definition at line 31 of file parse.c.

References radius_is_valid().

Referenced by parse_command_line(), parse_kfr(), parse_mdz_center(), parse_mm(), parse_png(), parse_ppar_center(), parse_ppar_corners(), parse_ppm(), and parse_sft().

Here is the call graph for this function:

Here is the caller graph for this function:

bool radius_is_valid ( const mpfr_t radius )

Check if a radius is valid. A radius \(r\) is valid when \(0 < r < +\infty\). NaN is not a valid radius.

Parameters

radius The radius to check.

Returns: whether the radius is valid.

Definition at line 27 of file parse.c.

Referenced by parse_kfr(), parse_mdz_center(), parse_mm(), parse_png(), parse_ppar_center(), parse_ppar_corners(), parse_ppm(), parse_sft(), and precision_for_radius().

Here is the caller graph for this function:

mightymandel v16

GPU-based Mandelbrot set explorer

(v16)

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation