On this page:
prop:  convertible
convertible?
convert

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 convertible 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:

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).