adfExplorer vs. adfExplorer2
Source:vignettes/adfExplorer_vs_adfExplorer2.Rmd
adfExplorer_vs_adfExplorer2.RmdMotivation for adfExplorer2
adfExplorer2 is the succesor of adfExplorer.
This vignette explains why a complete overhaul was created and released
separately with a different version. It will also provide some hands on
examples showing how to modify your R code when you are switching from
adfExplorer to adfExplorer2.
In the predecessor adfExplorer everything was coded in
R. Although, technically a lot could be achieved, it was
not very effective. In order to work with Amiga Disk Files, the entire
file first needed to be copied into memory, and than save the object in
memory back to disk after manipulation.
Consider the case where you want to extract a file from a virtual disk and store it on your local drive. The schematics below show the process in the old situation. The ADF file first needs to be copied to memory. The file data from that object needs to be extracted from that copy. After which the file data can be stored to disk:
After working on this approach for a while, I learned about the
existence of ADFlib. This
is when I decided to start from scratch and set up a more efficient
design resulting in adfExplorer2. There I took the
C code from ADFlib and build an interface to
R in C++. This strategy had several
advantages:
- The wheel doesn’t have to be reinvented, as
ADFlibalready implemented the core functionalities for interacting with Amiga Disk Files. - By coding in
CandC++:- Custom
Rconnections can be created. This allows you to modify the ADF files in place without having to copy them to memory first. - The program needs to be compiled
- Custom
Because the new strategy doesn’t need to move data back and forth to memory and uses compiled code, it is much faster (see also the benchmark test below).
Furthermore, you can create connections to files on the virtual device and directly read from or write to those files. There is no more need to create physical copies of the virtual file.
The process of extracting a file from an ADF device with
adfExplorer2 would look something like this:
Switching to adfExplorer2
When you have code using adfExplorer, I recommend
switching to adfExplorer2 at your earliest convenience.
Partly because of the reasons listed above, but also because
adfExplorer will receive minimal maintenance. As
adfExplorer2 uses a different syntax, I have put some
examples side by side, to help you translate your code.
Let’s start by opening a Amiga Disk File:
adz_file <- system.file("example.adz", package = "adfExplorer2")
# ---------------- adfExplorer
library(adfExplorer)
my_disk1 <- read.adz(adz_file)
# ---------------- adfExplorer2
library(adfExplorer2)
my_disk2 <- connect_adf(adz_file)Show and change the current dir:
# ---------------- adfExplorer
current.adf.dir(my_disk1)
#> [1] "adfExampleOFS:"
current.adf.dir(my_disk1) <- "s"
# ---------------- adfExplorer2
adf_directory(my_disk2)
#> ROOT adfExampleOFS
adf_directory(my_disk2) <- "s"List entries in a directory. Note that adfExplorer2 has
the capability to list the entries recursively (in all nested
subdirectories):
# ---------------- adfExplorer
list.adf.files(my_disk1, "DF0:")
#> [1] "Devs" "S" "this" "mods"
# ---------------- adfExplorer2
list_adf_entries(my_disk2, "DF0:", recursive = TRUE)
#> DIR DEWR... Devs
#> FILE DEWR...iguration
#> DIR DEWR... S
#> FILE DEWR...-Sequence
#> DIR DEWR... this
#> DIR DEWR... is
#> DIR DEWR... a
#> DIR DEWR... deep
#> DIR DEWR... path
#> DIR DEWR... mods
#> FILE DEWR...mod.introRead from a file on the virtual disk:
# ---------------- adfExplorer
get.adf.file(my_disk1, "startup-sequence") |>
rawToChar()
#> [1] "; The Startup-Sequence is executed after booting\n; Everything after semicolons are comments and is ignored\n; By default standard commands are loaded from\n; the ROM kickstart. Additional commands should be\n; stored on the disk in the SYS:C directory.\n; For demonstration purposes we only echo some\n; text to the screen... Note that this will not\n; work on Amiga OS <2.0 as \"Echo\" is not available\n; in older ROM kickstart versions.\n\nEcho \"\033c\033[22m\033[32mADF Explorer Example Disk\" ; Note that the weird characters at the start are escape-codes to format the text\nEcho \"\033[0mThis disk was created as an example for the\"\nEcho \"R package 'adfExplorer' by Pepijn de Vries.\""
# ---------------- adfExplorer2
con <- adf_file_con(my_disk2, "startup-sequence")
readLines(con, warn = FALSE)
#> [1] "; The Startup-Sequence is executed after booting"
#> [2] "; Everything after semicolons are comments and is ignored"
#> [3] "; By default standard commands are loaded from"
#> [4] "; the ROM kickstart. Additional commands should be"
#> [5] "; stored on the disk in the SYS:C directory."
#> [6] "; For demonstration purposes we only echo some"
#> [7] "; text to the screen... Note that this will not"
#> [8] "; work on Amiga OS <2.0 as \"Echo\" is not available"
#> [9] "; in older ROM kickstart versions."
#> [10] ""
#> [11] "Echo \"\033c\033[22m\033[32mADF Explorer Example Disk\" ; Note that the weird characters at the start are escape-codes to format the text"
#> [12] "Echo \"\033[0mThis disk was created as an example for the\""
#> [13] "Echo \"R package 'adfExplorer' by Pepijn de Vries.\""
close(con)Clean up after yourself:
Benchmarking adfExplorer and adfExplorer2
A set of tasks were defined to evaluate computational time: open an
ADF file; show the current dir; set the current directory to a specific
path; read a small text file from the virtual device; list all dir and
file entries on the disk’s root. The plot below shows the time it took
to complete these tasks with both packages. adfExplorer2 is
nearly 5 times faster than its predecessor.
