Engee documentation

A class for working with the file system and extensions (UTILS_API)

Page in progress.

UTILS_API is a set of auxiliary methods for working with files and directories on the user’s computer and is not intended for Engee directories.

Using UTILS_API you can:

  • Upload files to your computer;

  • Download files from a computer;

  • Create and delete directories in the file system using the specified paths.

In addition, UTILS_API allows you to connect external user modules to the Engee hardware support package. Access to the module opens immediately after install the support package.

function createFile(utils::Any, filename::String, filepath::String, contents::Union{Vector{UInt8}, String, Nothing}=nothing, mode::String="wb", buffering::Int64=-1, encoding::Union{String, Nothing}=nothing, errors::Union{String, Nothing}=nothing, newline::Union{String, Nothing}=nothing, closefd::Bool=true)::Nothing

The function is designed to create a file named filename on the user’s client program in the specified directory filepath.

Arguments

  • utils: object type UTILS.Utils.

  • engee_filepath: the path to the file in the directory of the file browser Engee.

  • host_dirpath: the path to the directory on the user’s client program to which the specified file from Engee will be uploaded.

  • mode: file opening mode. Possible values:

  • "r": reading;

  • "w": recording (overwriting);

  • "a": additional recording;

  • "wb": binary notation;

  • "rb": binary reading.

  • buffering: parameters of the system buffer for working with files. Possible values:

  • -1: default system buffer;

  • 0: disable buffering;

  • 1: line-by-line buffering (in text mode only);

  • >1: buffer size in bytes.

  • encoding: encoding of the file. Possible values: "utf-8", "cp1251", "ascii", "latin-1", nothing — default system setting.

  • errors: error handling strategy:

  • "strict": error with non-encoded characters;

  • "ignore": ignore non-encoded characters;

  • "replace": replace with � (replacement marker);

  • "backslashreplace": replace with escape sequences.

  • newline: line feed control:

  • nothing or "" — universal mode;

  • "\n", "\r", "\r\n" — a specific line feed option. The line feed character differs from system to system:

  • Unix/Linux: \n;

    • Windows: \r\n;

    • Old MacOS: \r.

  • closefd: closes the file descriptor automatically (true — close it, false — leave it open).

  • filename: name of the file being created;

  • filepath: path to the directory to create the file;

  • contents: file contents (string, bytes, or nothing).

function createFolder(utils::Any, folder_path::String, folder_name::String, mode::Int64=511, dir_fd::Union{Int64, Nothing}=nothing)::Nothing

The function is designed to create a directory named folder_name on the user’s client program in the specified directory folder_path.

Arguments

  • utils: object type UTILS.Utils.

  • folder_path: the path to the directory on the user’s client program where the new folder will be created.

  • folder_name: the name of the directory being created.

  • mode: access mode for the directory. Example of access rights:

    Rights Octal Decimal Description

    rwxrwxrwx

    0o777

    511

    Full access for all

    rwxr-xr-x

    0o755

    493

    Standard rights for directories

    rwxr-x---

    0o750

    488

    Owner: full access, Group: read+execute

    rwx------

    0o700

    448

    Owner only

    rw-rw-rw-

    0o666

    438

    Read+Write for all

    rw-r—​r--

    0o644

    420

    Standard file permissions

    rw-r-----

    0o640

    416

    Owner: read+write, Group: read

    rw-------

    0o600

    384

    Owner only (Read+write)

  • dir_fd: file descriptor. nothing — the usual path, the number is the relative path through the descriptor.

function deleteExtension(utils::Any, path_to_extension::String)::Nothing

The function is designed to remove the specified user extension path from auto-upload to the Engee hardware support package.

Arguments

  • utils: object type UTILS.Utils.

  • path_to_extension: the path to the extension being deleted.

function deleteFile(utils::Any, filename::String, filepath::String, ignore_if_missing::Bool=false, verbose::Bool=false)::Nothing

The function is designed to delete a file named filename on the user’s client program in the specified directory filepath.

Arguments

  • utils: object type UTILS.Utils.

  • filename: the name of the file to delete.

  • filepath: the path to the directory where the file is being deleted.

  • ignore_if_missing: false — error if the file is not found; true — ignore the missing file.

  • verbose: output operation details (true) or not (false).

function deleteFolder(utils::Any, folder_path::String, folder_name::String, even_if_not_empty::Bool=false, dir_fd::Union{Int64, Nothing}=nothing)

The function is designed to delete a directory named folder_name on the user’s client program in the specified directory folder_path.

Arguments

  • utils: object type UTILS.Utils.

  • folder_path: the path to the directory on the user’s client program.

  • folder_name: the name of the directory to delete.

  • even_if_not_empty: delete even if the directory is not empty (true — Yes, false: only empty ones).

  • dir_fd: file descriptor: nothing — the usual path, the number is to use a relative path.

function downloadFile(utils::Any, engee_dirpath::String, host_filepath::String, mode::String="rb", buffering::Int64=-1, encoding::Union{String, Nothing}=nothing, errors::Union{String, Nothing}=nothing, newline::Union{String, Nothing}=nothing, closefd::Bool=true)::Nothing

The function is designed to download the specified file from the user’s client program to the specified directory of the Engee file browser.

Arguments

  • utils: object type UTILS.Utils.

  • engee_filepath: the path to the file in the directory of the file browser Engee.

  • host_dirpath: the path to the directory on the user’s client program to which the specified file from Engee will be uploaded.

  • mode: file opening mode. Possible values:

  • "r": reading;

  • "w": recording (overwriting);

  • "a": additional recording;

  • "wb": binary notation;

  • "rb": binary reading.

  • buffering: parameters of the system buffer for working with files. Possible values:

  • -1: default system buffer;

  • 0: disable buffering;

  • 1: line-by-line buffering (in text mode only);

  • >1: buffer size in bytes.

  • encoding: encoding of the file. Possible values: "utf-8", "cp1251", "ascii", "latin-1", nothing — default system setting.

  • errors: error handling strategy:

  • "strict": error with non-encoded characters;

  • "ignore": ignore non-encoded characters;

  • "replace": replace with � (replacement marker);

  • "backslashreplace": replace with escape sequences.

  • newline: line feed control:

  • nothing or "" — universal mode;

  • "\n", "\r", "\r\n" — a specific line feed option. The line feed character differs from system to system:

  • Unix/Linux: \n;

    • Windows: \r\n;

    • Old MacOS: \r.

  • closefd: closes the file descriptor automatically (true — close it, false — leave it open).

function loadExtension(utils::Any, path_to_extension::String)::Nothing

The function is designed to download custom extensions to the Engee hardware support package.

Arguments

  • utils: object type UTILS.Utils.

  • path_to_extension: the path to the downloaded extension.

function uploadFile(utils::Any, engee_filepath::String, host_dirpath::String, mode::String="wb", buffering::Int64=-1, encoding::Union{String, Nothing}=nothing, errors::Union{String, Nothing}=nothing, newline::Union{String, Nothing}=nothing, closefd::Bool=true)::Nothing

The function is designed to download the specified file from the Engee file browser to the user’s client program in the specified directory.

Arguments

  • utils: object type UTILS.Utils.

  • engee_filepath: the path to the file in the directory of the file browser Engee.

  • host_dirpath: the path to the directory on the user’s client program to which the specified file from Engee will be uploaded.

  • mode: file opening mode. Possible values:

  • "r": reading;

  • "w": recording (overwriting);

  • "a": additional recording;

  • "wb": binary notation;

  • "rb": binary reading.

  • buffering: parameters of the system buffer for working with files. Possible values:

  • -1: default system buffer;

  • 0: disable buffering;

  • 1: line-by-line buffering (in text mode only);

  • >1: buffer size in bytes.

  • encoding: encoding of the file. Possible values: "utf-8", "cp1251", "ascii", "latin-1", nothing — default system setting.

  • errors: error handling strategy:

  • "strict": error with non-encoded characters;

  • "ignore": ignore non-encoded characters;

  • "replace": replace with � (replacement marker);

  • "backslashreplace": replace with escape sequences.

  • newline: line feed control:

  • nothing or "" — universal mode;

  • "\n", "\r", "\r\n" — a specific line feed option. The line feed character differs from system to system:

  • Unix/Linux: \n;

    • Windows: \r\n;

    • Old MacOS: \r.

  • closefd: closes the file descriptor automatically (true — close it, false — leave it open).