1: @node Library modules - Utilities, References, Library modules - SRFIs, Top 2: @chapter Library modules - Utilities 3: @c NODE ?饤?Ö¥??⥸?塼?? ?桼?Æ¥????? 4: 5: 6: @c ---------------------------------------------------------------------- 7: @menu 8: * Binary I/O:: 9: * Packing Binary Data:: 10: * Rational-less arithmetic:: 11: * Database independent access layer:: 12: * Generic DBM interface:: 13: * File-system dbm:: 14: * GDBM interface:: 15: * NDBM interface:: 16: * Original DBM interface:: 17: * Filtering file content:: 18: * Filesystem utilities:: 19: * Mathematic constants:: 20: * Mersenne-Twister random number generator:: 21: * RFC822 message parsing:: 22: * Base64 encoding/decoding:: 23: * HTTP cookie handling:: 24: * FTP:: 25: * HMAC keyed-hashing:: 26: * HTTP:: 27: * IP packets:: 28: * ICMP packets:: 29: * MD5 message digest:: 30: * MIME message handling:: 31: * Quoted-printable encoding/decoding:: 32: * SHA1 message digest:: 33: * URI parsing and construction:: 34: * SLIB:: 35: * Functional XML parser:: 36: * SXML Query Language:: 37: * Manipulating SXML structure:: 38: * Serializing XML and HTML from SXML:: 39: * CSV tables:: 40: * Calculate difference of text streams:: 41: * Localized messages:: 42: * Simple HTML document construction:: 43: * Parsing input stream:: 44: * Showing progress on text terminals:: 45: * SQL parsing and construction:: 46: * Transliterate characters:: 47: * Lazy text construction:: 48: * Combination library:: 49: * Message digester framework:: 50: * Determine isomorphism:: 51: * The longest common subsequence:: 52: * Additional list library:: 53: * Pattern matching:: 54: * Queue:: 55: * Red black tree:: 56: * SLIB-compatible record type:: 57: * Relation framework:: 58: * Stream library:: 59: * Trie:: 60: * Topological sort:: 61: * CGI Utility:: 62: * CGI testing:: 63: @end menu 64: 65: @c ---------------------------------------------------------------------- 66: @node Binary I/O, Packing Binary Data, Library modules - Utilities, Library modules - Utilities 67: @section @code{binary.io} - Binary I/O 68: @c NODE ?Ð¥??Ê¥?O, @code{binary.io} - ?Ð¥??Ê¥?O 69: 70: @deftp {Module} binary.io 71: @mdindex binary.io 72: @c EN 73: This module provides basic procedures to perform binary I/O 74: of numeric data. Each datum can be read from or written to a port, 75: and got from or put to a uniform vector (see @ref{Uniform vectors}). 76: For structured binary data I/O, 77: more convenient @code{pack} utility is implemented 78: on top of this module (see @ref{Packing Binary Data}). 79: You might want to use this module directly if you need 80: speed or want a flexible control of endianness. 81: 82: See also @ref{Uniform vectors}, which provides binary block I/O. 83: @c JP 84: ???Υ⥸?塼????Ç¡?????ß½ñ¤¤??????Ê¥????Ѥδ???????????Þ¤????ƥǡ????ϥݡ??Ȥ??뤤?Ï¥??Õ¥????????? 85: (@ref{Uniform vectors}?????????ß¹??ß¡????뤤?Ϥ????ؽñ¤½Ð¤????Ȥ? 86: ?Ǥ??Þ¤??? 87: ??¤??ĥХ??Ê¥??????????ϤˤĤ??Ƥϡ?????@code{pack}?桼?Æ¥??????????Υ⥸?塼???ȤäƼ?õ¤µ¤????Þ¤? 88: (@ref{Packing Binary Data}?ò»²¾È¤??Ƥ??????)?? 89: ???Ô¡??ɤ??뤤?Ï¥??????????????ɤ?ꤿ???Ȥ??ˤ??Υ⥸?塼 90: ?뤬?Ȥ??Þ¤??? 91: 92: ?Ð¥??Ê¥??Ö¥??????ϤˤĤ??Ƥ?ref{Uniform vectors}?ò»²¾È¤??Ƥ????????? 93: @c COMMON 94: @end deftp 95: 96: @c EN 97: @subheading Endianness 98: Most procedures of this module take an optional @var{endian} argument, 99: specifying the byte order of the binary input. 100: It must be either one of symbols @code{big-endian}, @code{little-endian}, 101: or @code{arm-little-endian}. 102: If the endian argument is omitted, the current value of the builtin 103: parameter @code{default-endian} is used. The default value of 104: the @code{default-endian} parameter is the machine's native endian. 105: (For 8-bit I/O procedures like @code{read-u8} the endian 106: argument has no effect, but is accepted for consistency). 107: @c JP 108: @subheading ???????????Υ⥸?塼???ۤȤ?μ??Ï¥??×¥?????????var{endian}?? 109: ?Ȥ?????????@code{big-endian}??@code{little-endian}?? 110: @code{arm-little-endian}?Τ????줫?Î¥?????ʤ????ʤ??????????????ô¤¬¾?????줿???ˤϡ?????ߥѥ?????@code{default-endian} 111: ?θ???ͤ??Ȥ??Þ¤???@code{default-endian}?ν???????η׻????ǤΥ???????????(@code{read-u8}???褦??8?ӥå????ϼ??Ǥϥ????????????????????󤬡? 112: ????Τ?????????褦?ˤ??Ƥ???????) 113: @c COMMON 114: 115: @deffn {Builtin Parameter} default-endian &optional value 116: @c EN 117: When called without @var{value}, returns the current default 118: endian. When called with @var{value}, sets the current endian 119: to the @var{value}, which must be one of the following symbols: 120: @c JP 121: @var{value}̵???ǸƤФ??È¡????ߤΥǥե????????????ͤ???Þ¤??? 122: @var{value}??äƸƤФ??È¡?????ͤ?Õ¥??????????????Þ¤??? 123: ?????????ͤϰʲ??Τ????줫?Î¥?????ʤ????ʤ?????@c COMMON 124: @table @code 125: @item big-endian 126: @c EN 127: Big endian. An integer @code{#x12345678} is written out as an octet 128: sequence @code{#x12 #x34 #x56 #x78}. 129: @c JP 130: ?ӥå?????????????code{#x12345678}??code{#x12 #x34 #x56 #x78} 131: ?Τ褦?ʥХ??È¥??????󥹤Ȥ??ƽ?Ϥ??????? 132: @c COMMON 133: @item little-endian 134: @c EN 135: Little endian. An integer @code{#x12345678} is written out as an octet 136: sequence @code{#x78 #x56 #x34 #x12}. 137: @c JP 138: ???륨??????????code{#x12345678}??code{#x78 #x56 #x34 #x12} 139: ?Τ褦?ʥХ??È¥??????󥹤Ȥ??ƽ?Ϥ??????? 140: @c COMMON 141: @item arm-little-endian 142: @c EN 143: This is a variation of @code{little-endian}, and used in ARM 144: processors in some specific modes. It works just like @code{little-endian}, 145: except reading/writing double-precision floating point number (@code{f64}), 146: which is written as two little-endian 32bit words ordered by big-endian 147: (e.g. If machine register's representation is @code{#x0102030405060708}, 148: it is written as @code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}. 149: @c JP 150: ????@code{little-endian}?ΥХꥨ???????Ç¡?ARM?×¥í¥»?Ã¥??????Υ⡼?ɤǻȤ????ΤǤ???????Æ°????????code{little-endian} 151: ?????????Þ¤???????Æ°?????Ĥ??Ƥϡ??Õ¤??ĤΥ??륨?????????ɤ? 152: ?ӥå????????????ñ¤½Ð¤????? (????Ð¥Þ¥???????????Υӥåȥѥ?????@code{#x0102030405060708}?ξ?????Ϥ?@code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}?Ȥʤ???)?? 153: @c COMMON 154: @end table 155: 156: @c EN 157: The default endian value is thread-local. You can use @code{parameterize} 158: (@xref{Parameters}) to switch default endianness within certain dynamic scope. 159: @c JP 160: ?Ç¥Õ¥????????????Ï¥????É¥í¡¼????????@code{parameterize} 161: (@ref{Parameters}????????뤳?Ȥǡ?????ͤ??????ʥߥå????????פ??Ö¤????????뤳?Ȥ??Ǥ??Þ¤??? 162: @c COMMON 163: @end deffn 164: 165: @c EN 166: @subheading I/O using port 167: @c JP 168: @subheading ?Ý¡??Ȥ????I/O 169: @c COMMON 170: 171: @defun read-u8 &optional port endian 172: @defunx read-u16 &optional port endian 173: @defunx read-u32 &optional port endian 174: @defunx read-u64 &optional port endian 175: @c EN 176: Reads 8, 16, 32 or 64 bit unsigned integer from @var{port} 177: with specified endian, respectively. If @var{port} is omitted, 178: current input port is used. If @var{port} reaches EOF before 179: a complete integer is read, EOF is returned. 180: @c JP 181: ???줾????????????????var{port}?????16??32??64?ӥå??̵ 182: ???ɤ߹??ߤޤ???@var{port}????????줿???Ï¡????ߤ????Ý¡??Ȥ??????Þ¤???@var{port}?????ɤ߹??ߤ???λ??????OF???ã???Ƥ??Þ¤??????ˤ?OF????????? 183: @c COMMON 184: @end defun 185: 186: @defun read-s8 &optional port endian 187: @defunx read-s16 &optional port endian 188: @defunx read-s32 &optional port endian 189: @defunx read-s64 &optional port endian 190: @c EN 191: Reads 8, 16, 32 or 64 bit 2's complement signed integer from @var{port} 192: with specified endian, respectively. If @var{port} is omitted, 193: current input port is used. If @var{port} reaches EOF before 194: a complete integer is read, EOF is returned. 195: @c JP 196: ???줾????????????????var{port}?????16??32??64?ӥåȡ?2??????????ɤ߹??ߤޤ???@var{port}????????줿???Ï¡????ߤ??? 197: ?Ý¡??Ȥ??Ȥ??Þ¤???@var{port}?????ɤ߹??ߤ???λ??????OF??? 198: ã???Ƥ??ޤä????ˤ?OF????????? 199: @c COMMON 200: @end defun 201: 202: @defun read-uint size &optional port endian 203: @defunx read-sint size &optional port endian 204: @c EN 205: More flexible version. Reads @var{size}-octet unsigned 206: or signed integer from @var{port} with specified endian. 207: If @var{port} reaches EOF before a complete integer is read, 208: EOF is returned. 209: @c JP 210: ?????????⤯??@var{size}?????ƥåȤ??̵?????뤤?????????@var{port}??????Î¥????????ɤ߹??ߤޤ??? 211: @var{port}?????ɤ߹??ߤ???λ??????OF??? 212: ã???Ƥ??ޤä????ˤ?OF????????? 213: @c COMMON 214: @end defun 215: 216: @defun read-ber-integer &optional port 217: @c EN 218: Reads BER compressed integer a la X.209. 219: A BER compressed integer is an unsigned integer in base 128, 220: most significant digit first, where the high bit is set on all but the 221: final (least significant) byte. 222: @c JP 223: X.209??ER???Ì·?????ɤ߹??ߤޤ???BER???Ì·?????28???̵??? 224: ??????Ǿ??夬?ǽ????Þ¤????Dz??Ì·??Ð¥??Ȥ?????????٤ƤΥХ? 225: ?ȤκǾ??ӥåȤϥ???ʤäƤ??Þ¤??? 226: @c COMMON 227: @end defun 228: 229: @defun write-u8 val &optional port endian 230: @defunx write-u16 val &optional port endian 231: @defunx write-u32 val &optional port endian 232: @defunx write-u64 val &optional port endian 233: @c EN 234: Writes a nonnegative integer @var{val} as 8, 16, 32 or 64 bit 235: unsigned integer 236: to @var{port} with specified endian, respectively. @var{Val} must be within 237: the range of integers representable by the specified bits. 238: When @var{port} is omitted, current output port is used. 239: @c JP 240: ???줾????????????????var{port}??8??16??32??64?ӥåȡ???? 241: ???????????????????????r{val}????Ф??Þ¤??? 242: @var{val}?Ϥ??줾????????ӥåȿ?ϰϤ?????Ǥ????Ǥʤ????ʤ?Þ¤???var{port}????????줿???Ï¡????ߤν?ϥݡ??Ȥ??Ȥ??Þ¤??? 243: @c COMMON 244: @end defun 245: 246: @defun write-s8 val &optional port endian 247: @defunx write-s16 val &optional port endian 248: @defunx write-s32 val &optional port endian 249: @defunx write-s64 val &optional port endian 250: @c EN 251: Writes an integer @var{val} as 8, 16, 32 or 64 bit 252: as 2's complement signed integer to @var{port} with specified endian, 253: respectively. @var{Val} must be within 254: the range of integers representable by the specified bits. 255: When @var{port} is omitted, current output port is used. 256: @c JP 257: ???줾????????????????var{port}??8??16??32??64?ӥåȡ?2??????????????????????????r{val}????Ф??Þ¤??? 258: @var{val}?Ϥ??줾????????ӥåȿ?ϰϤ?????Ǥ????Ǥʤ????ʤ?Þ¤???var{port}????????줿???Ï¡????ߤν?ϥݡ??Ȥ??Ȥ??Þ¤??? 259: @c COMMON 260: @end defun 261: 262: @defun write-uint size val &optional port endian 263: @defunx write-sint size val &optional port endian 264: @c EN 265: More flexible version. Writes an integer @var{val} as unsigned 266: or signed integer of @var{size} bytes to @var{port} with 267: specified endian. 268: When @var{port} is omitted, current output port is used. 269: @c JP 270: ?????????⤯??@var{size}?????ƥåȤ??̵?????뤤?????????ar{val}??r{port}?Ø¡?????????????ñ¤½Ð¤??Þ¤??? 271: @var{port}????????줿???Ï¡????ߤν?ϥݡ??Ȥ??Ȥ??Þ¤??? 272: @c COMMON 273: @end defun 274: 275: @defun write-ber-integer val &optional port 276: @c EN 277: Writes a nonnegative integer @var{val} in BER compressed integer 278: to @var{port}. See @code{read-ber-integer} above for BER format. 279: @c JP 280: BER???Ì·????????r{val}??r{port}?ؽñ¤½Ð¤??Þ¤??? 281: BER???Ì·???ˤĤ??Ƥ???Ò¤?code{read-ber-integer}?ò¸«¤Æ¤???????? 282: @c COMMON 283: @end defun 284: 285: @defun read-f16 &optional port endian 286: @defunx read-f32 &optional port endian 287: @defunx read-f64 &optional port endian 288: @c EN 289: Reads 16, 32, or 64-bit floating point numbers, respectively. 290: 32bit is IEEE754 single-precision, and 64bit is 291: IEEE754 double-precision numbers. 16-bit floating 292: point number consists of 1-bit sign, 5-bit exponent and 293: 10-bit mantissa, as used in some HDR image format. 294: 295: If @var{port} is omitted, 296: current input port is used. If @var{port} reaches EOF before 297: a complete number is read, EOF is returned. 298: @c JP 299: ???줾?ì¡¢16??32??64?ӥåȤ???????ɤ߹??ߤޤ??? 300: 32?ӥåȤ?EEE754ñ????64?ӥåȤ??????????????? 301: 16?ӥå????????1?ӥåȤ????5?ӥåȤλؿ?0?ӥåȤβ??ô¤«¤??ë¡¢ 302: HDR???᡼???Õ¥????ޥå?????Ƥ??????Ǥ??? 303: 304: @var{port}????????줿???ˤϡ? 305: ???ߤ????Ý¡??Ȥ??Ȥ??Þ¤???@var{port}?????ɤ߹??ߤ???λ??????EOF???ã???Ƥ??ޤä????ˤ?OF????????? 306: @c COMMON 307: @end defun 308: 309: @defun write-f16 val &optional port endian 310: @defunx write-f32 val &optional port endian 311: @defunx write-f64 val &optional port endian 312: @c EN 313: Writes a real number @var{val} to @var{port} in 16, 314: 32, or 64-bit floating point number, respectively. 315: If @var{port} is omitted, current output port is used. 316: @c JP 317: ?¿?var{val}?ò¡¢¤??줾????32??64?ӥåȤ???????????ñ¤½Ð¤??Þ¤??? 318: @var{port}????????줿???ˤϡ????ߤν?ϥݡ??Ȥ??Ȥ??Þ¤??? 319: @c COMMON 320: @end defun 321: 322: 323: @c EN 324: @subheading I/O using uniform vectors 325: @c JP 326: @subheading ???Õ¥??????????????I/O 327: @c COMMON 328: 329: @c EN 330: In the following routines, the argument @var{uv} can be any 331: type of uniform vector; if it is not a @code{u8vector}, it is 332: treated as if @code{(uvector-alias <u8vector> @var{uv})} is 333: called---that is, it reads directly from the memory image 334: that holds the uvector's content. The @var{pos} argument 335: specifies the byte position from the beginning of the memory 336: area (it is always byte position, regardless of the uniform 337: vector's element size). 338: @c JP 339: ?ʲ??Υ롼???Ï¡???var{uv} ????դη??Î¥??Õ¥??????????????Þ¤???@code{u8vector} ?ǤϤʤ????ˤ?@code{(uvector-alias 340: <u8vector> @var{uv})} ???ƤФ줿?Τ????ΰ????ˤʤ????????ʤ??? 341: uvector????????ꥤ?᡼?????????ß¹??Þ¤?????@var{pos} 342: ??????Î¥??????ǽ餫???Ð¥??È°?Ö¤?ꤹ???˻Ȥ??Þ¤?(?? 343: ?????Õ¥????????????ǤΥ??????ˤ??????????Ĥͤ˥Х??È°?֤Ǥ?)?? 344: @c COMMON 345: 346: @defun get-u8 uv pos &optional endian 347: @defunx get-u16 uv pos &optional endian 348: @defunx get-u32 uv pos &optional endian 349: @defunx get-u64 uv pos &optional endian 350: @defunx get-s8 uv pos &optional endian 351: @defunx get-s16 uv pos &optional endian 352: @defunx get-s32 uv pos &optional endian 353: @defunx get-s64 uv pos &optional endian 354: @defunx get-f16 uv pos &optional endian 355: @defunx get-f32 uv pos &optional endian 356: @defunx get-f64 uv pos &optional endian 357: @c EN 358: Reads a number of a specific format from a uniform vector @var{uv}, 359: starting at a byte position @var{pos}. An error is signalled 360: if the specified position makes reference outside of the uniform 361: vector's content. Returns the read number. 362: @c JP 363: ???Õ¥????????? @var{uv} ?ΥХ??È°??@var{pos} ??????????Õ¥??? 364: ?ޥåȤǿ??ß¹??ß¡????ο????Þ¤?????ꤷ????Ö¤???????Õ¥??? 365: ??????????Τ????ϳ??ò»²¾È¤????ΤǤ??ä????????顼?ò¼¨¤????? 366: ?ʥ뤬?????????? 367: @c COMMON 368: @end defun 369: 370: @defun get-u16be uv pos 371: @defunx get-u16le uv pos 372: @defunx get-u32be uv pos 373: @defunx get-u32le uv pos 374: @defunx get-u64be uv pos 375: @defunx get-u64le uv pos 376: @defunx get-s16be uv pos 377: @defunx get-s16le uv pos 378: @defunx get-s32be uv pos 379: @defunx get-s32le uv pos 380: @defunx get-s64be uv pos 381: @defunx get-s64le uv pos 382: @defunx get-f16be uv pos 383: @defunx get-f16le uv pos 384: @defunx get-f32be uv pos 385: @defunx get-f32le uv pos 386: @defunx get-f64be uv pos 387: @defunx get-f64le uv pos 388: @c EN 389: These are big-endian (@code{be}) or little-endian (@code{le}) specific 390: versions of @code{get-*} procedures. In speed-sensitive code, 391: you might want to use these to avoid the overhead of optional-argument 392: handling. 393: @c JP 394: ?????Ï¡?@code{get-*} ???Î¥?????????Ã¥??????????ode{be} 395: ???뤤?Ï¥??륨???????ode{le})??ꤷ????Ǥ??????Ô¡??ɤ??????????ɤǤϥ??×¥???????Î¥????С??إåɤ???뤿?ᤳ??? 396: ?Ȥ??Τ??????Ǥ??礦?? 397: @c COMMON 398: @end defun 399: 400: @defun put-u8! uv pos val &optional endian 401: @defunx put-u16! uv pos val &optional endian 402: @defunx put-u32! uv pos val &optional endian 403: @defunx put-u64! uv pos val &optional endian 404: @defunx put-s8! uv pos val &optional endian 405: @defunx put-s16! uv pos val &optional endian 406: @defunx put-s32! uv pos val &optional endian 407: @defunx put-s64! uv pos val &optional endian 408: @defunx put-f16! uv pos val &optional endian 409: @defunx put-f32! uv pos val &optional endian 410: @defunx put-f64! uv pos val &optional endian 411: @c EN 412: Writes a number @var{val} into a uniform vector @var{uv} in 413: a specific format, starting at a byte position @var{pos}. 414: An error is signalled 415: if the specified position makes reference outside of the uniform 416: vector's content. 417: @c JP 418: ??@var{val} ??Ë¥Õ¥????????? @var{uv} ?ΥХ??È°??@var{pos} ?? 419: ??????줿?Õ¥????ޥåȤǽñ¤½Ð¤??Þ¤?????ꤷ????Ö¤???????Õ¥?????Ù¥???????Τ????ϳ??ò»²¾È¤????ΤǤ??ä????????顼?ò¼¨¤????????뤬?????????? 420: @c COMMON 421: @end defun 422: 423: @defun put-u16be! uv pos val 424: @defunx put-u16le! uv pos val 425: @defunx put-u32be! uv pos val 426: @defunx put-u32le! uv pos val 427: @defunx put-u64be! uv pos val 428: @defunx put-u64le! uv pos val 429: @defunx put-s16be! uv pos val 430: @defunx put-s16le! uv pos val 431: @defunx put-s32be! uv pos val 432: @defunx put-s32le! uv pos val 433: @defunx put-s64be! uv pos val 434: @defunx put-s64le! uv pos val 435: @defunx put-f16be! uv pos val 436: @defunx put-f16le! uv pos val 437: @defunx put-f32be! uv pos val 438: @defunx put-f32le! uv pos val 439: @defunx put-f64be! uv pos val 440: @defunx put-f64le! uv pos val 441: @c EN 442: These are big-endian (@code{be}) or little-endian (@code{le}) specific 443: versions of @code{put-*} procedures. In speed-sensitive code, 444: you might want to use these to avoid the overhead of optional-argument 445: handling. 446: @c JP 447: ?????Ï¡?@code{put-*} ???Î¥?????????Ã¥??????????ode{be} 448: ???뤤?Ï¥??륨???????ode{le})??ꤷ????Ǥ??????Ô¡??ɤ??????????ɤǤϥ??×¥???????Î¥????С??إåɤ???뤿?ᤳ??? 449: ?Ȥ??Τ??????Ǥ??礦?? 450: @c COMMON 451: @end defun 452: 453: @c EN 454: @subheading Compatibility notes 455: @c JP 456: @subheading ?ß´???ؤ??c COMMON 457: 458: @c EN 459: @code{read-u8} etc. were called @code{read-binary-uint8} etc., and 460: @code{read-f32} and @code{read-f64} were called @code{read-binary-float} 461: and @code{read-binary-double}, respectively. 462: These old names are still supported for the backward compatibility 463: but their use is deprecated. The reason of the changes is 464: for brevity and for consistency with the uniform vectors. 465: @c JP 466: @code{read-u8} ?ʤɤ?@code{read-binary-uint8} ?ȸƤФ????????Ç¡? 467: @code{read-f32} ??code{read-f64} ?Ϥ??줾??code{read-binary-float}?? 468: @code{read-binary-double} ?ȸƤФ????????Ǥ??? 469: ?????θŤ?̾??ϸ??ß´??Τ??ᤤ?ޤΤȤ??í¥µ?Ý¡??Ȥ??????Þ¤?????????ˤĤ??Ƥ????Ȥ??Þ¤???????ѹ?????????̤ȥ??Õ¥????????????ΰ???Ý»???Ô¤??Þ¤????? 470: @c COMMON 471: 472: @c ---------------------------------------------------------------------- 473: @node Packing Binary Data, Rational-less arithmetic, Binary I/O, Library modules - Utilities 474: @section @code{binary.pack} - Packing Binary Data 475: @c NODE ?Ð¥??Ê¥??????Υѥå?, @code{binary.pack} - ?Ð¥??Ê¥??????Υѥå? 476: 477: @deftp {Module} binary.pack 478: @mdindex binary.pack 479: @c EN 480: This module provides an interface for packing and unpacking (writing 481: and reading) binary data with templates. The functionality was 482: inspired largely by the Perl pack/unpack functions, with comparison of 483: similar features from other languages, however an effort was made to 484: make it more general and more efficient, to be usable for 485: database-like processing. To that end, the most notable differences 486: are that any packable value is unpackable (and vice versa), and the 487: default behavior is to pack and unpack using port I/O, so you can seek 488: in a large file and unpack from it. Also, templates may be stored as 489: dispatch closures to pack, unpack or even skip over values without 490: re-parsing the template. 491: @c JP 492: ???Υ⥸?塼?????Ð¥??Ê¥????????졼?Ȥ?ä??ѥå?/????Ã¥?(??ß½????뤿?????󥿥ե???????????Þ¤??? 493: ???ε?ǽ?Ï¡??????????l??ack/unpack?Ø¿ô¤«¤??????¾?θ????Ʊ???褦?ʵ?ǽ??????ʤ??é¡¢?????????Ç¡????Ù¡????饤???ʽ??????ʤ褦?Ë¡?????Ū?Ǥ???????ʤ????˼?õ¤·¤Þ¤????? 494: ?????õ¤±¤Æ¡??Ǥ????????Ï¡???ƤΥѥå??????ͤϥ???Ã¥? 495: ??????Õ¤??)???ѥå?/????Ã¥??Υǥե????ο??????ϥݡ???/O?????Τǡ???Ê¥Õ¥???????ߤʤ??餽?????饢??Ã¥????뤳?Ȥ? 496: ?Ǥ??Þ¤????Þ¤????Æ¥?졼?Ȥϥǥ????ѥå???í¡¼???????Ƴ???Ǥ??? 497: ?ѥå???????Ã¥??????뤤??ͤΥ????åפ????â¡¢?Æ¥?졼?Ȥ???????ľ?????Ȥʤ??Ô¤??Þ¤??? 498: @c COMMON 499: 500: @c See also binary.io - Binary I/O for utilities to read and write 501: @c individual binary values. 502: @end deftp 503: 504: @defun pack template list &keyword :output :to-string? 505: @c EN 506: Writes the values in @var{list} to the current output port, according 507: to the format specified by the string @var{template}. The template 508: string is a series of single character codes, optionally followed by a 509: numeric count (which defaults to 1). 510: @c JP 511: @var{list}?ˤ????????ar{template}?Ç»?ꤵ?줿?Õ¥????ޥåȤ????????äơ????ߤν?ϥݡ??Ȥ˽ñ¤½Ð¤??Þ¤????Æ¥?졼??????? 512: 1ʸ?????ɤ??³?Ç¡????×¥??????Ç¥Õ¥?????1?Ǥ????????Ѥο???³???Þ¤??? 513: 514: @c EN 515: The format characters can generally be divided into string types, 516: which interpret the count as a string byte size, and object types, 517: which treat the count as a repetition indicator. The count may be 518: specified as the character @code{*}, which means to use the full 519: size of the string for string types, and use all remaining values for 520: object types. 521: @c JP 522: ?Õ¥????ޥå?????Ū?Ë¡????????????È¿?????????È¡???????ò·«¤????ؼ??ҤȲ???륪?Ö¥??????È·???ʬ?????Þ¤?????????????e{*}?Ç»?ꤵ?졢ʸ???Ǥ?ʸ??????????ò¡¢¥??Ö¥??????È·??ǤϻĤ???Ƥ?ͤ?????Ȥ?Ì£???Þ¤??? 523: 524: @c EN 525: Counts may also be specified as a template enclosed in brackets, which 526: means the count is the byte size of the enclosed template. For 527: example, @code{x[L]} skips a long. 528: @c JP 529: ?????????̤˰Ϥޤ줿?Æ¥?졼?ȤȤ??Ƥ???Ǥ??????ξ? 530: ??????Ϥ?????̤???????졼?ȤΥХ??È¿??????Þ¤??? 531: ????С?@code{x[L]}??ong?ò¥¹¥??åפ??Þ¤??? 532: 533: @c EN 534: The special format character @code{/} may be used to indicate a 535: structure where the packed data contains a dynamic count followed by 536: the value itself. The template is written as 537: @code{<count-item>/<value-item>}, where @code{<count-item>} is any 538: template character to be interpreted as a numeric count, and 539: @code{<value-item>} is any other template character to use this count. 540: If a normal count is given after @code{<value-item>} it is ignored. 541: @c JP 542: ???Ê¥Õ¥????ޥå????e{/}?Ï¡??ѥå????줿?Ç¡????????????? 543: ưŪ?Ê¥???????????????¤????????Ȥ??Þ¤??? 544: ?Æ¥?졼?Ȥϡ?@code{<count-item>/<value-item>}?Τ褦?˽ñ¤«¤ì¡¢ 545: ?????Ǥ?code{<count-item>}?Ï¿?Î¥?????Ȳ?????????ʤ?Æ¥?졼?????ode{<value-item>}?Ϥ??Î¥????????????ʤ???Υƥ?졼??????? 546: @code{<value-item}>?θ???????????Í¿?????Ƥ⡢̵?뤵?????? 547: 548: @c EN 549: The format character @code{@@} may be used with a count to pad to an 550: absolute position since the start of the template. 551: @c JP 552: ?Õ¥????ޥå????e{@@}?Ï¡???????ȤȤ??Ȥ????Æ¥?졼?Ȥ??ǽ餫??????֤ޤǥѥǥ??ó¥°¤??Þ¤??? 553: 554: @c EN 555: Sub-templates may be grouped inside parentheses. If angle-brackets 556: are used, then they also behave as group operators but recursively 557: operate on nested lists. 558: @c JP 559: ???֥ƥ?졼?Ȥϡ?????????롼?ײ?????????<>???Ȥ????? 560: ?Í¥??Ȥ??줿?ꥹ?Ȥ˺Ƶ?Ū???????????롼?ײ????ڥ졼???Ȥ??Ƥ??????Þ¤??? 561: 562: @c EN 563: The string types: 564: @c JP 565: ʸ??: 566: 567: @c COMMON 568: @table @code 569: @item a 570: @c EN 571: An arbitrary incomplete string, null padded. 572: @c JP 573: Ǥ?Õ¤?Ô´??ʸ??NULL?ǥѥǥ??ó¥°¤??????? 574: @c COMMON 575: 576: @item A 577: @c EN 578: A text string, space padded. 579: @c JP 580: ?Æ¥????????????Ú¡????ǥѥǥ??ó¥°¤??????? 581: @c COMMON 582: 583: @item Z 584: @c EN 585: A null terminated (ASCIZ) string, null padded. 586: @c JP 587: NULL??ü(ASCIZ)ʸ??NULL?ǥѥǥ??ó¥°¤??????? 588: @c COMMON 589: 590: @item b 591: @c EN 592: A bit string (ascending bit order inside each byte). 593: @c JP 594: ?ӥå??????줾???Ð¥??Ȥˤ??????åȥ???????Ͼ???? 595: @c COMMON 596: 597: @item B 598: @c EN 599: A bit string (descending bit order inside each byte). 600: @c JP 601: ?ӥå??????줾???Ð¥??Ȥˤ??????åȥ???????Ϲ߽?? 602: @c COMMON 603: 604: @item h 605: @c EN 606: A hex string (low nybble first). 607: @c JP 608: 16?????㤤?˥֥뤬?)?? 609: @c COMMON 610: 611: @item H 612: @c EN 613: A hex string (high nybble first). 614: @c JP 615: 16?????⤤?˥֥뤬?)?? 616: @c COMMON 617: @end table 618: 619: @c EN 620: The object types: 621: @c JP 622: ???Ö¥??????È·?: 623: @c COMMON 624: 625: @table @code 626: @item c 627: @c EN 628: A signed 8bit integer. 629: @c JP 630: ?????8?ӥå????@c COMMON 631: 632: @item C 633: @c EN 634: An unsigned 8bit integer. 635: @c JP 636: ?????8?ӥå????@c COMMON 637: 638: @item s 639: @c EN 640: A signed short (16 bit) value. 641: @c JP 642: ?????16?ӥå????@c COMMON 643: 644: @item S 645: @c EN 646: An unsigned short (16 bit) value. 647: @c JP 648: ?????16?ӥå????@c COMMON 649: 650: @item i 651: @c EN 652: A signed integer (>= 32 bit) value. 653: @c JP 654: ???????? 32?ӥå??? 655: @c COMMON 656: 657: @item I 658: @c EN 659: An unsigned integer (>= 32 bit) value. 660: @c JP 661: ???????? 32?ӥå??? 662: @c COMMON 663: 664: @item l 665: @c EN 666: A signed long (32 bit) value. 667: @c JP 668: ?????long(32?ӥå??? 669: @c COMMON 670: 671: @item L 672: @c EN 673: An unsigned long (32 bit) value. 674: @c JP 675: ?????long(32?ӥå??? 676: @c COMMON 677: 678: @item n, n! 679: @c EN 680: An unsigned and signed short (16 bit) in "network" (big-endian) order. 681: @c JP 682: ?ͥåȥ?????????(?ӥå??????????????ʤ?/?????short(16?ӥå??? 683: @c COMMON 684: 685: @item N, N! 686: @c EN 687: An unsigned and signed long (32 bit) in "network" (big-endian) order. 688: @c JP 689: ?ͥåȥ?????????(?ӥå??????????????ʤ?/?????long(32?ӥå??? 690: @c COMMON 691: 692: @item v, v! 693: @c EN 694: An unsigned and signed short (16 bit) in "VAX" (little-endian) order. 695: @c JP 696: VAX???????(???륨???????????ʤ?/?????short(16?ӥå??? 697: @c COMMON 698: 699: @item V, V! 700: @c EN 701: An unsigned and signed long (32 bit) in "VAX" (little-endian) order. 702: @c JP 703: VAX???????(???륨???????????ʤ?/?????long(32?ӥå??? 704: @c COMMON 705: 706: @item q 707: @c EN 708: A signed quad (64 bit) value. 709: @c JP 710: ?????quad(64?ӥå??? 711: @c COMMON 712: 713: @item Q 714: @c EN 715: An unsigned quad (64 bit) value. 716: @c JP 717: ?????quad(64?ӥå??? 718: @c COMMON 719: 720: @item f 721: @c EN 722: A single-precision float in the native format. 723: @c JP 724: ??????float?? 725: @c COMMON 726: 727: @item d 728: @c EN 729: A double-precision float in the native format. 730: @c JP 731: ??????float?? 732: @c COMMON 733: 734: @item w 735: @c EN 736: A BER compressed integer. An unsigned integer in base 128, most 737: significant digit first, where the high bit is set on all but the 738: final (least significant) byte. Thus any size integer can be encoded, 739: but the encoding is efficient and small integers don't take up any 740: more space than they would in normal char/short/int encodings. 741: @c JP 742: BER???̤??줿??ô¡£¥Ù¡???128?ˤ??????????????Ǥ????ʷ夬 743: ?ǽ????⤤?ӥåȤ??Ǹ?(?????????Ð¥??Ȱʳ??Ë¥??åȤ????? 744: ???????äơ??ɤΤ褦??ç¤?????????󥳡??ɤǤ??뤬?? 745: ???󥳡??Ç¥??󥰤ϸ??Ç¡??????????̾?char/short/int 746: ???󥳡??Ç¥??󥰤ξ?????Í?????Ö¤????ʤ??? 747: @c COMMON 748: 749: @item x 750: @c EN 751: A null byte. 752: @c JP 753: NULL?Ð¥??È¡? 754: @c COMMON 755: 756: @item o 757: @c EN 758: An sexp, handled with @code{read} and @code{write}. 759: @c JP 760: S????@code{read}??code{write}?Ç°????ë¡£ 761: @c COMMON 762: 763: @end table 764: 765: @c EN 766: If the optional keyword @var{:output} is given that port is used 767: instead of the current output port. If @var{:to-string?} is given and 768: true, then pack accumulates and returns the output as a string. 769: