Initial revision

[ssr] / StraySrc / Libraries / Sapphire / csapph / h / choices / options

/*
 * options.h
 *
 * [Generated from options, 08 November 1995]
 */

#pragma include_only_once
#pragma force_top_level

#ifndef __options_h
#define __options_h

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  options_read
 *  options_write
 *  optType_string
 *  optType_integer
 *  optType_literal
 *  optType_enum
 *  optType_bool
 *  optType_version
 */

/* --- options_read --- *
 *
 * On entry:	R0 == chunk file handle
 *		R1 == pointer to a chunk name
 *		R2 == pointer to options definition
 *		R3,R4 specify address of output block
 *
 * On exit:	--
 *
 * Use:		Claims the specified options chunk, and reads the data in
 *		it into a binary block.  Because the output data might be
 *		in a flex block, the two registers R3,R4 which define its
 *		address work as follows:
 *
 *		R3 == address or offset of data
 *		R4 == -1 if R3 is address, else flex anchor address
 */

extern routine options_read;

/* --- options_write --- *
 *
 * On entry:	R0 == terminator character to write, 0 for none, or -1 for
 *			quoting with 's
 *		R1 == pointer to name to save
 *
 * On exit:	May return an error
 *
 * Use:		Writes out an option name, terminated with the character
 *		given in R0 (which will normally be a space or an `=' sign).
 */

extern routine options_write;

/* --- optType_string --- *
 *
 * Flags:	--
 *
 * Data:	(word) buffer size of string
 *
 * Use:		Handles string data.  The binary representation is a ctrl
 *		terminated string.  The textual representation is a sequence
 *		of characters, which is always output in single quotes,
 *		although this is not necessary for the input.  The string
 *		will be truncated to fit in the buffer during reading.
 */

extern routine optType_string;

/* --- optType_integer --- *
 *
 * Flags:	bit 8 == use given default base
 *
 * Data:	(word) default base, if bit 8 set
 *
 * Use:		Handles integer data.  The binary representation is a 32-
 *		bit integer value.  The textual representation is the normal
 *		RISC OS style of numbers (i.e. the base_value notation is
 *		supported).  Numbers are always output in the default base
 *		given (or in decimal if there is none given).  Numbers
 *		being read may always have a sign; numbers will only be
 *		output with a sign if the default base is decimal.  Uppercase
 *		letters will be used for output, but any case is acceptable
 *		for input.
 *
 *		Special prefixes allowed are `%' for binary and `&' for hex.
 *		Such numbers are always output with these prefixes.
 */

extern routine optType_integer;

/* --- optType_literal --- *
 *
 * Flags:	--
 *
 * Data:	(string) data to write out (*null* terminated)
 *
 * Use:		Reads nothing; leave the name blank.  Writes out the data
 *		literally.  Note that an extra linefeed is added to the
 *		end, so don't overdo it.
 */

extern routine optType_literal;

/* --- optType_enum --- *
 *
 * Flags:	bit 8 == quote output string
 *		bit 9 == don't put an `=' sign in output
 *
 * Data:	See below
 *
 * Use:		The data is a collection of ctrl-terminated strings, itself
 *		terminated by a zero-length entry.  The textual
 *		representation is one of these strings, or an abbreviation
 *		of one.  The binary representation is a word containing the
 *		index into the list.
 */

extern routine optType_enum;

/* --- optType_bool --- *
 *
 * Flags:	bit 8 == make flag active low
 *		bit 9 == use `on'/`off' rather than `true'/`false'; also
 *			suppresses the `=' sign
 *
 * Data:	(word) bit mask to OR or BIC within word
 *
 * Use:		Handles a boolean option.  It will translate between the
 *		strings `true' or `false' and a bit (or set of bits) within
 *		a word.
 */

extern routine optType_bool;

/* --- optType_version --- *
 *
 * Flags:	--
 *
 * Data:	--
 *
 * Use:		Converts between version number strings (of the form
 *		<int>[.[<digit>[<digit>]]]) and integers.  The version
 *		number is stored multiplied by 100.
 */

extern routine optType_version;

/*----- Data structures ---------------------------------------------------*/

/* --- Options definition block --- */

#define opt_flags 0
#define opt_length 4
#define opt_offset 8
#define opt_type 12
#define opt_name 16

/* --- Option block flags --- */

#define optFlag_last ((1<<0))
#define optFlag_ignore ((1<<1))

/* --- Integer type flags --- */

#define intFlag_base ((1<<8))

/* --- Enumeration type flags --- */

#define enumFlag_quote ((1<<8))
#define enumFlag_noEq ((1<<9))

/* --- Boolean type flags --- */

#define boolFlag_cpl ((1<<8))
#define boolFlag_onOff ((1<<9))

/* --- Type handler reason codes --- *
 *
 * All enter with:
 *
 *  R0 == reason code
 *  R7 == flags read from table
 *  R8 == address of option name
 *  R9 == address of type-specific data
 * R10 == address of binary option
 */

#define optReason_read 0

#define optReason_write 1

/*----- That's all, folks -------------------------------------------------*/

#endif