The @io module contains functions and classes related to standard/file input/output and manipulating various text file formats.

Functions

:load(path) #

Load file at path into string.

Parameters

Return

:save(path,data) #

Save data to file at path.

Parameters

Return

:prompt(q) #

Prompt for user input.

Parameters

Return

Example

f = io.prompt('Degrees in F? ').number() c = (f-32)*5/9 print '=>',c,'degrees in C' ## Degrees in F? 99 => 37.2222 degrees in C ## :status(index,total,message) #

Print a status message. Multiple calls will re-use the same line. This is meant to be called within a loop to give progress feedback to the user.

Parameters

Notes

The output is limited to 79 characters, so that it will fit one line of a terminal 80 characters wide.

This function prints to stderr.

At the last step (index+1 == total) a newline is printed.

Example

for n,1000 io.status(n,1000,'step: '+n) os.sleep(10) print 'Done.' #while running: #[203/1000] (20.3%) step: 202 #when done: #[1000/1000] (100.0%) step: 999 #Done. :color(code,s) #

Wrap string with ANSI color codes.

Parameters

Return

Notes

The code should be like "format;color" or just "format" or "color". See the following chart for formats/colors:

Colors black 30 red 31 green 32 yellow 33 blue 34 magenta 35 cyan 36 white 37 Formats bold/bright 1 underline 4 inverse 7

Reset/off codes aren't included here because they are not necessary (this function automatically ends the string with a reset sequence). Background colors aren't included here because they do not seem to work on most terminals.

Example

print io.color('1;31','This is bold red') print io.color('32','This is green') print io.color('4','This is underlined') :exists(path) #

Determine whether or not file exists.

Parameters

Return

:remove(path) #

Remove (delete) file at path.

Parameters

Return

:rename(old_name,new_name) #

Rename file from old_name to new_name.

Parameters

Return

@file Methods

:new(path,flags) #

Construct a stream to a file.

Parameters

Return

Notes

The flags can by any of the following:

The underlying implementation uses fopen().

:read(n) #

Read n bytes from the stream.

Parameters

Return

:write(s) #

Write bytes s to stream.

Parameters

Return

Notes

The return value is equal to s.len() unless there is an error.

:seek(pos) #

Seek stream to a position within the file.

Parameters

Return

:read_line() #

Read a single line from the file.

Return

Notes

The character '\r' is ignored for cross-platform compatibility.

Example

f = io.file('bigfile.txt') while (line = f.read_line())!=null print 'LINE:',line

@csv Functions

:load(path) #

Load CSV (comma-separate values) file at path.

Parameters

Return

:save(path,data) #

Save data to CSV file at path.

Parameters

Return

:parse(s) #

Parse string as CSV.

Parameters

Return

:escape(value) #

Escape a single CSV value

Parameters

Return

Notes

If value contains commas or newlines, it is quoted and quotes within are replaced with two quotes. If value contains no commas or newlines, nothing is done.

:split_line(line) #

Split a single line of CSV.

Parameters

Return

Notes

This is useful if the CSV file is too big to read into memory at once.

Example

f = io.file('bigfile.csv') while (line = f.read_line())!=null print 'VALUES:',io.csv.split_line(line)

@html Functions

:parse_table(html) #

Parse HTML table.

Parameters

Return

Notes

Only <tr> and <td> tags are parsed. This does fuzzy parsing for maximum compatibility.

:get_text(html) #

Extract text from HTML.

Parameters

Return

Notes

This is similar to .textContent in Javascript.

@ini Functions

:load(path) #

Load .ini/.conf/.cfg file.

Parameters

Return

Notes

Comments can be indicated with either ';' or '#'.

Each subsection in the .ini file becomes a subobject.

Any whitespace around the '=' is ignored. On any line, leading or trailing whitespace is ignored.

Value can be JSON literals. If values failed to parse as JSON, they are parsed as strings.

Example

#test.ini: ## ;this is a comment #also a comment asdf = narf local = false port = 1234 [narf] asdf = [1,2,3] zxcv = 3 ## print io.ini.load('test.ini') ## { "asdf" : "narf", "local" : false, "port" : 1234, "narf" : { "asdf" : [1,2,3], "zxcv" : 3 } } ##

@json Functions

:load(path) #

Load a JSON file.

Parameters

Return

Notes

This is equivalent to io.load(path).parse_json().

JSON serialization and parsing are part of the core library, and therefore not repeated here. See :parse_json() and :json().

:save(path,data) #

Save data to JSON file at path.

Parameters

Notes

This is equivalent to io.save(path,data.json()).

@text Functions

:diff(a,b,ignore_whitespace,diff_format) #

Compare the contents of two text documents and output the diff.

Parameters

Return

Notes

A diff is a specially-formatted string that show the line-by-line differences between two text files. This string is commonly displayed in source control software and with the Unix "diff" tool.

If diff_format is false, the output is "source control" style, in which differences are prefixed by '-' or '+'. If diff_format is true, the output is "diff tool" style, in which differences are prefixed by '<' or '>', and separated by '---'.

Example

a = ` a b c ` b = ` a z c ` print io.text.diff(a,b) ## 2+1,2+1 - b + z ## print io.text.diff(a,b,false,true) ## 2+1,2+1 < b --- > z ## :merge(parent,child_a,child_b) #

Do a three-way merge of related text documents.

Parameters

Return

Notes

A three-way merge is useful to incorporate modifications when two parties have edited a single document simultaneously. If both parties have deleted a line, then the line will be deleted in the merged result. If both parties have modified the same line, the left modification will appear before the right modification; any conflicts must be manually detected and resolved. If either party has modified a line which the other party did not modify, the modification will appear in the merged result.

Example

parent = ` The quick brown fox ` child_a = ` quick brown fox ` child_b = ` quick lazy dog ` print io.text.merge(parent,child_a,child_b) ## quick lazy dog ## :annotate(versions,separator,width) #

Produce an annotated text document, given an object of previous versions.

Parameters

Return

Notes

An annotated text document is useful when you have the version history of a text document, and you want to know which version added which line. It is typically produced by source control software, and sometimes also called "blame" (the idea being, if you found a bug in a certain line of code, you can find who to blame).

The result is the final text document, except that each line is prefixed with the note corresponding to each version. To preserve the legibility of the annotated result, the prefix has a fixed width and is separated from the text content documents with separator.

Example

versions = {} #maps note => text, in order versions['first draft'] = ` hello world ` versions['capitalized hello'] =` Hello world ` versions['added stuff'] = ` Hello there world ` print io.text.annotate(versions) ## capitalized he| Hello added stuff | there first draft | world ##