docs menu

Module Fits.Header

Headers.

A header is its records in file order, each the 80 bytes the file held: order, duplicates, blank records and bytes outside ASCII 32–126 are kept, so every record a program does not edit is written back byte for byte. A value is parsed when it is asked for, and fails there alone.

A record is commentary when its keyword is COMMENT, HISTORY or blank, or its bytes 9–10 are not "= ", unless it starts with "HIERARCH " and holds =.

Keywords. A standard keyword is 1 to 8 characters of A–Z 0–9 - _. A hierarchical keyword is the tokens between "HIERARCH " and the first = of a record, joined by single spaces: two or more tokens, or one longer than 8 bytes, each of bytes 33–126 other than =, in the case written, as in "ESO DET DIT". Keywords compare exactly. Header.get, Header.find, Header.set and Header.remove raise Invalid_argument on a name of neither form, such as "naxis", and on COMMENT, HISTORY, blank and CONTINUE, which Header.commentary reads.

Duplicates. A keyword repeated with different values is indeterminate (§4.1.2.3): get returns the value when every card agrees, and is an Error naming two cards that disagree otherwise.

#type t

The type for headers: records in file order, without END.

#val empty : t

empty has no record.

#val of_string : ?name:string -> string -> (t, string) Stdlib.result

of_string ~name s reads 80-byte records back to back up to END, or, when s holds a newline, lines of at most 80 bytes up to END, as .head files hold them. name starts the header's errors.

#val to_string : t -> string

to_string h is h's records, END, and spaces to a multiple of 2880 bytes.

#val records : t -> string list

records h is h's records, 80 bytes each.

#val equal : t -> t -> bool

equal h h' is true iff h and h' have the same records.

#val pp : Stdlib.Format.formatter -> t -> unit

pp formats a header one record per line, trailing spaces dropped.

#val get : 'a Value.t -> string -> t -> ('a, string) Stdlib.result

get v k h is the value of keyword k read with v. It is an Error if k is absent or undefined, if a card does not read, or if its cards disagree.

Raises Invalid_argument if k is not a keyword (see above).

#val find : 'a Value.t -> string -> t -> ('a option, string) Stdlib.result

find is get with Ok None for an absent or undefined keyword.

#val set : ?comment:string -> 'a Value.t -> string -> 'a -> t -> t

set ~comment v k x h is h with one card giving k the value x, at the place of k's first card or appended, its later cards removed. comment replaces the card's comment; without it the comment is kept, cut to fit beside the new value.

A value that fits bytes 11–30 is written in the fixed format of §4.2.2–§4.2.4, others in the free format from byte 11. A string over 68 bytes continues over CONTINUE records. get v k (set v k x h) is Ok x for every finite float and every string without trailing spaces.

Raises Invalid_argument if k is not a keyword, on a non-finite float, on a byte outside ASCII 32–126, on Value.text that is not one FITS value, on a hierarchical keyword that leaves no room for the value, and on a comment that does not fit beside a value other than a string.

#val remove : string -> t -> t

remove k h is h without k's cards and their CONTINUE records.

Raises Invalid_argument as get does.

#val commentary : string -> t -> string list

commentary k h is the text of h's commentary records whose keyword is k (bytes 9–80, trailing spaces dropped), in order. k is "COMMENT", "HISTORY", "" for blank, or any other keyword whose records have no value indicator.

#val add_commentary : string -> string -> t -> t

add_commentary k s h appends s as k records of 72 bytes each.

Raises Invalid_argument if k is not "COMMENT", "HISTORY" or "", or if s holds a byte outside ASCII 32–126.