Package 'Adfexplorer'
Total Page:16
File Type:pdf, Size:1020Kb
Package ‘adfExplorer’ November 3, 2017 Type Package Title Import from and Export to Amiga Disk Files Version 0.1.2 Date 2017-11-03 Author Pepijn de Vries [aut, cre, dtc] Maintainer Pepijn de Vries <[email protected]> Description Amiga Disk Files (ADF) are virtual representations of 3.5 inch floppy disks for the Commodore Amiga. Most disk drives from other systems (including modern drives) are not able to read these disks. To be able to emulate this system, the ADF format was created. This package enables you to read ADF files and import and export files from and to such virtual DOS-formatted disks. Depends R (>= 2.10) Imports methods License GPL-3 LazyData True RoxygenNote 6.0.1 Suggests knitr, rmarkdown, ProTrackR VignetteBuilder knitr NeedsCompilation no Repository CRAN Date/Publication 2017-11-03 12:20:39 UTC R topics documented: adf.disk.name . .2 adf.example . .3 adf.file.exists . .4 1 2 adf.disk.name amigaBlock-class . .5 amigaBlock-method . .5 amigaDateToRaw . .7 amigaDisk-class . .8 amigaIntToRaw . .9 blank.amigaDOSDisk . 10 boot.block.code . 12 current.adf.dir . 13 displayRawData . 14 get.adf.file . 15 get.blockID . 17 get.diskLocation . 18 is.amigaDOS . 19 is.bootable . 20 list.adf.files . 21 print . 22 rawToAmigaDate . 23 rawToAmigaInt . 24 read.adf . 25 write.adf . 27 Index 29 adf.disk.name Get or set the disk name of an amigaDisk object Description Get or set the disk name of an amigaDisk object. Usage ## S4 method for signature 'amigaDisk' adf.disk.name(x) ## S4 replacement method for signature 'amigaDisk,character' adf.disk.name(x) <- value Arguments x An amigaDisk object for which the disk name needs to be obtained or changed. value A character representation with which the disk’s name needs to be replaced. Disk name needs to be between 1 and 30 characters long and are not allowed to contain a colon or forward slash. Details DOS-formatted disks (is.amigaDOS) store their disk name on the socalled root block of the disk. This method allows you to obtain the disk’s name or change it (when it is DOS-formatted). adf.example 3 Value Returns A character representation of the disk’s name. Author(s) Pepijn de Vries Examples ## Not run: data(adf.example) ## get the disk name: adf.disk.name(adf.example) ## change it if you don't like it: adf.disk.name(adf.example) <- "MyDisk" ## confirm that it has changed: adf.disk.name(adf.example) ## End(Not run) adf.example An example of an amigaDisk object Description An example of an amigaDisk-class object. Format An S4 amigaDisk-class object. Details An amigaDisk-class object that represents an ’Old File System’ formatted and bootable disk. It is used in multiple examples of this package. It contains a directory structure and some files that can be accessed using this package. The content of this example might change in future versions. Examples data("adf.example") 4 adf.file.exists adf.file.exists Test file or directory existsence in an amigaDisk object Description Tests whether a specific file (or directory) exists in an amigaDisk object. Usage ## S4 method for signature 'amigaDisk,character' adf.file.exists(x, file) Arguments x An amigaDisk object in which this method will check for the file’s existence. file A character string representing a file or directory name. Use Amiga specifica- tions for file name (see current.adf.dir). Details This method will look for a file/directory header, based on its name. If such a header exists, it is assumed that the file exists. The file/directory itself is not checked for validity. Value Returns a logical value indicating whether the file exists or not. Author(s) Pepijn de Vries Examples data(adf.example) ## This file exists: adf.file.exists(adf.example, "df0:mods/mod.intro") ## This file doesn't: adf.file.exists(adf.example, "df0:idontexist") amigaBlock-class 5 amigaBlock-class The amigaBlock class Description The Commodore Amiga stores data on floppy disks as 512 byte blocks. This class reflects such a block. Details There are several types of blocks. Most important are the boot block (used for booting the Amiga system), the root block (containing information on the disk and the root directory), header blocks (indicating where to find file data) and data blocks (containing the actual file data). See this pack- age’s vignette for more details. use the amigaBlock-method to extract a specific block from an amigaDisk object. Slots data The raw data of a ’block’ of data on an Amiga disk file. Each block holds 512 bytes of information. This slot is therefore a vector of the same length. Author(s) Pepijn de Vries Examples ## create a block with no data: new("amigaBlock") amigaBlock-method Extract block from or replace a block on an amigaDisk object Description Extract an amigaBlock from an amigaDisk object, or replace it on the disk. Usage ## S4 method for signature 'amigaDisk,numeric' amigaBlock(x, block) ## S4 replacement method for signature 'amigaDisk,numeric,amigaBlock' amigaBlock(x, block) <- value 6 amigaBlock-method Arguments x An amigaDisk object from which the block needs to be extracted or on which the block needs to be replaced. block A numeric identifier (whole numbers ranging from 0 up to 1759 (DD disk) or 3519 (HD disk)). value An amigaBlock object with which the block at the specified location on the disk needs to be replaced. Details Information is stored in 512 byte blocks on floppy disks. This method extracts a specific block at a numeric identifier (whole numbers ranging from 0 up to 1759 (DD disk) or 3519 (HD disk)) from an amigaDisk object. Value The amigaBlock object at the specified location is returned. In case of the replace method, an amigaDisk object with a replaced amigaBlock is returned. Author(s) Pepijn de Vries See Also Other block.operations: get.blockID, get.diskLocation Examples ## get the root block from the example adf: amigaBlock(adf.example, 880) ## Create a completely blank disk without file system: blank.disk <- new("amigaDisk") ## Replace the boot block on the blank disk with ## that from the example object: amigaBlock(blank.disk, 0) <- amigaBlock(adf.example, 0) ## The blank disk now has a boot block, ## but still no file system... amigaDateToRaw 7 amigaDateToRaw Convert date time objects into raw values Description This function converts date-time objects into raw data conform Amiga file system specifications. Usage amigaDateToRaw(x, format = c("long", "short"), tz = "UTC") Arguments x A(vector of) POSIXt object(s). format a character string indicating whether the date should be stored as short or long integers. tz A character string specifying the time zone to be used to convert the date time object. Note that the time zone is not stored on the Amiga. By default the Universal time zone (UTC) is assumed. You will get a warning when you use a timezone other then UTC. Details The Amiga file system stores date time objects as three unsigned short (16 bit) or long (32 bit) integers. Where the values are number of days, minutes and ticks (fiftieth of a second) since 1978- 01-01 respectively. As these values are always positive, only date time values on or after 1978-01-01 are allowed. The inverse of this function can be achieved with rawToAmigaDate. Value returns raw data reflecting the date-time objects conform the Amiga file system specifications. Author(s) Pepijn de Vries See Also Other raw.operations: amigaIntToRaw, displayRawData, rawToAmigaDate, rawToAmigaInt Examples ## Note that using the same date-time with different timezones will ## result in different raw data. The time zone is not stored. amigaDateToRaw(as.POSIXct("1978-01-01 13:30", tz = "UTC")) amigaDateToRaw(as.POSIXct("1978-01-01 13:30", tz = "CET")) 8 amigaDisk-class amigaDisk-class The amigaDisk class Description An S4 class representing the information from an Amiga Disk File. Details An Amiga Disk File (ADF) holds the raw data of an amiga disk in the same order as blocks (amigaBlock-class) on the physical disks. As an Amiga Disk can hold any kind of information, so can this class. An ADF file does not hold any other information. The size of the file will dictate whether it repre- sents a double density floppy disk (880 kB) or a high density floppy disk (1760 kB). The disk type is also stored in this class. Finally, the current directory is stored with this class. Which is only useful for DOS-formatted disks (with a file structure). By default this is set to the disk’s root. For more (technical) backgrounds please check this package’s vignette. Use the objects constructor (new("amigaDisk")) to create a completely blank disk (without a filesystem). If you want to be able to transfer files from and to the virtual disk, use blank.amigaDOSDisk instead. Slots data The raw data of the virtual disk. It should be a vector of length 901,120 in case of a double density disk and 1,802,240 in case of a high density disk. type A character indicating whether the virtual disk represents a "DD" (double density, most common) or "HD" (high density) disk. current.dir An integer, pointing at the block address of the current directory of this virtual disk. Use current.adf.dir to get or set the current directory. Author(s) Pepijn de Vries Examples ## This creates a blank non-bootable, non-DOS disk: new("amigaDisk") amigaIntToRaw 9 amigaIntToRaw Convert Amiga integers into raw values Description Convert 8, 16, or 32-bit signed or unsigned integer values into raw data, conform Amiga specifica- tions. Usage amigaIntToRaw(x, bits = 8, signed = F) Arguments x A vector of class numeric which needs to be converted into raw values.