Documention for: codecs.r
Created by: vincentecuye
 on: 2-Mar-2025
Format: text/editable
Downloaded on: 1-Apr-2025

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

=toc

===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):

\note
*image* : ~bmp~. ~png~, ~gif~, ~jpeg~ 
*audio* : ~wav~
*text* : ~base64~, ~markup (xml)~, ~percent-encoding~, ~text (rebol)~
/note

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

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

===Codec registration

:register-codec block! - regiser a new codec
:unregister-codec 'word - removes a codec from the internal list

===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

===Codec usage - data identification

:encoding?  - determines encoding of binary! data ('identify method)
:file-type? - determines file type from suffix (returns a word!)

===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

===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

\note
'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 them
from the import :

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

===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!] ...]

===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)
    ]