@spec close(DBF.Database.t()) :: close_result()

Closes the DBF and memo resources owned by an open database.

Closing the same database more than once is safe. After closing, the database must not be used for random access or resumed enumeration.

{:ok, db} = DBF.open("customers.dbf")
:ok = DBF.close(db)
:ok = DBF.close(db)

@spec get(DBF.Database.t(), term()) :: record_result()

Gets a record by its zero-based physical index.

Active and deleted records retain their status. Invalid indexes return an :invalid_record_index database error.

DBF.with_open("customers.dbf", fn db ->
  case DBF.get(db, 2) do
    {:record, row} -> {:ok, row}
    {:deleted_record, row} -> {:deleted, row}
    {:error, error} -> {:error, error}
  end
end)

@spec open(String.t(), options()) :: open_result()

Opens a DBF file and returns an opaque database value.

The caller owns the returned resource and must eventually call close/1. Prefer with_open/2,3 when callback-scoped access is sufficient.

Options are described in the module documentation.

Example

case DBF.open("customers.dbf", numeric: :exact) do
  {:ok, db} ->
    try do
      DBF.get(db, 0)
    after
      DBF.close(db)
    end

  {:error, error} ->
    {:error, Exception.message(error)}
end

@spec open!(String.t(), options()) :: DBF.Database.t()

Opens a DBF file, raising DBF.DatabaseError on failure.

Like open/2, the caller owns the returned resource and must call close/1. This is useful when failure should abort the current operation:

db = DBF.open!("customers.dbf")

try do
  Enum.take(db, 10)
after
  DBF.close(db)
end

@spec with_open(String.t(), (DBF.Database.t() -> result)) :: with_open_result(result)
when result: term()

Opens a database for the duration of a callback and always attempts to close it.

This is the preferred lifecycle for complete reads. The callback result is returned unchanged. If opening or closing fails, an error tuple is returned. If the callback raises, throws, or exits, DBFex closes the resources before propagating the original failure.

The callback receives an enumerable DBF.Database and must not close it.

Examples

Read every physical record:

DBF.with_open("customers.dbf", fn db ->
  Enum.to_list(db)
end)

Pass decoding options and keep only active rows:

DBF.with_open("customers.dbf", [numeric: :exact], fn db ->
  Enum.flat_map(db, fn
    {:record, row} -> [row]
    {:deleted_record, _row} -> []
    {:error, error} -> raise error
  end)
end)