mightymandel v16

GPU-based Mandelbrot set explorer

parse.h File Reference

(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:

Go to the source code of 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
sourceA null-terminated input file already loaded into memory.
lengthLength of the input file (without the extra null terminator).
cxFor output of the real part of the view center. It is already mpfr_init2()'d.
cyFor output of the imaginary part of the view center. It is already mpfr_init2()'d.
czFor 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
filenameThe file to load.
lengthThe 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
filenameThe name of a file to load and parse.
cxFor output of the real part of the view center. It is already mpfr_init2()'d.
cyFor output of the imaginary part of the view center. It is already mpfr_init2()'d.
czFor 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
sourceA null-terminated input file already loaded into memory.
lengthLength of the input file (without the extra null terminator).
cxFor output of the real part of the view center. It is already mpfr_init2()'d.
cyFor output of the imaginary part of the view center. It is already mpfr_init2()'d.
czFor 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
sourcePointer 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
sourcePointer to source string pointer. Updated as described above.
separatorCharactor 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
radiusA 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
radiusThe 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: