Class Spec

Javadoc 27 generates this reference during each site build from the exported packages and the annotation processor. The Java guide shows the API in use.

java.lang.Object

dev.gecode.iris.Spec

public final class Spec extends Object

A parsed reader spec, checked against every parse-time rule of the Specification.

A spec is immutable, so threads can share it.

• Method Summary

  Modifier and Type

  Method

  Description

  Data

  catalog(byte[] input)

  Lists the instances of an input without an origin or parameters (§9.6).

  Data

  catalog(byte[] input, String origin)

  Lists the instances of an input without parameters, as catalog(byte[]) says.

  Data

  catalog(byte[] input, String origin, Params params)

  Lists the instances of an input, as catalog(byte[]) says.

  Data

  catalog(String input)

  Lists the instances of an input without an origin or parameters, as catalog(byte[]) says.

  Data

  catalog(String input, String origin)

  Lists the instances of an input without parameters, as catalog(byte[]) says.

  Data

  catalog(String input, String origin, Params params)

  Lists the instances of an input, as catalog(byte[]) says.

  Data

  catalog(Path input)

  Lists the instances of a file without parameters, as catalog(byte[]) says.

  Data

  catalog(Path input, Params params)

  Lists the instances of a file, as catalog(byte[]) says.

  @Nullable String

  format()

  Returns the name of the format that the reader spec reads, or null if it names none.

  static Spec

  parse(byte[] source)

  Parses a reader spec without an origin.

  static Spec

  parse(byte[] source, String origin)

  Parses a reader spec.

  static Spec

  parse(String source)

  Parses a reader spec without an origin.

  static Spec

  parse(String source, String origin)

  Parses a reader spec.

  Data

  read(byte[] input)

  Reads an input without an origin or parameters.

  Data

  read(byte[] input, String origin)

  Reads an input without parameters.

  Data

  read(byte[] input, String origin, Params params)

  Reads an input.

  Data

  read(String input)

  Reads an input without an origin or parameters.

  Data

  read(String input, String origin)

  Reads an input without parameters.

  Data

  read(String input, String origin, Params params)

  Reads an input.

  Data

  read(Path input)

  Reads a file without parameters.

  Data

  read(Path input, Params params)

  Reads a file.

  <R extends Record>
RecordReader<R>

  reader(Class<R> type, MethodHandles.Lookup lookup)

  Makes a reader of data into records of type, after checking every component against the entries that a read can produce, so that a mismatch fails here rather than in a read.

  Methods inherited from class Object

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

• Method Details

  • parse

    public static Spec parse(byte[] source)

    Parses a reader spec without an origin.

    Parameters:

    source - the UTF-8 bytes of the reader spec

    Returns:

    the parsed reader spec

    Throws:

    IrisException - for the first parse-time error

  • parse

    public static Spec parse(byte[] source, String origin)

    Parses a reader spec.

    Parameters:

    source - the UTF-8 bytes of the reader spec

    origin - the name of the source in errors

    Returns:

    the parsed reader spec

    Throws:

    IrisException - for the first parse-time error

  • parse

    public static Spec parse(String source)

    Parses a reader spec without an origin.

    Parameters:

    source - the text of the reader spec

    Returns:

    the parsed reader spec

    Throws:

    IrisException - for the first parse-time error

  • parse

    public static Spec parse(String source, String origin)

    Parses a reader spec.

    Parameters:

    source - the text of the reader spec

    origin - the name of the source in errors

    Returns:

    the parsed reader spec

    Throws:

    IrisException - for the first parse-time error

  • format

    public @Nullable String format()

    Returns the name of the format that the reader spec reads, or null if it names none.

    Returns:

    the name of the format that the reader spec reads, or null if it names none

  • read

    public Data read(byte[] input)

    Reads an input without an origin or parameters.

    Parameters:

    input - the bytes of the input

    Returns:

    the data read

    Throws:

    IrisException - for the first error

  • read

    public Data read(byte[] input, String origin)

    Reads an input without parameters.

    Parameters:

    input - the bytes of the input

    origin - the name of the input in errors

    Returns:

    the data read

    Throws:

    IrisException - for the first error

  • read

    public Data read(byte[] input, String origin, Params params)

    Reads an input.

    Parameters:

    input - the bytes of the input

    origin - the name of the input in errors

    params - the parameters

    Returns:

    the data read

    Throws:

    IrisException - for the first error

  • read

    public Data read(String input)

    Reads an input without an origin or parameters.

    Parameters:

    input - the text of the input

    Returns:

    the data read

    Throws:

    IrisException - for the first error

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • read

    public Data read(String input, String origin)

    Reads an input without parameters.

    Parameters:

    input - the text of the input

    origin - the name of the input in errors

    Returns:

    the data read

    Throws:

    IrisException - for the first error

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • read

    public Data read(String input, String origin, Params params)

    Reads an input.

    Parameters:

    input - the text of the input

    origin - the name of the input in errors

    params - the parameters

    Returns:

    the data read

    Throws:

    IrisException - for the first error

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • read

    public Data read(Path input)

    Reads a file without parameters. Its path is the origin of the input.

    Parameters:

    input - the file

    Returns:

    the data read

    Throws:

    IrisException - for the first error

    UncheckedIOException - if the file cannot be read

  • read

    public Data read(Path input, Params params)

    Reads a file. Its path is the origin of the input.

    Parameters:

    input - the file

    params - the parameters

    Returns:

    the data read

    Throws:

    IrisException - for the first error

    UncheckedIOException - if the file cannot be read

  • catalog

    public Data catalog(byte[] input)

    Lists the instances of an input without an origin or parameters (§9.6). The data has the entry instances with their number, name with their names if all have one, and failed with the first rejection of each if any has one.

    Parameters:

    input - the bytes of the input

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

  • catalog

    public Data catalog(byte[] input, String origin)

    Lists the instances of an input without parameters, as catalog(byte[]) says.

    Parameters:

    input - the bytes of the input

    origin - the name of the input in errors

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

  • catalog

    public Data catalog(byte[] input, String origin, Params params)

    Lists the instances of an input, as catalog(byte[]) says.

    Parameters:

    input - the bytes of the input

    origin - the name of the input in errors

    params - the parameters

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

  • catalog

    public Data catalog(String input)

    Lists the instances of an input without an origin or parameters, as catalog(byte[]) says.

    Parameters:

    input - the text of the input

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • catalog

    public Data catalog(String input, String origin)

    Lists the instances of an input without parameters, as catalog(byte[]) says.

    Parameters:

    input - the text of the input

    origin - the name of the input in errors

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • catalog

    public Data catalog(String input, String origin, Params params)

    Lists the instances of an input, as catalog(byte[]) says.

    Parameters:

    input - the text of the input

    origin - the name of the input in errors

    params - the parameters

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

    IllegalArgumentException - if the text has an unpaired surrogate, which has no UTF-8 form

  • catalog

    public Data catalog(Path input)

    Lists the instances of a file without parameters, as catalog(byte[]) says. Its path is the origin of the input.

    Parameters:

    input - the file

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

    UncheckedIOException - if the file cannot be read

  • catalog

    public Data catalog(Path input, Params params)

    Lists the instances of a file, as catalog(byte[]) says. Its path is the origin of the input.

    Parameters:

    input - the file

    params - the parameters

    Returns:

    the catalog

    Throws:

    IrisException - for the first error that is not a rejection in an instance

    UncheckedIOException - if the file cannot be read

  • reader

    public <R extends Record> RecordReader<R> reader(Class<R> type, MethodHandles.Lookup lookup)

    Makes a reader of data into records of type, after checking every component against the entries that a read can produce, so that a mismatch fails here rather than in a read.

    A component reads the entry of its own name, spelled exactly as the component is, or the entry that its Entry annotation names. Entries without a component are left out. A component's type must be what a typed handle of the entry reads:

    • at depth 0, long or Long for int, double or Double for float, String for string, and Number for num, whose values are int or float as the data decides;
    • at depth 1, long[], double[], List<String> or List<Number>;
    • at each further depth, a List of the type one depth less, as in List<long[]>;
    • at any value type and depth, Value, which an entry with no single value type and depth needs, such as a parameter without a default.

    An entry that a read may leave out needs a reference type annotated @Nullable, as in @Nullable String name, and reads as null when it is absent. JSpecify's annotation does, and so does any other named Nullable that the class file keeps for run time.

    The reader constructs records through their canonical constructor, which lookup finds, so the record's module need not open its package. Pass MethodHandles.lookup() from code that can access the constructor. A method handle can pass at most 253 parameter slots, where a long or double takes two, so a record whose components take 254, the most a constructor can take, is constructed through Constructor.newInstance(Object...) as the lookup class calls it, after the checks that a method handle's lookup makes, which needs a lookup with original access, as MethodHandles.lookup() has.

    Type Parameters:

    R - the record type

    Parameters:

    type - the record class

    lookup - a lookup that can access the canonical constructor of type

    Returns:

    the reader

    Throws:

    IllegalArgumentException - if type is not a record class, if a component names an entry that no read produces or has a type that does not fit its entry, if lookup cannot access the canonical constructor, or if the components take 254 parameter slots and lookup lacks original access