Engee documentation

Input/Output functions

The Input/Output functions in Julia provide the ability to work with files, data streams, and other data sources/sinks (for more information, see I/O and Network). For files imported into the file browser, the following functions can be applied:

Discovery

open — opening a file or data stream.

Details

Function open it provides convenient and secure work with files, because after using the file in the context of a call open The file is automatically closed, which helps to avoid resource leaks or other problems associated with implicitly leaving files open.

The function applies the function f to the result open(args...; kwargs...) and closes the handle of the resulting file upon completion.

open(f::Function, args...; kwargs...)

A file descriptor is an abstract concept used to represent an open file in a program. It is a data structure that contains information about a file, such as its path, access mode (read, write, etc.), current position in the file, and other properties. Examples:

write("my_file.txt", "Hello world!"); # a file is being created my_file.txt containing the text Hello world!

open(io->read(io, String), "my_file.txt")
"Hello world!" # opens my_file.txt for reading and immediately reads its contents into a string

rm("my_file.txt") # deletes my_file.txt after its contents have been read and output

Function io→read(io, String), which accepts an input/output (io) object and reads its contents into a string. After that, the contents of the file "my_file.txt " is output as a result, and eventually the string is obtained. "Hello world!".

Opens the file in the mode specified by five logical named arguments:

open(filename::AbstractString; lock = true, keywords...) -> IOStream

Keyword

Description

By default

read
write
create
truncate
append

open for reading
open for recording
create if it does not exist
crop to zero size
perform the search to the end

!write
truncate | append
!read & write | truncate | append
!read & write
false

By default, if no keywords are transmitted, the files will be read-only. The stream returns to access the open file. Named argument lock determines whether operations will be blocked for secure multithreaded access.

An alternative opening syntax that uses a mode descriptor based on string operations instead of five logical arguments. The mode values correspond to the values from fopen(3) or Perl open and are equivalent to setting up the following logical groups:

Mode

Description

Keywords

r
w
r+
w+
a+

read
read, create, crop
read, create, attach
read, write
read, write, create, crop
read, write, create, attach

no write = true
append = true
read = true, write = true
truncate = true, read = true
append = true, read = tru

Examples:

io = open("my_file.txt", "w"); # opens my_file.txt for writing (write)

write(io, "Hello world!"); # writes the string Hello world! to the file that was opened for writing in the previous line

close(io); # closes my_file.txt , freeing up resources and completing the write operation

io = open("my_file.txt", "r"); # opens my_file.txt for reading (read), returns an input/output object (io)

read(io, String) # reads the contents of the my_file file.txt as a string
"Hello world!" # the result of the operation

write(io, "This file is read only") # since the file was opened read-only (on the previous line), this write operation is not allowed and will generate an ArgumentError error.
ERROR: ArgumentError: write failed, IOStream is not writeable
[...]

close(io) # closes the file my_file.txt after a write attempt to free up resources

io = open("myfile.txt", "a"); # opens my_file.txt to add (append), which will allow writing data to the end of the file without deleting or overwriting its contents

write(io, "This stream is not read only") # writes the line "This stream is not read only" to the end of the file my_file.txt because the file was opened in append mode ("a"). The write function returns the number of bytes written (28)
28 # the result of the operation

close(io)# closes my_file.txt after performing all write operations to free up resources

rm("my_file.txt") # deletes the file my_file.txt

Learn more about all the features of the function open read in I/O and Network.

isopen — determines whether the object (thread or timer) is already closed.

Details

After the object is closed, it will no longer be able to create new events. However, given that a closed stream can still contain read data in the buffer, you should use eof to check if the data can be read. Use the FileWatching package to receive notifications if writing to or reading from a stream is supported. The function outputs true if the object is open and false if the object is closed.

io = open("my_file.txt", "w+"); # opens the file my_file.txt in "w+" mode (write and read)

isopen(io) # checks whether the file associated with the io I/O object is open (my_file.txt )
true # the result of the operation

close(io) # closes the file associated with the io I/O object. After closing, the file is no longer available for writing or reading.

isopen(io) # after the file has been closed (the previous operation), the command returns false because the file is no longer open.
false # the result of the operation

For the function io = open("my_file.txt", "w+"):

  • If the file does not exist, it will be created.

  • If the file already exists, its contents will be deleted.

Function open It also returns an input/output object. (io), which is associated with an open file.

Closure

close — closes the input/output stream.

Details

First, it runs flush (forced reset of I/O).

close(io)

closeall — closes all open windows of the graphical user interface.

Details

This is useful if you need to make sure that all files are closed before terminating the program.

closeall()

closeread — closes only the read stream from the file associated with the input/output object.

Details

If the file has been opened for reading and writing, the write stream remains open. It is used to close the read-only stream, with the option to continue writing to the file.

closeread(io)

closewrite — stops recording half of the full-duplex I/O stream.

Details

Operation flush executed first. Notifies the other party that data is no longer being written to the base file. This operation may not be supported for some I/O types.

Examples:

io = Base.BufferStream(); # a new buffered input/output stream is created. In this case, the lock is never executed, so read and write operations are available for the same job.

write(io, "request"); # the request string is written to the buffered io stream

# when calling `read(io)` here, a permanent lock is applied.

closewrite(io); # The io write stream is closed and no write operations will be accepted, while the read stream remains open.

read(io, String) # a read operation is being performed from io

Record

write — Writes a representation of the canonical binary value file to a specified input/output stream or file.

Details

Returns the number of bytes written to the stream. The byte order in the recorded value depends on the byte order in the host system.

You can write multiple values with a single write call, meaning the following values are equivalent:

write(io, x, y...)
write(io, x) + write(io, y...)

Examples:

# Consistent serialization

fname = tempname(); # arbitrary temporary file name

open(fname,"w") do f
             # Make sure that a 64-bit integer value is being written in the direct byte order format.
             write(f,htol(Int64(42)))
         end
8

julia> open(fname,"r") do f
             # Perform the reverse conversion to the basic byte order and the basic integer type
             Int(ltoh(read(f,Int64)))
         end
42

# Combining write operation calls:

io = IOBuffer();

write(io, "JuliaLang is a GitHub organization.", " It has many members.")
56

String(take!(io))
"JuliaLang is a GitHub organization. It has many members."

write(io, "Sometimes those members") + write(io, " write documentation.")
44

String(take!(io))
"Sometimes those members write documentation."

# User-defined core data types without write methods can be written, and notably encapsulated in Ref

struct MyStruct; x::Float64; end

io = IOBuffer()
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)

write(io, Ref(MyStruct(42.0)))
8

seekstart(io); read!(io, Ref(MyStruct(NaN)))
Base.RefValue{MyStruct}(MyStruct(42.0))

flush — forcibly writes all buffered data from the input/output stream to the base device (for example, to disk).

Details

Function flush ensures that all data that has been written to the stream (for example, using write), but could be temporarily stored in a buffer in memory, will be physically written to the final destination (file, socket, etc.). Used before operations where it is necessary to make sure that the data is saved (for example, before closing a file or before another program starts reading this file).

io = open("log.txt", "w")
write(io, "Important message 1\n")
write(io, "Important message 2\n")

# The data may still be in a buffer in memory, not in a file.
# Calling flush ensures that they are written to disk.
flush(io)

# Now you can be sure that "log.txt " contains up-to-date data.
read("log.txt", String)
"Important message 1\ Important message 2\n"

close(io)
rm("log.txt")
Function close automatically calls flush before closing the stream.

iswritable — checks whether writing to the specified object is supported.

Details

Returns false if writing to the specified I/O object is not supported.

Examples:

open("my_file.txt", "w") do io
    print(io, "Hello world!");
    iswritable(io)
end
true

open("my_file.txt", "r") do io
    iswritable(io)
end
false

rm("my_file.txt")

Reading

read — reads the contents of the file.

Details

By default read reads the file in binary mode:

read("sample1.json")

# conclusion
65-element Vector{UInt8}:
 0x7b
 0x0a
 0x20
 0x20
 0x20
    ⋮

To avoid representation as an array of bytes, it is recommended to use the representation argument. For example, the function read it can take several arguments, including the data type to convert the file contents to (using String):

read("sample1.json", String) # reads the contents of the sample1 file.json and returns it as a string

# withdrawal
"{\n    \"fruit\": \"Apple\",\n    \"size\": \"Large\",\n    \"color\": \"Red\"\n}"

You can read the first character from the file and return it in Char format (character type) using the Char argument.:

read("sample1.json", Char)

# conclusion
'{': ASCII/Unicode U+007B (category Ps: Punctuation, open)

This function read(file_name::IOStream, number_of_bytes::Integer) performs reading no more than number_of_bytes bytes from the stream file_name and returns an array Vector{ UInt8 }, containing a few bytes. To receive a stream from a file, you need to open it for reading. For example:

open("sample1.json", "r") # opening the file for reading

# output of the reading result
IOStream(<file sample1.json>)

read("sample1.json", 10) # reading the first 10 bytes from the file

# conclusion
10-element Vector{UInt8}:
 0x7b
 0x0a
 0x20
 0x20
 0x20
 0x20
 0x22
 0x66
 0x72
 0x75
A stream is an abstraction of data, which is a sequence of bytes. The sequence can be read or written both from sources and in them. For example, text files, network connections, memory, etc. Streams can also be used to read data from a source (input) or write data to it (output). Use:

  • flush — captures all the entries currently in the buffer in this stream.

  • close(stream) — closes the input/output stream. Performs flush first of all.

  • closewrite(steam) — disables half of the recording of a full-duplex stream. Performs flush first of all. No more data will be written to the base file. This is not supported by all I/O types.

You can execute cmd commands using the function read. For example, let’s create a command date (displays the current date and time):

# creating a command that outputs the current date and time
cmd = `date`

read(cmd) # outputs the result as an array of bytes

read(cmd, String) # outputs the result as a string
# conclusion
"Thu Mar 28 07:44:58 UTC 2024\n"

read! — Reads binary data from an input/output stream or file, filling in the data matrix.

Details

Function read! It is used to read data from an input/output stream or file into a pre-allocated buffer or array. It is usually used to efficiently fill an array with data from an external source without creating additional temporary arrays. To receive a stream from a file, you need to open it for reading. For example:

open("sample1.json", "r") # opening the file for reading

my_array = zeros(UInt8, 5) # an array of 5 UInt8 type elements filled with zeros is created
# conclusion
5-element Vector{UInt8}:
 0x00
 0x00
 0x00
 0x00
 0x00

read!("sample1.json", my_array) # reads data from sample1.json and fills the my_array array with them
# conclusion
5-element Vector{UInt8}:
 0x7b
 0x0a
 0x20
 0x20
 0x20

readavailable — reads the available buffered data from the stream.

Details

If there is data in the stream that has not been read yet, the function will return this data. The actual I/O is performed only if the data has not been buffered yet. If there is no data in the buffer, the function returns an empty byte array.

The amount of data returned will depend on the implementation, for example, it may depend on the internal buffer size selection. Instead, you should generally use other functions such as read. 
IOS=open("sample1.json", "r") # opens the file in read mode and writes it to the contents of the IOS I/O buffer

readavailable(IOS) # reads available data from the I/O buffer and returns it

readbytes! — reads no more than nb bytes from stream to b, returning the number of bytes to be read.

Details

Function readbytes! reads no more than n bytes from the stream and writes them to the data array. If n if not specified, it reads the number of bytes equal to the length of the array. Then it returns the number of bytes read. If fewer bytes are available in the stream than requested, only the available number of bytes will be read.

IOS=open("sample1.json", "r") # opens the file in read mode and writes it to the contents of the IOS I/O buffer

buffer = Vector{UInt8}(undef, 5) # an empty buffer array of type UInt8 with a length of 5 elements is created

readbytes!(IOS, buffer) # reads 5 bytes from the IOS stream and saves them to the buffer array

# conclusion
5 # as a result, a number is output that indicates the number of bytes successfully read. Since the array consisted of 5 elements, it was fully successfully read.

readchomp — reads the entire file as a line and deletes one line break character at the end (if any).

Details

Function readchomp equivalent to chomp(read(x, String)).

write("my_file.txt", "Welcome to Engee.\n");

readchomp("my_file.txt")

# the conclusion
is "Welcome to Engee."

readdir — returns the names in the directory (dir) or the current working directory, if it is not specified.

Details

Function readdir it is used to read the contents of a directory. It returns an array of strings, each of which represents the name of a file or subdirectory in the specified directory.

By default readdir sorts the list of returned names. To skip sorting the names and get them in the order they are listed in the file system, you can use readdir(dir, sort=false).

cd("/user") # going to the user start directory

readdir() # returns the names of all files in the current directory (currently "/user")
7-element Vector{String}:
 ".git"
 ".packages"
 ".project"
 "11.ngscript"
 "engee_commands.csv"
 "my_file.txt"
 "sample1.json"

readdir(join=true) # combining the returned name with the current directory
7-element Vector{String}:
 "/user/.git"
 "/user/.packages"
 "/user/.project"
 "/user/11.ngscript"
 "/user/engee_commands.csv"
 "/user/my_file.txt"
 "/user/sample1.json"

readdir("my_dir") # returns the names of all files in the my_dir directory
7-element Vector{String}:
 "RTFM-HISTORY.txt"
 "delay.html"
 "difference.pdf"
 "difference.xml"
 "littleendian.svg"
 "markdown_test.md"
 "mat.mat"

readdir("my_dir", join=true) # combining the returned name with the selected directory (my_dir)
7-element Vector{String}:
 "my_dir/RTFM-HISTORY.txt"
 "my_dir/delay.html"
 "my_dir/difference.pdf"
 "my_dir/difference.xml"
 "my_dir/littleendian.svg"
 "my_dir/markdown_test.md"
 "my_dir/mat.mat"

readeach — returns an iterable object, resulting in read(io, T).

Details

Function readeach It is used to iterate through the contents of a file or stream, performing the specified operation for each row or part of the data. It accepts a read stream as input and an argument that will be applied to each row or piece of data.

io = IOBuffer("Welcome to Engee.\n Text to be deleted by the function.\n") # an input/output buffer is created

for c in readeach(io, Char) # iterating over characters from the stream until it reaches \n, then completes the iteration.
             c == '\n' && break
             print(c)
         end

# conclusion
Welcome to Engee.

readline — Reads a single line of text from a given input/output stream or file.

Details

When reading from a file, it is assumed that UTF-8 encoding is used for the text. Strings at the input end with '\n' or "\r\n" or at the end of the input stream. An argument can also be used keep. If keep it matters false (by default), these trailing newlines are removed from the string before it is returned. If keep it matters true they are returned as part of a string.

write("my_file.txt", "Welcome to Engee.\Ntext to be deleted by the function.\n");

readline("my_file.txt")
"Welcome to Engee."

readline("my_file.txt", keep=true)
"Welcome to Engee.\n"

rm("my_file.txt") # deletes the file my_file.txt

print("Enter your name: ")

your_name = readline() # opens the user name input window.
# enter a name, for example Engee_User
"Engee_User"

readlines — Reads all lines in an input/output stream or file as vector or string values.

Details

The behavior is similar to repetitive saving of the read result readline with the same arguments and saving the resulting strings as vector or string values.

write("my_file.txt", "Welcome to Engee.\Ntext that will NOT be deleted by the function.\n");

readlines("my_file.txt")
# conclusion
2-element Vector{String}:
 "Welcome to Engee."
 "Text that will NOT be deleted by the function."

readlines("my_file.txt", keep=true)
2-element Vector{String}:
 "Welcome to Engee.\n"
 "Text that will NOT be deleted by the function.\n"

rm("my_file.txt") # deletes the file my_file.txt

readuntil — reads a line from an input/output stream or file (up to a specified delimiter character).

Details

The delimiter character can be a UInt8, AbstractChar, string, or vector. Named argument keep determines whether the delimiter symbol is included in the result. It is assumed that UTF-8 encoding is used for the text.

write("my_file.txt", "Welcome to Engee.\Ntext to be deleted by the function.\n")

readuntil("my_file.txt", 'L')

readuntil("my_file.txt", '.', keep = true)
  "Welcome to Engee."

rm("my_file.txt")

For more information about other file management features in Engee, see Software control of modelling.

  1. Data import

  2. Working with Julia packages

  3. File formats