uk.ac.starlink.fits

## Class CardFactory

- java.lang.Object
- - uk.ac.starlink.fits.CardFactory

-     public class CardFactory
      extends java.lang.Object

  Creates FITS CardImages suitable for writing to a FITS header. Different factory instances are available with variant options for header construction.

  Attempts to construct illegal FITS headers will generally provoke RuntimeExceptions.

  Since:
    4 Mar 2022

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `CardFactory.Config` CardFactory configuration.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static CardFactory` | `CLASSIC` Instance with value trimming, bad char replacement, no HIERARCH.
    `static CardFactory` | `DEFAULT` Default instance (currently `CLASSIC`).
    `static CardImage` | `END_CARD` CardImage for terminating header ("END").
    `static CardFactory` | `HIERARCH` Instance with value trimming, bad char replacement, and HIERARCH.
    `static CardFactory` | `STRICT` Instance with no value trimming, bad char rejection, no HIERARCH.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CardFactory(CardFactory.Config config)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CardImage` | `createCommentCard(java.lang.String txt)` Constructs a COMMENT card with the given comment.
    `CardImage` | `createIntegerCard(java.lang.String key, long value, java.lang.String comment)` Constructs a key-value card with integer content.
    `CardImage` | `createLiteralCard(java.lang.String key, java.lang.String literal, java.lang.String comment)` Constructs a key-value card with given literal text for the value part.
    `CardImage` | `createLogicalCard(java.lang.String key, boolean value, java.lang.String comment)` Constructs a key-value card with logical content.
    `CardImage` | `createPlainCard(java.lang.String txt)` Constructs a card containing the given exact text.
    `CardImage` | `createRealCard(java.lang.String key, double value, java.lang.String comment)` Constructs a key-value card with floating point content.
    `CardImage` | `createStringCard(java.lang.String key, java.lang.String value, java.lang.String comment)` Constructs a key-value card with string content.
    `CardFactory.Config` | `getConfig()` Returns the configuration state of this factory.
    `static java.lang.String` | `sanitiseAsError(java.lang.String txt)` Utility string sanitisation function that throws an IllegalArgumentException if any illegal characters are present.
    `static java.lang.String` | `sanitiseByReplacement(java.lang.String txt, char replaceChar)` Utility string sanitisation function that replaces illegal characters by a given char.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CLASSIC

          public static final CardFactory CLASSIC

      Instance with value trimming, bad char replacement, no HIERARCH.

    - #### HIERARCH

          public static final CardFactory HIERARCH

      Instance with value trimming, bad char replacement, and HIERARCH.

    - #### STRICT

          public static final CardFactory STRICT

      Instance with no value trimming, bad char rejection, no HIERARCH.

    - #### DEFAULT

          public static final CardFactory DEFAULT

      Default instance (currently `CLASSIC`).

    - #### END_CARD

          public static final CardImage END_CARD

      CardImage for terminating header ("END").

  - ### Constructor Detail

    - #### CardFactory

          public CardFactory(CardFactory.Config config)

      Constructor.
      Parameters:
        `config` - factory configuration

  - ### Method Detail

    - #### getConfig

          public CardFactory.Config getConfig()

      Returns the configuration state of this factory.
      Returns:
        config object

    - #### createPlainCard

          public CardImage createPlainCard(java.lang.String txt)

      Constructs a card containing the given exact text. It is padded with spaces if necessary. No sanitisation or trimming is performed.
      Parameters:
        `txt` - literal card content, <=80 characters
      Returns:
        new card

    - #### createCommentCard

          public CardImage createCommentCard(java.lang.String txt)

      Constructs a COMMENT card with the given comment. The text may be sanitised and trimmed if too long according to policy.
      Parameters:
        `txt` - comment text
      Returns:
        new card

    - #### createStringCard

          public CardImage createStringCard(java.lang.String key,
                                            java.lang.String value,
                                            java.lang.String comment)

      Constructs a key-value card with string content. The value and comment may be sanitised and trimmed if too long according to policy.
      Parameters:
        `key` - header keyword
        `value` - header value
        `comment` - comment text, or null
      Returns:
        new card

    - #### createIntegerCard

          public CardImage createIntegerCard(java.lang.String key,
                                             long value,
                                             java.lang.String comment)

      Constructs a key-value card with integer content. The comment may be sanitised and trimmed if too long according to policy.
      Parameters:
        `key` - header keyword
        `value` - header value
        `comment` - comment text, or null
      Returns:
        new card

    - #### createRealCard

          public CardImage createRealCard(java.lang.String key,
                                          double value,
                                          java.lang.String comment)

      Constructs a key-value card with floating point content. The comment may be sanitised and trimmed if too long according to policy.
      Parameters:
        `key` - header keyword
        `value` - header value
        `comment` - comment text, or null
      Returns:
        new card

    - #### createLogicalCard

          public CardImage createLogicalCard(java.lang.String key,
                                             boolean value,
                                             java.lang.String comment)

      Constructs a key-value card with logical content. The comment may be sanitised and trimmed if too long according to policy.
      Parameters:
        `key` - header keyword
        `value` - header value
        `comment` - comment text, or null
      Returns:
        new card

    - #### createLiteralCard

          public CardImage createLiteralCard(java.lang.String key,
                                             java.lang.String literal,
                                             java.lang.String comment)

      Constructs a key-value card with given literal text for the value part. No additional quoting or escaping is performed on the provided string, but both string and comment may be trimmed in a string-sensitive way according to policy.

      The key must contain only legal key characters, and the literal and comment must contain only legal header characters.

      Parameters:
        `key` - header keyword
        `literal` - formatted value text
        `comment` - comment text, or null
      Returns:
        new card
      Throws:
        `java.lang.IllegalArgumentException` - if inputs are not suitable for FITS

    - #### sanitiseByReplacement

          public static java.lang.String sanitiseByReplacement(java.lang.String txt,
                                                               char replaceChar)

      Utility string sanitisation function that replaces illegal characters by a given char.
      Parameters:
        `txt` - input text
        `replaceChar` - character to replace non-FITS characters
      Returns:
        same as `txt`, but with non-FITS characters replaced by `replaceChar`

    - #### sanitiseAsError

          public static java.lang.String sanitiseAsError(java.lang.String txt)

      Utility string sanitisation function that throws an IllegalArgumentException if any illegal characters are present.
      Parameters:
        `txt` - input text
      Returns:
        input text
      Throws:
        `java.lang.IllegalArgumentException` - if non-FITS characters are present