TeeJee.FileSystem

1. Overview

The TeeJee.FileSystem module provides filesystem utility namespace for BastionGuard Backup. It provides common path, file, directory, compression, recursive deletion, listing, size-formatting, and shell-escaping helpers.

The implementation is written in Vala and uses GLib/GIO together with the application utility namespaces required by the file.

2. Dependencies and Integration

The module imports:

  • TeeJee.Logging
  • TeeJee.ProcessHelper
  • TeeJee.Misc

Key runtime integrations include:

  • Gee – typed lists, maps, queues, or collection operations
  • GIO/GLib streams – filesystem and process I/O

3. Declared Types

3.1 TeeJee.FileSystem

namespace TeeJee.FileSystem

This namespace groups stateless utility functions and shared constants.

4. State, Properties, Constants, and Signals

Public and protected state

  • public const int64 KB – Compile-time constant used by this module.
  • public const int64 MB – Compile-time constant used by this module.
  • public const int64 GB – Compile-time constant used by this module.
  • public const int64 TB – Compile-time constant used by this module.
  • public const int64 KiB – Compile-time constant used by this module.
  • public const int64 MiB – Compile-time constant used by this module.
  • public const int64 GiB – Compile-time constant used by this module.
  • public const int64 TiB – Compile-time constant used by this module.

5. Public API and Operational Methods

5.1 file_parent()

public string file_parent(string file_path)

Implements the file parent operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.2 file_basename()

public string file_basename(string file_path)

Implements the file basename operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.3 path_combine()

public string path_combine(string path1, string path2)

Implements the path combine operation for this module.

5.4 remove_trailing_slash()

public string remove_trailing_slash(string path)

Removes trailing slash and reports whether cleanup completed successfully.

5.5 file_exists()

public bool file_exists (string file_path)

Implements the file exists operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.6 file_delete()

public bool file_delete(string file_path)

Implements the file delete operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.7 file_line_count()

public int64? file_line_count (string file_path)

Implements the file line count operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.8 file_read()

public string? file_read (string file_path)

Implements the file read operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.9 file_read_array()

public string[]? file_read_array(string file_path, char delimiter = '\n')

Implements the file read array operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.10 file_write()

public bool file_write (string file_path, string contents)

Implements the file write operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.11 file_copy()

public bool file_copy (string src_file, string dest_file)

Implements the file copy operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.12 file_move()

public void file_move (string src_file, string dest_file)

Implements the file move operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.13 file_is_symlink()

public bool file_is_symlink(string file_path)

Implements the file is symlink operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.14 file_gzip()

public bool file_gzip (string src_file)

Implements the file gzip operation for this module.

  • Executes an external process or generated shell command and uses its return status as part of the result.
  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.15 file_resolve_executable_path()

public string file_resolve_executable_path(string file_path)

Implements the file resolve executable path operation for this module.

5.16 file_get_symlink_target()

public string file_get_symlink_target(string file_path)

Implements the file get symlink target operation for this module.

  • Catches runtime errors locally and reports them through the logging layer or return value.

5.17 dir_exists()

public bool dir_exists (string dir_path)

Implements the dir exists operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.18 dir_create()

public bool dir_create (string dir_path, bool show_message = false)

Implements the dir create operation for this module.

  • Catches runtime errors locally and reports them through the logging layer or return value.

5.19 dir_empty_delete()

public static bool dir_empty_delete(string path)

Implements the dir empty delete operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.20 dir_delete_recursive()

public static bool dir_delete_recursive(string dir)

Recursively enumerates and removes files, symbolic links, and child directories before deleting the requested directory.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.21 dir_delete()

public static bool dir_delete(string dir_path, bool show_message = false)

Implements the dir delete operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.22 dir_is_empty()

public bool dir_is_empty (string dir_path)

Implements the dir is empty operation for this module.

  • Catches runtime errors locally and reports them through the logging layer or return value.

5.23 dir_list_names()

public Gee.ArrayList<string> dir_list_names(string path)

Implements the dir list names operation for this module.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.24 format_file_size()

public string format_file_size ( uint64 size, bool binary_units = false, string unit = "", bool show_units = true, int decimals = 1)

Builds a human-readable representation from the current object state.

5.25 escape_single_quote()

public string escape_single_quote(string file_path)

Escapes the supplied text for safe use in the target representation.

6. External Commands and System Interfaces

The module constructs, checks, or parses commands containing:

%%'0.%df
gzip '%s'

Execution success is determined from command exit status and, where applicable, parsed standard output or standard error.

7. Operational Flow

  1. Transform raw values, command output, or metadata into structured or display-ready form.
  2. Finalize the operation and release files, mounts, child processes, widgets, or cached state.

8. Error Handling and Diagnostics

  • GLib and filesystem exceptions are caught locally in the operations that can fail.
  • The TeeJee logging layer records errors, debug state, generated commands, and operational messages.
  • Boolean, nullable, or empty-string return values communicate recoverable failures to callers.

9. Runtime and Security Considerations

  • External commands: command availability, quoting, locale, privileges, and output format can affect behavior.
  • Dynamic command construction: caller-controlled values must be validated and escaped before being inserted into shell commands.
  • Shared state: static caches and global switches are shared by all callers and are not automatically thread-isolated.

10. Licensing

The source is distributed under the GNU General Public License version 2 or any later version.

The source header identifies:

Copyright 2012-2018 Tony George &lt;teejeetech@gmail.com&gt;

Published on:
Last updated on: