Script Library: 1247 scripts
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 
View scriptLicenseDownload documentation as: HTML or editable
Download scriptHistoryOther scripts by: vincentecuye

Documentation for: codecs.r


REBOL2 Codec System

Author: Annick ECUYER
Version: 1.0.0 (2-Mar-2025)

Contents

1. Purpose

This script implements a coder/encoder system for REBOL2, like in R3/Red, modules that converts to/from (mostly) binary formats.

It's a component (system/components), and cam be used with the 'Needs header field : Needs: [codecs 1.0.0]

The predefined codecs are (options in parenthesis):

image : bmp. png, gif, jpeg

audio : wav

text : base64, markup (xml), percent-encoding, text (rebol)

Theses are linked to internal Rebol function but can be replaced.

2. Loading / Execution

    >> do %codecs.r

It's only updated if it isn't loaded / the existing version is older.To force a refresh/reload :

    >> do/args %codecs.r 'force

By default, all words in header/exports are bound to the global context.It can be prevented at script execution:

    ; only exports 'encode and 'decode functions
    >> do/args %codecs.r [with [encode decode]]

The rest is still available in 'ctx-codecs .

3. Codec registration

register-codec block!

regiser a new codec

unregister-codec 'word

removes a codec from the internal list

4. Codecs information

list-codecs

list registered codecs

list-codecs 'all

list registered codecs

list-codecs 'codec | 'type | 'method

list related codecs

codec-info 'codec

print info about a codec and returns its definition

codec-info/query 'codec

returns a codec definition

5. Codec usage - data identification

encoding?

determines encoding of binary! data ('identify method)

file-type?

determines file type from suffix (returns a word!)

6. Codec usage - decoding

decode 'codec date

returns the decoded data ('decode method)

load/as data 'codec

loads and decodes the data ('decode method)

decode/as 'codec date option

returns the decoded data with codec options

load/as data [codec option]

loads and decodes the data with codec options

7. Codec usage - encoding

encode 'codec data

returns the encoded data ('encode method)

save/as data 'codec

encodes and saves the data ('encode method)

encode/as 'codec data option

returns the encoded data with codec options

save/as data 'codec

encodes and saves the data with codec options

'load and 'save both auto-detect file-type from filename by default (only when no refinements are provided)

'load and 'save are overloaded by the system. It can be prevented by excluding themfrom the import :

    do/args %codecs.r [with [register-codec unregister-codec list-codecs encoding? file-type? encode decode codec-info]]

8. Module context

'ctx-codecs

contains both the related methods and codecs list (ctx-codecs/codecs)

'ctx-codecs/codecs

a block! of values in the format : [codec-name [word!] codec-definition [object!] ...]

9. Codec structure

    codec!: make object! [
        name: none     ; mandatory, used to identify the codec
        type: none     ; category for classification (optional)
        title: none    ; text description (optional)
        version: none  ; codec version (optional)
        suffixes: none ; block! of suffixes in the form [%.txt %.bin] (optional)

        encoding: any-function! ; encoding method (optional)
        decoding: any-function! ; decoding method (optional)
        identify: any-function! ; identify method (optional)
    ]