Slag:Readers and Writers

From Plasmaworks

Virtually all Slag I/O is expressed in terms of templated Readers and Writers that are specialized and extended to handle specific data types.

Something that incorporates Readable<<Char>> can have create_reader() called on it, which in turn instantiates and returns a Reader<<Char>> object - likewise with Writers and Writable things. forEach loops work with both Readable objects and Reader objects, automatically calling create_reader() on the former.

In Slag terminology, a Reader<<DataType>> reads a single unit of "DataType" at a time and a Writer<<DataType>> writes a single unit of "DataType" at a time. Actions such as printing, scanning, and inputting require extra translation between datatypes and values and thus do not use the method names read and write.

Contents 1 Common Reader Classes and Aspects 2 Common Writer Classes and Aspects 3 Using StringBuilder 4 Working with Files 4.1 Read Every Character From A File 4.2 Load a File as a Byte List 4.3 Load a File as a String 4.4 Load Each Line of a File as a String 4.5 Creating a Text File 4.6 Creating a Binary File 4.7 Reading a Binary File

Common Reader Classes and Aspects

For documentation on any of these, type e.g. gogo doc Readable<<Char>> or gogo doc "Reader<<String>>::peek".

Readable<<DataType>>

Classes incorporating this aspect define the method create_reader().Reader<<DataType>>.

Reader<<DataType>>

Classes incorporating this aspect define the methods has_another().Logical, read().DataType, and peek().DataType.

LineReader

Utility Reader<<String>> class that wraps a Reader<<Char>> or Readable<<Char>> and returns one line at a time (discarding the newlines). Example:

 forEach (line in LineReader(File("data.txt"))) println(data)

FileReader

An extended Reader<<Char>> returned from a call to File::create_reader().

Scanner

Primary way of parsing text data. Create with a String or File parameter, then call next_is_Int32().Logical, scan_Int32().Int32, etc. Unlike the Java Scanner it will fail rather than skip input if asked to read a certain type of data that is not the next value.

ParseReader

An excellent class for writing custom compilers.

BitReader

A specialized Reader<<Char>> that can read arbitrary numbers of bits at a time. You must [include "bit_io.slag"] before you can use in code or obtain a doc listing.

Common Writer Classes and Aspects

Writable<<DataType>>

Classes incorporating this aspect define the method create_writer().Writer<<DataType>>.

Writer<<DataType>>

Classes incorporating this aspect define the methods write(DataType), flush(), and close().

TextWriter

An extended Writer<<Char>> that defines various print() operations for encoding data into character form.

FileWriter

An extended Writer<<Char>> returned from a call to File::create_writer() or File::create_appender().

BitWriter

A specialized Writer<<Char>> that can write arbitrary numbers of bits at a time. You must [include "bit_io.slag"] before you can use in code or obtain a doc listing.

Using StringBuilder

 local StringBuilder buffer()
 buffer.println( "Coordinates ($,$)" (3,4) )
 buffer.println( "END OF LINE" )
 local String st = buffer.to_String
 println( st )  # prints: Coordinates (3,4)
                #         END OF LINE

Working with Files

Read Every Character From A File

 forEach (ch in File("data.txt")) print( ch + "." )

Load a File as a Byte List

 local Byte[] bytes = File("data.txt").load

Load a File as a String

 local String st = String.create_from( File("data.txt" )

Load Each Line of a File as a String

 forEach (line in LineReader(File("data.txt"))) println(line)

Creating a Text File

 local var writer = File("file.txt").create_writer
 writer.println( "Print" );
 writer.println( stuff );
 writer.close

Creating a Binary File

 local BitWriter writer( File("file.bin").create_writer )
 writer.write( ch )     # write 'ch' in 8 bits
 writer.write( x, 16 )  # write 'x' in 16 bits
 writer.write( b, 1 )   # write 'b' in 1 bit
 writer.close

Reading a Binary File

 local BitReader reader( File("file.bin").create_reader )
 local Char ch = reader.read
 local Int32 x = reader.read(16)
 local Logical b = (reader.read(1) == 1)
 reader.close