▼ |  | File: Racket File and Format Libraries

1 | Convertible: Data-Conversion Protocol
2 | gzip Compression and File Creation
3 | gzip Decompression
4 | zip File Creation
5 | zip File Extraction
6 | tar File Creation
7 | tar File Extraction
8 | tar+gzip File Extraction
9 | MD5 Message Digest
10 | SHA1 Message Digest
11 | GIF File Writing
12 | ICO File Reading and Writing
13 | Windows Registry
14 | Caching
15 | Globbing
| Bibliography
| Index

On this page:

prop: convertible
convertible?
convert

top ← prev up next →

### 1`` Convertible: Data-Conversion Protocol

(require file/convertible) | package: base

The file/convertible library provides a protocol to mediate between providers of data in different possible formats and consumers of the formats. For example, a datatype that implements prop:convertible might be able to convert itself to a GIF or PDF stream, in which case it would produce data for 'gif-bytes or 'pdf-bytes requests.

Any symbol can be used for a conversion request, but the following should be considered standard:

- 'text — a string for human-readable text

- 'gif-bytes — a byte string containing a GIF image encoding

- 'png-bytes — a byte string containing a PNG image encoding

- 'png-bytes+bounds — a list containing a byte string and four numbers; the byte string contains a PNG document, and the four numbers are sizing information for the image: the width, height, descent (included in the height), and extra vertical top space (included in the height), in that order

- 'png-bytes+bounds8 — a list containing a byte string and eight numbers; like 'png-bytes+bounds, but where the image encoded that is in the byte string can be padded in each direction (to allow the drawn region to extend beyond its “bounding box”), where the extra four numbers in the list specify the amount of padding that was added to the image: left, right, top, and bottom

- 'png@2x-bytes — like 'png-bytes, but for an image that is intended for drawing at 1/2 scale

- 'png@2x-bytes+bounds — like 'png-bytes+bounds, but for an image that is intended for drawing at 1/2 scale, where the numbers in the result list are already scaled (e.g, the byte string encodes an image that is twice as wide as the first number in the resulting list)

- 'png@2x-bytes+bounds8 — like 'png-bytes+bounds8, but but for an image that is intended for drawing at 1/2 scale, and where the numbers in the result list are already scaled

- 'svg-bytes — a byte string containing a SVG image encoding

- 'svg-bytes+bounds — like 'png-bytes+bounds, but for an SVG image

- 'svg-bytes+bounds8 — like 'png-bytes+bounds8, but for an SVG image

- 'ps-bytes — a byte string containing a PostScript document

- 'eps-bytes — a byte string containing an Encapsulated PostScript document

- 'eps-bytes+bounds — like 'png-bytes+bounds, but, but for an Encapsulated PostScript document

- 'eps-bytes+bounds8 — like 'png-bytes+bounds8, but, but for an Encapsulated PostScript document

- 'pdf-bytes — a byte string containing a PDF document

- 'pdf-bytes+bounds — like 'png-bytes+bounds, but, but for an PDF document

- 'pdf-bytes+bounds8 — like 'png-bytes+bounds8, but, but for an PDF document

> value prop:convertible
> : |
> (struct-type-property/c
> (->i ([v convertible?] [request symbol?] [default default/c])
> [result
> (case request
> [(text)
> (or/c string? default/c)]
> [(gif-bytes
> png-bytes
> png@2x-bytes
> ps-bytes
> eps-bytes
> pdf-bytes
> svg-bytes)
> (or/c bytes? default/c)]
> [(png-bytes+bounds
> png@2x-bytes+bounds
> eps-bytes+bounds
> pdf-bytes+bounds)
> (or/c (list/c bytes?
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?)))
> default/c)]
> [(png-bytes+bounds8
> png@2x-bytes+bounds8
> eps-bytes+bounds8
> pdf-bytes+bounds8)
> (or/c (list/c bytes?
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?)))
> default/c)]
> [else (or/c opaque-default/c any/c)])]))

A property whose value is invoked by convert.

The v argument to the procedure is the structure, the request argument is a symbol for the requested conversion, and the default argument is a value to return (typically #f if the conversion is not supported). The procedure’s result depends on the requested conversion, as above.

The default/c contract is one generated by new-α/c.

> procedure (convertible? v) → boolean?
> v : any/c

Returns #t if v supports the conversion protocol, #f otherwise.

> procedure (convert v request [default])
> | → |  |
> (case request
> [(text)
> (or/c string? default/c)]
> [(gif-bytes
> png-bytes
> png@2x-bytes
> ps-bytes
> eps-bytes
> pdf-bytes
> svg-bytes)
> (or/c bytes? default/c)]
> [(png-bytes+bounds
> png@2x-bytes+bounds
> eps-bytes+bounds
> pdf-bytes+bounds)
> (or/c (list/c bytes?
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?)))
> default/c)]
> [(png-bytes+bounds8
> png@2x-bytes+bounds8
> eps-bytes+bounds8
> pdf-bytes+bounds8)
> (or/c (list/c bytes?
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?)))
> default/c)]
> [else (or/c opaque-default/c any/c)])
> v : convertible?
> request : symbol?
> default : any/c = #f

Requests a data conversion from v, where request indicates the type of requested data and default is the value that the converter should return if it cannot produce data in the format indicated by request.

The default/c contract is one created by new-α/c and it guarantees that the result of convert is the given default argument (or #f if one is not supplied).

top ← prev up next →