Define distinct error types for panics

[jclark]

The language spec (including the langlib documentation) should specify panics in more detail. At the moment, it just says there's a panic without going into any detail about the error value associated with the panic.

Langlib (probably mostly in lang.error) should define categorize possible panics using distinct error types. When the spec says there's a panic, it should further give the error type (as defined in langlib) of the error value associated with the panic. In some cases, it could also specify a detail record.

[jclark]

jBallerina's list of runtime errors are here.

[jclark]

Here's a first cut at categorization.

1. Arithmetic
   1. int overflow: arithmetic operation on ints that results in a value that does not fit in 64-bits
   2. decimal overflow: arithmetic operation on a decimal that results in a value with a magnitude that is greater than can be represented by a decimal (our decimals do not have infinities)
   3. int divide by zero: integer / or % with a second operand that is zero
   4. decimal divide by zero: integer / or % with a second operand that is zero (our decimals do not have NaNs)
   5. type cast fails because a numeric conversion fails
2. Limits on lengths of sequences/structures (there's always a limit of the maximum value of a signed 64-bit int, but implementations will typically have lower limits for at least some basic types)
   1. attempt to construct or mutate an array in a way that would cause its length to exceed an implementation limit (e.g. writing to an index that is > maximum supported index)
   2. attempt to construct a string whose length would exceed an implementation limit (e.g. by reading a file bigger than 2Gb)
   3. attempt to construct an xml text item that would have data that is a string with a length exceeding an implementation limit (e.g. by an XML template expression)
   4. attempt to construct an xml sequence with a length that would exceed an implementation limit
   5. attempt to construct a table with a length that would exceed an implementation limit
   6. attempt to construct a mapping value with a length that would exceed an implementation limit
3. Reading a constituent/member of a sequence/structure
   1. out of bounds index when getting a member of an array
   2. out of bounds index when getting a constituent of an xml sequence (xml:get)
   3. out of bounds index when getting a constituent of a string
   4. non-existent key when getting a member of a map (map:get)
   5. non-existent key when getting a member of a table (table:get)
4. Mutation of selectively immutable basic types
   1. attempt to mutate a read-only value
   2. attempt to mutate a read-only field of a record
   3. attempt to mutate a mapping that is inconsistent with mapping's inherent type
   4. attempt to mutate a mapping by a filling-read, but there no filler value for the type descriptor of the member to be filled in
   5. attempt to mutate a list that would be inconsistent with mapping's inherent type
   6. attempt to mutate a list that would require a member to be filled in, but there is no filler value for the type descriptor of that member (i.e. write to an index that is > the current length)
   7. attempt to mutate a member of an array with a negative index
   8. attempt to mutate an object field that is inconsistent with the type of the field
   9. attempt to mutate a final field of an object
   10. attempt to mutate a table by adding a member with a type that is inconsistent with the table's inherent type (table:add, table:put)
   11. attempt to mutate a table by adding a member that has a key that conflicts with the key of an existing member (table:add)
5. XML-specific
   1. invalid XML code point: a string is used in constructing an XML value and the string contains code points that are not allowed by XML
   2. invalid XML qname: a string is used to specify the name of an XML element or attribute, but the name is not a valid XML qname
   3. invalid XML processing instruction target (xml:createProcessingInstruction)
   4. invalid XML processing instruction content (e.g. containing ?>), which means it cannot be serialized as XML (xml:createProcessingInstruction)
   5. invalid XML comment content (e.g. containing --), which means it cannot be serialized as XML (xml:createComment)
6. Type cast fails otherwise than because of a numeric conversion failure
7. Resource limits
   1. out of memory

[jclark]

@manuranga My current thinking is to have a distinct type Panic in lang.error, and then distinct subtypes XyzPanic for each specific panic. It's more convenient to use error:Panic than runtime:Panic because the error prefix is predeclared.

[manuranga]

My current thinking is to have a distinct type Panic in lang.error

Sounds good.

Should we also recommend users (eg: stdlib) to subtype from error:Panic to indicate that it's intended to be paniced with (instead of being returned).

If so, panicking with a non-error:Panic subtype should be be which of the following: Ok / Not recommend / Compile time warning / Compile time error

[jclark]

@manuranga I made a separate issue #839 for this.