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

Functions

Load file at path into string.

Parameters

• path — which file to load

Return

• a string containing the file contents as bytes
• an empty string, if the file does not exist or could not be opened

Save data to file at path.

Parameters

• path — where to save the file
• data — the bytes to save

Return

• true if the file was saved, otherwise false

Prompt for user input.

Parameters

• q — the question to print to the user on the same line

Return

• a string containing the user's input

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
##

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

• index — the current step (first step = 0)
• total — the total number of steps (last step = total-1) or 0 if the total is unknown
• message — the status message for the current step

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.

Wrap string with ANSI color codes.

Parameters

• code — the color code, see notes for details
• s — the string to wrap

Return

• the wrapped string, like: [color sequence][s][reset sequence]

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')

Determine whether or not file exists.

Parameters

• path — the path of the file

Return

• true if the file exists, otherwise false

Remove (delete) file at path.

Parameters

• path — the path of the file

Return

• true on success, otherwise false

Rename file from old_name to new_name.

Parameters

• old_name — the current name of the file
• new_name — the name to change it to

Return

• true on success, otherwise false

@file Methods

Construct a stream to a file.

Parameters

• path — the file to open
• flags — the behavior of the stream, see notes for details (optional, default is 'rb')

Return

• a new file object if successful
• null if unable to open file, or file not found (if reading)

Notes

The flags can by any of the following:

• 'rb' — open file for reading in binary mode
• 'r' — open file for reading in text mode
• 'wb' — open file for writing in binary mode
• 'w' — open file for writing in text mode
• 'ab' — open file for appending in binary mode
• 'a' — open file for appending text mode

The underlying implementation uses fopen().

Read n bytes from the stream.

Parameters

• n — the number of bytes to read

Return

• a string containing the bytes read

Write bytes s to stream.

Parameters

• s — a string of bytes to write

Return

• the number of bytes actually written

Notes

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

Seek stream to a position within the file.

Parameters

• pos — the position in bytes, see notes

Return

• true if successful, otherwise false

Notes

If pos is >= 0, the position seeked is relative to the beginning of the file. If pos is < 0, the position seeked is relative to the end of the file.

Read a single line from the file.

Return

• a string containing the line read from the file (without trailing newline)
• null, if end of file reached

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 CSV (comma-separate values) file at path.

Parameters

• path — the path of the CSV file

Return

• a 2D array containing the contents of the CSV file

Save data to CSV file at path.

Parameters

• path — where to save the CSV file
• data — a 2D array of data

Return

• true if successful, otherwise false

Parse string as CSV.

Parameters

• s — a string containing CSV data

Return

• a 2D array containing the CSV data

Escape a single CSV value

Parameters

• value — the value to escape

Return

• the escaped value

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 a single line of CSV.

Parameters

• line — a single line of comma-separated values

Return

• an array containing the values

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 HTML table.

Parameters

• html — the HTML code containing table data

Return

• a 2D array containing the table data

Notes

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

Extract text from HTML.

Parameters

• html — a string containing HTML

Return

• a string containing the text content of the HTML

Notes

This is similar to .textContent in Javascript.

@ini Functions

Load .ini/.conf/.cfg file.

Parameters

• path — the path of the file

Return

• an object containing the parsed data

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 a JSON file.

Parameters

• path — the path of the file

Return

• an object containing the parsed data

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 data to JSON file at path.

Parameters

• path — where to save the JSON file
• data — the data

Notes

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

@text Functions

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

Parameters

• a — the left text document contents as a string
• b — the right text document contents as a string
• ignore_whitespace — whether or not to ignore whitespace (optional, default is false)
• diff_format — whether or not to imitate the output format of the Unix "diff" tool (optional, default is false)

Return

• the diff as a string

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
##

Do a three-way merge of related text documents.

Parameters

• parent — the original text document
• child_a — the left modified text document
• child_b — the right modified text document

Return

• a string containing the contents of a text document with all modifications merged

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
##

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

Parameters

• versions — the previous versions of the text file, in order, as an object mapping note to text (see example for details)
• separator — the string to use as a separator between the note and the text document line (optional, defaults to '| ')
• width — the width of the note (optional, defaults to 14)

Return

• the annotated text document

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
##

@xml Functions

Parse and query an XML string for certain nodes.

Parameters

• xml — a string containing XML
• selector — a string that defines which nodes to select, see notes for details

Return

• an array of objects, one for each matching node, see notes for details

Notes

The selector syntax is as follows:

• tag name: tag
• any descendant: tag anydesc
• direct descendant: tag > directdesc
• has attribute: [attrib]
• has attribute with exact value: [attrib=value]
• has attribute with value that is not something: [attrib!value]
• has attribute with value that contains something: [attrib~something]
• has attribute with value that doesn't contain something: [attrib^something]
• has class (for HTML support): .classname (matches like [class~classname], except mindful of whitespace)

Be careful when using the direct descendant selector (>) with HTML, because it is common for HTML tags to be unclosed by XML standards. For example, in the following HTML, in order to select "two", the selector "ul > li" won't work, because the "li" tags are unclosed:

<ul>
	<li>one
	<li>two
</ul>

Each returned node is an object with the following attributes:

• name — the tag name
• attr — an object like:

  {
  	attribute_name: value,
  	...
  }

• body — the inner contents of the node (can be text or more XML)

Example

#extract links from website
html = web.get('https://www.iana.org/help/example-domains')
links = io.xml.query(html,'a[href]')
print links
##
[ 
  {
    "name" : "a",
    "attr" : 
    {
      "href" : "/"
    },
    "body" : ""
  }, 
  ...
  {
    "name" : "a",
    "attr" : 
    {
      "href" : "https://www.icann.org/privacy/tos"
    },
    "body" : "Terms of Service"
  } ]
##