Use custom ExitCode values to indicate different failure types

[recursion-ninja]

We can use different ExitCode values to indicate the different types of failure that can occur during our computation.

There are very refined failure types in the following modules:

• PCG.Command.Read.Unification.UnificationError
• PCG.Command.Read.ReadError

Each one of these error conditions could receive a special ExitCode value to be checked after the program completes. The benifit of this is that we can check the ExitCode value in our integration test suite to ensure that certain expected failure occur, and not just that "any" failure has occurred.

This change will require a little bit of tinkering with the EvalUnit type. The Error constructor should contain an Int8 for the ExitCode value. The fail function should supply a default ExitCode value. We will export a new function failWith :: Int8 -> String to allow for failing with a specific exit code in the EvaluationT monadic context.

[recursion-ninja]

Document what each custom exit code means in the PCG help menu.

[recursion-ninja]

Unfortunately, this was more involved than anticipated and there has been some scope-creep when attempting to make the changes consistent and well-typed.

pcg-error-phase:

• [x] move back to pcg-evaluation

pcg-validationT:

• [x] add library for transformer
• [x] add test suite
• [x] add documentation explaining use case and law violation.

pcg-file-source:

• [x] separate Data.FileSource into separate file-source library
• [x] move InputStreamError here
• [x] create OutputStreamError
• add Data.FileSource.IO
  • [x] add readFile :: FileSource -> ValidationT InputStreamError IO Text
  • [x] add serializeBinary :: FileSource -> ValidationT InputStreamError IO a
  • [x] add serializeCompact :: FileSource -> ValidationT InputStreamError IO a
  • [x] add deserializeBinary :: FileSource -> a -> ValidationT OutputStreamError IO ()
  • [x] add derializeCompact :: FileSource -> a -> ValidationT OutputStreamError IO ()
  • [x] add appendFile :: FileSource -> Text -> ValidationT OutputStreamError IO ()
  • [x] add writeFile :: FileSource -> Text -> ValidationT OutputStreamError IO ()
  • [x] add writeFileWithMove :: FileSource -> Text -> ValidationT OutputStreamError IO ()

pcg:

• [x] update PCG.Load to use Data.FileSource.IO.deserializeBinary/deserializeCompact
• [x] update PCG.Save to use Data.FileSource.IO.serializeBinary/serializeCompact
• [x] update PCG.Report to use Data.FileSource.IO.appendFile/writeFile/writeFileWithMove
• [x] update PCG.Report to collect OutputStreamErrors when writing to multiple streams
• [x] update PCG.Read to collect InputStreamErrors when reading to multiple streams
• [x] update Main to use Data.FileSource.IO.readFile for reading input scripts
• [x] add --exitcodes flag to print exit code documentation

CHANGELOG.md:

• [x] add description of changes

[recursion-ninja]

• [ ] Add an integration test to try and open 1024 small files at once.
• [x] Add more integration tests to test new failure cases.
• [x] Add integration test to ensure that parse errors are pre-empted by input errors.
• [x] Add integration test to ensure that unification errors are pre-empted by input errors.
• [x] Add integration test to ensure that unification errors are pre-empted by parse errors.

[recursion-ninja]

• [x] Use Conduit, Pipes, Streamly, or whatever is best for writing out and reading in lazy Text from disk.

[recursion-ninja]

• [x] Clean up the TextShow instances to render error messages without escaped strings in the output.

[recursion-ninja]

I decided not to add an integration test of opening 1024 small files at once. The files all open successfully, but there appears to be efficiency issues associated with that many character blocks.

Profiling and remedying this efficiency issue is beyond the scope of this issue.

[recursion-ninja]

This has been completed, see 4db324b.