Xbase.MemoHandler (Xbase v0.1.0)

View Source

Handles coordinated operations between DBF and DBT files for memo field support.

Provides high-level API for seamless memo content handling in record operations, automatic file discovery, and transaction safety across both file types.

Summary

Types

t()

Functions

append_record_with_memo(handler, record_data)

Appends a record with automatic memo content handling.

close_memo_files(handler)

Closes both DBF and DBT files properly.

create_dbf_with_memo(dbf_path, fields, opts \\ [])

Creates a new DBF file with memo support and coordinated DBT file.

memo_transaction(handler, transaction_fn)

Executes a function with transaction safety across both DBF and DBT files.

open_dbf_with_memo(dbf_path, modes \\ [:read], opts \\ [])

Opens a DBF file with automatic memo file discovery and coordination.

read_record_with_memo(handler, record_index)

Reads a record with automatic memo content resolution.

update_record_with_memo(handler, record_index, record_data)

Updates a record with automatic memo content handling.

Types

t()

@type t() :: %Xbase.MemoHandler{
  dbf: map(),
  dbf_path: String.t(),
  dbt: Xbase.Types.DbtFile.t() | nil,
  dbt_path: String.t() | nil,
  memo_mode: :auto | :required | :disabled
}

Functions

append_record_with_memo(handler, record_data)

Appends a record with automatic memo content handling.

Parameters

  • handler - MemoHandler structure
  • record_data - Map of field names to values, where memo fields contain content strings

Returns

  • {:ok, updated_handler} - Successfully appended record with memo content
  • {:error, reason} - Error appending record

Example

record_data = %{
  "NAME" => "John Doe",
  "NOTES" => "This memo content will be automatically stored in the DBT file"
}
{:ok, updated_handler} = MemoHandler.append_record_with_memo(handler, record_data)

close_memo_files(handler)

Closes both DBF and DBT files properly.

Parameters

  • handler - MemoHandler structure

Returns

  • :ok - Files closed successfully

create_dbf_with_memo(dbf_path, fields, opts \\ [])

Creates a new DBF file with memo support and coordinated DBT file.

Parameters

  • dbf_path - Path for the new DBF file
  • fields - Field definitions for the DBF file
  • opts - Options for file creation
    • :version - DBF version (automatically set to memo-capable if memo fields present)
    • :dbt_path - Explicit DBT file path (defaults to replacing .dbf with .dbt)
    • :block_size - DBT block size (default: 512)

Returns

  • {:ok, MemoHandler.t()} - Successfully created coordinated files
  • {:error, reason} - Error creating files

memo_transaction(handler, transaction_fn)

Executes a function with transaction safety across both DBF and DBT files.

Parameters

  • handler - MemoHandler structure
  • transaction_fn - Function to execute with the handler

Returns

  • {:ok, {result, updated_handler}} - Transaction successful
  • {:error, reason} - Transaction failed, changes rolled back

open_dbf_with_memo(dbf_path, modes \\ [:read], opts \\ [])

Opens a DBF file with automatic memo file discovery and coordination.

Parameters

  • dbf_path - Path to the DBF file
  • modes - File access modes (default: [:read])
  • opts - Options for memo handling
    • :memo - Memo mode (:auto, :required, :disabled)
    • :dbt_path - Explicit DBT file path (overrides auto-discovery)

Returns

  • {:ok, MemoHandler.t()} - Successfully opened coordinated files
  • {:error, reason} - Error opening files

Examples

# Automatic memo file discovery
{:ok, handler} = MemoHandler.open_dbf_with_memo("data.dbf")

# Read-write mode with required memo support
{:ok, handler} = MemoHandler.open_dbf_with_memo("data.dbf", [:read, :write], memo: :required)

# Explicit DBT file path
{:ok, handler} = MemoHandler.open_dbf_with_memo("data.dbf", [], dbt_path: "memos.dbt")

read_record_with_memo(handler, record_index)

Reads a record with automatic memo content resolution.

Parameters

  • handler - MemoHandler structure
  • record_index - Zero-based record index to read

Returns

  • {:ok, record_data} - Record data with memo content resolved
  • {:error, reason} - Error reading record

update_record_with_memo(handler, record_index, record_data)

Updates a record with automatic memo content handling.

Parameters

  • handler - MemoHandler structure
  • record_index - Zero-based record index to update
  • record_data - Map of field names to values for update

Returns

  • {:ok, updated_handler} - Successfully updated record with memo content
  • {:error, reason} - Error updating record