# Introduction to Rparadox

## Introduction

The Rparadox package provides tools to read data from Paradox database files (`.db`) directly into R. This vignette will walk you through the basic and advanced usage of the package.

## Installation

    # stable version from CRAN
    install.packages("Rparadox")

You can install the development version from GitHub:

    # install.packages("devtools")
    devtools::install_github("celebithil/Rparadox")

## Basic Usage with `read_paradox()`

The simplest way to read a Paradox file is with the `read_paradox()` wrapper function. It handles the entire workflow of opening the file, reading the data, and closing the connection for you.

    # Get the path to an example database included with the package
    db_path <- system.file("extdata", "biolife.db", package = "Rparadox")

    # Read the data in a single step
    biolife_data <- read_paradox(db_path)

    # Display the first few rows of the resulting tibble
    head(biolife_data)
    #> # A tibble: 6 × 8
    #>   `Species No` Category Common_Name `Species Name` `Length (cm)` Length_In Notes
    #>          <dbl> <chr>    <chr>       <chr>                  <dbl>     <dbl> <chr>
    #> 1        90020 Trigger… Clown Trig… Ballistoides …            50      19.7 "Als…
    #> 2        90030 Snapper  Red Emperor Lutjanus sebae            60      23.6 "Cal…
    #> 3        90050 Wrasse   Giant Maor… Cheilinus und…           229      90.2 "Thi…
    #> 4        90070 Angelfi… Blue Angel… Pomacanthus n…            30      11.8 "Hab…
    #> 5        90080 Cod      Lunartail … Variola louti             80      31.5 "Als…
    #> 6        90090 Scorpio… Firefish    Pterois volit…            38      15.0 "Als…
    #> # ℹ 1 more variable: Graphic <blob>

## Handling Character Encodings

For legacy files with incorrect encoding information in the header, you can specify the correct encoding manually with the `encoding` argument.

    # Example for a file known to be in the CP866 encoding
    my_data <- read_paradox("path/to/your/file.db", encoding = "cp866")

This ensures that text is correctly converted to UTF-8.

## Advanced Usage: Metadata and Manual Control

If you need more control, for instance, to check a file’s metadata before committing to reading a large dataset, you can use the lower-level functions.

The workflow is: 1. `pxlib_open_file()` to get a file handle. 2. `pxlib_metadata()` to inspect metadata (optional). 3. `pxlib_get_data()` to read the data. 4. `pxlib_close_file()` to release the connection.

    # This chunk uses the db_path defined in the previous chunk
    # Open the file handle
    pxdoc <- pxlib_open_file(db_path)

    if (!is.null(pxdoc)) {
      # Get and print metadata
      metadata <- pxlib_metadata(pxdoc)
      print(metadata$fields)

      # Read the full dataset
      data_from_handle <- pxlib_get_data(pxdoc)

      # IMPORTANT: Always close the file handle
      pxlib_close_file(pxdoc)
    }
    #>           name type size
    #> 1   Species No    6    8
    #> 2     Category    1   15
    #> 3  Common_Name    1   30
    #> 4 Species Name    1   40
    #> 5  Length (cm)    6    8
    #> 6    Length_In    6    8
    #> 7        Notes   12   60
    #> 8      Graphic   16   10