[Top] [Contents] [Index] [ ? ]

binary-struct リファレンスマニュアル

このドキュメントはバイナリ構造を読み書きするためのユーティティbinary-structのリファレンスマニュアルです。 バージョン0.1に対応します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. binary-struct

Module: binary.struct

バイナリ構造を読み書きするためのモジュールです。 このモジュールがエクスポートしている全てのシンボルはプレフィックス`bs'を持ちます。

このドキュメントでは、バイナリ構造を表す<bs:type>のインスタンスの事を「タイプ」と呼びます。

このモジュールを利用してバイナリデータの読み書きをする典型的なプログラムは次のようになるでしょう。

  1. タイプを作る手続きや構文を使って構造を定義する (see section Structure types)
  2. 定義した構造のreader/writerを得る
  3. reader/writerを使ってデータを読み書きする

以下に完全に動作する簡単な例を示します。

 
(use binary.struct)

(define struct-type
  (bs:struct
   ((num1  'u8)
    (num2  'u16le)
    (count 'u8)
    (str   (bs:cstring 10))
    (arr   (bs:array count 'u8))
    )))

(define writer (bs:writer-of struct-type))

(call-with-output-string
  (lambda (out)
    (writer
     '((num1  . 97)
       (num2  . 321)
       (count . 3)
       (str   . "abcdefg")
       (arr   . (1 2 3)))
     out)))
⇒ "aA\x01\x03abcdefg\0\0\0\x01\x02\x03"

(define reader (bs:reader-of struct-type))

(call-with-input-string "aA\x01\x03abcdefg\0\0\0\x01\x02\x03"
  reader)
⇒ ((num1 . 97) (num2 . 321) (count . 3) (str . "abcdefg") (arr 1 2 3))

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 The type and conditions

Class: <bs:type>

「タイプ」を表すオブジェクトのクラスです。タイプは特定のバイナリ構造を表現し、具体的にはreaderとwriterのペアです。

Function: bs:make-type reader writer

新しいタイプを作ります。

reader

入力ポートを引数にとり、入力ポートから読み込んだデータを返す手続きです。 読み込んだデータがタイプにとって不正な場合は<bs:read-error>をスローしなければいけません。

writer

データと出力ポートの二つを引数にとり、データを出力ポートに書き出す手続きです。 与えられたデータがタイプにとって不正な場合は<bs:marshal-error>をスローしなければいけません。

読み込みまたは書き出しのみに興味がある場合は、readerwriter#fを渡せます。

Function: bs:reader-of type
Function: bs:writer-of type

それぞれtypeのreader/writer手続きを返します。 typeがシンボルでありそのシンボルが下記のいずれかであれば、そのタイプのreader/writer手続きが返されます。

 
u8 u16 u32 u64 s8 s16 s32 s64 f16 f32 f64 ber-integer
u8le u16le u32le u64le s8le s16le s32le s64le f16le f32le f64le
u8be u16be u32be u64be s8be s16be s32be s64be f16be f32be f64be

これらはbinary.ioモジュールの手続きに対応します。 ただし、readerはEOFが返された場合<bs:eof-error>をスローし、 writerは書き出すことが出来ないデータが与えられた場合<bs:marshal-error>をスローします。

Class: <bs:read-error>

readerが読み込んだデータがタイプにとって正しくない場合にスローされます。

Class: <bs:eof-error>

readerが受け入れる事の出来るデータを読み終える前にEOFに到達した場合にスローされます。 <bs:read-error>を継承しています。

Class: <bs:marshal-error>

writerに渡されたデータがタイプにとって正しくない場合にスローされます。

Class: <bs:field-not-found>

構造体に存在しない名前のフィールドを参照しようとしたときにスローされます。See section Utility functions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Structure types

基本的な構造を定義するためのタイプを返す手続きと構文です。

Function: bs:cstring &optional size must-terminate?

null終端の文字列を読み書きするためのタイプを返します。 オプション引数のsizeが与えられた場合とそうでない場合で、動作が変わります。

must-terminate?のデフォルトは#tです。

Function: bs:block size

sizeの大きさのu8vectorを読み書きするためのタイプを返します。

Function: bs:array num subtype

num個のsubtypeを読み書きするためのタイプを返します。

Macro: bs:struct ((name type) …)

構造体を読み書きするためのタイプを返します。構造体は連想リストとして読み書きされます。

nameは同名のシンボルが連想リストのcarの値として使われるほか、 読み込み時にはtypeのreaderが読み込んだデータが束縛され、書き出し時にはデータとして与えられた連想リストの cdrの値に束縛されます。

基本的には次のように展開されます。

 
(bs:struct
  ((len 'u8)
   (str (bs:cstring len))))
  ≡
(bs:make-type
  (lambda (in)
    (let* ((len ((bs:reader-of 'u8) in))
           (str ((bs:reader-of (bs:cstring len)) in)))
      (list (cons 'len len)
            (cons 'str str))))
  (lambda (data out)
    (let ((len (bs:struct-ref data 'len))
          (str (bs:struct-ref data 'str)))
      ((bs:writer-of 'u8) len out)
      ((bs:writer-of (bs:cstring len)) str out))))
Function: bs:check pred type

typeと同じデータを読み書きするタイプを返します。ただし

reader

読み込んだデータがpredに渡され、pred#fを返した場合<bs:read-error>をスローします。

writer

渡されたデータがpredに渡され、pred#fを返した場合<bs:marshal-error>をスローします。

Function: bs:const val-required type &optional val-equal?

typeと同じデータを読み書きするタイプを返します。ただし

reader

読み込んだデータがval-requiredに一致しなければ<bs:read-error>をスローします。

writer

渡されたデータがval-requiredに一致しなければ<bs:marshal-error>をスローします。

オプションのval-equal?はデータを比較するのに使われ、デフォルトではequal?が使われます。

Function: bs:or type …

type …のどれかと同じタイプを読み書きするタイプを返します。

reader

まずtype …の始めのreaderを使って読み込みを試します。 もしtypeのreaderが<bs:read-error>をスローしたら、残りのタイプを順に試します。 始めに読み込みに成功したタイプのデータが返されます。 どのタイプも読み込みに成功しなければ<bs:read-error>をスローします。

writer

同様にtype …の始めのwriterを使って書き込みを試し、 typeのwriterが<bs:marshal-error>をスローしたら、残りのタイプを順に試します。 どのタイプも書き込みに成功しなければ<bs:marshal-error>をスローします。

このタイプのreaderに渡されるポートはシーク操作が可能である必要があります。

Function: bs:many subtype &optional lower upper

個数の範囲が指定されたsubtypeのシーケンスを読み書きするタイプを返します。 lowerupperが与えられていない場合はそれぞれ0と無限大と解釈されます。

reader

subtypeのreaderが<bs:read-error>をスローするまで入力ポートから読み込み、 読み込んだデータをリストにして返します。もしオプションのlowerが与えられた場合、 読み込めたデータの個数がlowerより小さければ<bs:read-error>をスローします。 upperが与えられていた場合はupperまで読み込めばその時点までに読み込んだデータを返します。

writer

データとしてリストを受け取り、subtypeのwriterを使ってリストの各要素を書き出します。 lowerupperが与えられていた場合、writerに与えられたリストの長さが指定された範囲外であれば、 <bs:marshal-error>をスローします。

このタイプのreaderに渡されるポートはシーク操作が可能である必要があります。

Function: bs:many2 size subtype

読み書きするデータのバイト数が指定されたsubtypeのシーケンスを読み書きするタイプを返します。

reader

読み込んだデータのサイズがsizeに一致するまでsubtypeのリーダーを呼び、一致すれば読み込んだデータをリストとして返します。 もし読み込んだデータのサイズがsizeを超えれば<bs:read-error>をスローします。

writer

与えられたデータの全ての要素をsubtypeのwriterを使って書き出します。 与えられたデータを全て書き出す前にsizeを超えたり、データを全て書き出してもsizeに満たない場合は <bs:marshal-error>をスローします。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Utility functions

Function: bs:struct-ref struct name

structnameフィールドの値を返します。 structnameがみつからなければ、<bs:field-not-found>をスローします。

Function: bs:struct-ref* struct name …

ネストした構造体のフィールドを得るためのユーティリティです。

 
(bs:struct-ref* struct 'field1 'field2)
  ≡ (bs:struct-ref (bs:struect-ref struct 'field1) 'field2)
Function: bs:struct-set! struct name value

structnameフィールドの値をvalueにセットします。 structnameがみつからなければ、<bs:field-not-found>をスローします。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A. Function and Syntax Index

Jump to:   B  
Index Entry Section

B
bs:array1.2 Structure types
bs:block1.2 Structure types
bs:check1.2 Structure types
bs:const1.2 Structure types
bs:cstring1.2 Structure types
bs:make-type1.1 The type and conditions
bs:many1.2 Structure types
bs:many21.2 Structure types
bs:or1.2 Structure types
bs:reader-of1.1 The type and conditions
bs:struct1.2 Structure types
bs:struct-ref1.3 Utility functions
bs:struct-ref*1.3 Utility functions
bs:struct-set!1.3 Utility functions
bs:writer-of1.1 The type and conditions

Jump to:   B  

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B. Class Index

For readability, the surrounding < and > are stripped off.

Jump to:   B  
Index Entry Section

B
bs:eof-error1.1 The type and conditions
bs:field-not-found1.1 The type and conditions
bs:marshal-error1.1 The type and conditions
bs:read-error1.1 The type and conditions
bs:type1.1 The type and conditions

Jump to:   B  

[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on April, 27 2007 using texi2html 1.76.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack beginning of this chapter or previous chapter 1
[ Up ] Up up section 1.2
[ >> ] FastForward next chapter 2
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index index  
[ ? ] About about (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on April, 27 2007 using texi2html 1.76.