Skip to content

global io

https://github.com/latex3/lualibs/blob/main/lualibs-io.lua

methods

io.readall

function io.readall(f)

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

io.loaddata

function io.loaddata(
  filename: string,
  textmode: any
) ->  any
@param textmode - non-nil|false triggers non-binary mode in certain operating systems.

A wrapper for io.open. Automatically supplies the r flag and handles opening and closing, returns the complete content of file filename. The optional argument textmode when non-nil|false triggers non-binary mode in certain operating systems.

Example:

local f = io.open("./text.txt", "w")
if f then
  f:write("Some Text.")
  f:close()
end

local text = io.loaddata("./text.txt")
io.write(text)

Reference:

io.copydata

function io.copydata(
  source,
  target,
  action
)

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

io.savedata

function io.savedata(
  filename: string,
  data: (string|string[]|fun(object: file*)),
  separator: string?,
  append: any
) ->  boolean

Writes data to file filename. Handles opening and closing routines automatically. data can be generic data, a list or a function. Lists are joined prior to write, using the optional separator as separator (nice for CSV output). Functions are applied to the file object.

Example:

local text = "Some Text."

text = text:gsub(".\n", "") .. " and again " .. text:lower()
io.savedata("./moretext.txt", text)
os.execute("cat ./moretext.txt")

local sometable = { "spam", "spam", "spam", "baked beans", "spam" }
io.savedata("./moretext.txt", sometable, ",")
os.execute("cat ./moretext.txt && echo '\n'")

local function weird_write(obj)
  for i = 1, 10 do
    if i % 2 == 0 then
      obj:write("But cool. ")
    else
      obj:write("Weird. ")
    end
  end
  obj:write("\n")
end

io.savedata("./weirdtext.txt", weird_write)
os.execute("cat ./weirdtext.txt")

Reference:

io.loadlines

function io.loadlines(
  filename,
  n
)

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

io.loadchunk

function io.loadchunk(
  filename,
  n
)

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

io.exists

function io.exists(filename: string) ->  boolean

Tests for file filename's existence and returns a boolean accordingly.

Example:

print(
  io.exists("moretext.txt") and "Yes, you're right (as usual)!"
    or "No, you're wasting your time, Sir!"
)

Reference:

io.size

function io.size(filename: string) ->  integer

Returns the byte count of file filename or 0 if the file is not found.

Example:

local check1 = io.size("moretext.txt")
local check2 = tonumber(
  io.popen([[du -b moretext.txt | sed -e 's/^\([0-9]*\).*/\1/']]):read("*all")
)

io.write(
  "I counted "
    .. check1
    .. " bytes, and it's got "
    .. check2
    .. " bytes according to ‘du’.\nTherefore "
)
io.write(
  check1 == check2 and "the size info should be reasonably accurate.\n"
    or "something's thoroughly wrong.\n"
)

Reference:

io.noflines

function io.noflines(object: file*) -> line_count integer

@return line_count - The line count of a file object object.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Returns the line count of a file object object.

Example:

local f = io.popen("dmesg")
if f then
  local infolength = io.noflines(f)
  f:close()
  print("There's " .. infolength .. " lines in the kernel ring buffer.")
end

Reference:

io.characters

function io.characters(
  object: file*,
  group: (-4|-2|1|2|4)?
) ->  fun() -> (string,string?,string?,string?)

Returns an iterator over the one-byte characters of a file object object. The optional argument group accepts a signed integer which determines the number and byte order of the characters returned simultaneously. Possible values are -4, -2, 1, 2, and 4. Negative values result in the order of the characters to be reversed.

Example:

local f = io.popen("cat ./moretext.txt")
if f then
  for char1, char2 in io.characters(f, 2) do
    io.write(string.format("“%s”, “%s”\n", char1, char2 or ""))
  end
  f:close()
end

f = io.open("./moretext.txt")
if f then
  for char1, char2, char3, char4 in io.characters(f, -4) do
    io.write(
      string.format(
        "1: “%s”, 2: “%s”, 3: “%s”, 4: “%s”\n",
        char1,
        char2 or "",
        char3 or "",
        char4 or ""
      )
    )
  end
  f:close()
end

Reference:

io.bytes

function io.bytes(
  object: file*,
  group: (-4|-2|1|2|4)?
) ->  fun() -> (string,string?,string?,string?)

Returns an iterator over the bytes of a file object. As with io.characters, the optional argument group specifies the number and order of the bytes returned simultaneously. If there fewer bytes left at the end of a file than the absolute of group, then the remainder is ignored. Thus to process the whole file make sure that its size is a multiple of group.

Example:

local f = io.open("./moretext.txt")
if f then
  for char1, char2, char3, char4 in io.bytes(f, 4) do
    io.write(
      string.format(
        "1: “%s”, 2: “%s”, 3: “%s”, 4: “%s”\n",
        char1,
        char2 or "",
        char3 or "",
        char4 or ""
      )
    )
  end
  f:close()
end

Reference:

io.ask

function io.ask(
  question: string,
  default: string?,
  options: string[]?
)

Interrupts the program flow to wait for user input. Prints the string question to stdout and returns the string given by the user. If a string default is given, it is printed in brackets and returned if the user input is empty. options has to be a list of valid input strings which are then printed in brackets as well; no other strings are accepted if options is specified.

Example:

local options = {
  default = "An African or European swallow?",
  other = { "http://www.style.org/unladenswallow/", "42" },
}
local someanswer = io.ask(
  "What is the air speed velocity of an unladen swallow?",
  options.default,
  options.other
)

print(
  someanswer == options.default
      and "I don't know that! /He is thrown into the chasm./"
    or "OK, off you go!"
)

Reference:

io.readnumber

function io.readnumber(
  object: string,
  offset: integer,
  count: integer
) ->  integer

Reads count next bytes from a file object, optionally starting at byte offset. The bytes are treated as representing a single integer which is then returned in base 10. Valid byte counts are 1, 2, 4, 8, and 12; throws an error when there are fewer bytes left from the current position to the end of file than count.

Example:

io.savedata("nums.txt", "\001\001\001\001\002\002\002\002\003\003\003\003")

local f = io.open("nums.txt", "r")
if f then
  print(io.readnumber(f, 1))
  print(io.readnumber(f, 5, 1))
  print(io.readnumber(f, 4))
  print(io.readnumber(f, 2))
  f:close()
end

Reference:

io.readnumber

function io.readnumber(
  object: string,
  count: integer
) ->  integer

Reads count next bytes from a file object, optionally starting at byte offset. The bytes are treated as representing a single integer which is then returned in base 10. Valid byte counts are 1, 2, 4, 8, and 12; throws an error when there are fewer bytes left from the current position to the end of file than count.

Example:

io.savedata("nums.txt", "\001\001\001\001\002\002\002\002\003\003\003\003")

local f = io.open("nums.txt", "r")
if f then
  print(io.readnumber(f, 1))
  print(io.readnumber(f, 5, 1))
  print(io.readnumber(f, 4))
  print(io.readnumber(f, 2))
  f:close()
end

Reference:

io.readstring

function io.readstring(
  object: string,
  offset: integer,
  length: integer
) ->  string

Returns the next length bytes from object, starting from the current position or, optionally, the byte offset.

Example:

local f = io.open("text.txt", "r")
local str = io.readstring(f, 5, 3)
print(str)
if f then
  f:close()
end

Reference:

io.readstring

function io.readstring(
  object: string,
  length: integer
) ->  string

Returns the next length bytes from object, starting from the current position or, optionally, the byte offset.

Example:

local f = io.open("text.txt", "r")
local str = io.readstring(f, 5, 3)
print(str)
if f then
  f:close()
end

Reference: