src/libstd/serialize.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Support code for encoding and decoding types.
  12
  13 /*
  14 Core encoding and decoding interfaces.
  15 */
  16
  17 #[forbid(deprecated_mode)];
  18 #[forbid(non_camel_case_types)];
  19
  20 use core::at_vec;
  21 use core::prelude::*;
  22 use core::vec;
  23
  24 pub trait Encoder {
  25     // Primitive types:
  26     fn emit_nil(&self);
  27     fn emit_uint(&self, v: uint);
  28     fn emit_u64(&self, v: u64);
  29     fn emit_u32(&self, v: u32);
  30     fn emit_u16(&self, v: u16);
  31     fn emit_u8(&self, v: u8);
  32     fn emit_int(&self, v: int);
  33     fn emit_i64(&self, v: i64);
  34     fn emit_i32(&self, v: i32);
  35     fn emit_i16(&self, v: i16);
  36     fn emit_i8(&self, v: i8);
  37     fn emit_bool(&self, v: bool);
  38     fn emit_float(&self, v: float);
  39     fn emit_f64(&self, v: f64);
  40     fn emit_f32(&self, v: f32);
  41     fn emit_char(&self, v: char);
  42     fn emit_borrowed_str(&self, v: &str);
  43     fn emit_owned_str(&self, v: &str);
  44     fn emit_managed_str(&self, v: &str);
  45
  46     // Compound types:
  47     fn emit_borrowed(&self, f: fn());
  48     fn emit_owned(&self, f: fn());
  49     fn emit_managed(&self, f: fn());
  50
  51     fn emit_enum(&self, name: &str, f: fn());
  52     fn emit_enum_variant(&self, v_name: &str, v_id: uint, sz: uint, f: fn());
  53     fn emit_enum_variant_arg(&self, idx: uint, f: fn());
  54
  55     fn emit_borrowed_vec(&self, len: uint, f: fn());
  56     fn emit_owned_vec(&self, len: uint, f: fn());
  57     fn emit_managed_vec(&self, len: uint, f: fn());
  58     fn emit_vec_elt(&self, idx: uint, f: fn());
  59
  60     fn emit_rec(&self, f: fn());
  61     fn emit_struct(&self, name: &str, _len: uint, f: fn());
  62     fn emit_field(&self, f_name: &str, f_idx: uint, f: fn());
  63
  64     fn emit_tup(&self, len: uint, f: fn());
  65     fn emit_tup_elt(&self, idx: uint, f: fn());
  66 }
  67
  68 pub trait Decoder {
  69     // Primitive types:
  70     fn read_nil(&self) -> ();
  71     fn read_uint(&self) -> uint;
  72     fn read_u64(&self) -> u64;
  73     fn read_u32(&self) -> u32;
  74     fn read_u16(&self) -> u16;
  75     fn read_u8(&self) -> u8;
  76     fn read_int(&self) -> int;
  77     fn read_i64(&self) -> i64;
  78     fn read_i32(&self) -> i32;
  79     fn read_i16(&self) -> i16;
  80     fn read_i8(&self) -> i8;
  81     fn read_bool(&self) -> bool;
  82     fn read_f64(&self) -> f64;
  83     fn read_f32(&self) -> f32;
  84     fn read_float(&self) -> float;
  85     fn read_char(&self) -> char;
  86     fn read_owned_str(&self) -> ~str;
  87     fn read_managed_str(&self) -> @str;
  88
  89     // Compound types:
  90     fn read_enum<T>(&self, name: &str, f: fn() -> T) -> T;
  91     fn read_enum_variant<T>(&self, f: fn(uint) -> T) -> T;
  92     fn read_enum_variant_arg<T>(&self, idx: uint, f: fn() -> T) -> T;
  93
  94     fn read_owned<T>(&self, f: fn() -> T) -> T;
  95     fn read_managed<T>(&self, f: fn() -> T) -> T;
  96
  97     fn read_owned_vec<T>(&self, f: fn(uint) -> T) -> T;
  98     fn read_managed_vec<T>(&self, f: fn(uint) -> T) -> T;
  99     fn read_vec_elt<T>(&self, idx: uint, f: fn() -> T) -> T;
 100
 101     fn read_rec<T>(&self, f: fn() -> T) -> T;
 102     fn read_struct<T>(&self, name: &str, _len: uint, f: fn() -> T) -> T;
 103     fn read_field<T>(&self, name: &str, idx: uint, f: fn() -> T) -> T;
 104
 105     fn read_tup<T>(&self, sz: uint, f: fn() -> T) -> T;
 106     fn read_tup_elt<T>(&self, idx: uint, f: fn() -> T) -> T;
 107 }
 108
 109 pub trait Encodable<S: Encoder> {
 110     fn encode(&self, s: &S);
 111 }
 112
 113 pub trait Decodable<D: Decoder> {
 114     static fn decode(&self, d: &D) -> self;
 115 }
 116
 117 pub impl<S: Encoder> uint: Encodable<S> {
 118     fn encode(&self, s: &S) { s.emit_uint(*self) }
 119 }
 120
 121 pub impl<D: Decoder> uint: Decodable<D> {
 122     static fn decode(&self, d: &D) -> uint {
 123         d.read_uint()
 124     }
 125 }
 126
 127 pub impl<S: Encoder> u8: Encodable<S> {
 128     fn encode(&self, s: &S) { s.emit_u8(*self) }
 129 }
 130
 131 pub impl<D: Decoder> u8: Decodable<D> {
 132     static fn decode(&self, d: &D) -> u8 {
 133         d.read_u8()
 134     }
 135 }
 136
 137 pub impl<S: Encoder> u16: Encodable<S> {
 138     fn encode(&self, s: &S) { s.emit_u16(*self) }
 139 }
 140
 141 pub impl<D: Decoder> u16: Decodable<D> {
 142     static fn decode(&self, d: &D) -> u16 {
 143         d.read_u16()
 144     }
 145 }
 146
 147 pub impl<S: Encoder> u32: Encodable<S> {
 148     fn encode(&self, s: &S) { s.emit_u32(*self) }
 149 }
 150
 151 pub impl<D: Decoder> u32: Decodable<D> {
 152     static fn decode(&self, d: &D) -> u32 {
 153         d.read_u32()
 154     }
 155 }
 156
 157 pub impl<S: Encoder> u64: Encodable<S> {
 158     fn encode(&self, s: &S) { s.emit_u64(*self) }
 159 }
 160
 161 pub impl<D: Decoder> u64: Decodable<D> {
 162     static fn decode(&self, d: &D) -> u64 {
 163         d.read_u64()
 164     }
 165 }
 166
 167 pub impl<S: Encoder> int: Encodable<S> {
 168     fn encode(&self, s: &S) { s.emit_int(*self) }
 169 }
 170
 171 pub impl<D: Decoder> int: Decodable<D> {
 172     static fn decode(&self, d: &D) -> int {
 173         d.read_int()
 174     }
 175 }
 176
 177 pub impl<S: Encoder> i8: Encodable<S> {
 178     fn encode(&self, s: &S) { s.emit_i8(*self) }
 179 }
 180
 181 pub impl<D: Decoder> i8: Decodable<D> {
 182     static fn decode(&self, d: &D) -> i8 {
 183         d.read_i8()
 184     }
 185 }
 186
 187 pub impl<S: Encoder> i16: Encodable<S> {
 188     fn encode(&self, s: &S) { s.emit_i16(*self) }
 189 }
 190
 191 pub impl<D: Decoder> i16: Decodable<D> {
 192     static fn decode(&self, d: &D) -> i16 {
 193         d.read_i16()
 194     }
 195 }
 196
 197 pub impl<S: Encoder> i32: Encodable<S> {
 198     fn encode(&self, s: &S) { s.emit_i32(*self) }
 199 }
 200
 201 pub impl<D: Decoder> i32: Decodable<D> {
 202     static fn decode(&self, d: &D) -> i32 {
 203         d.read_i32()
 204     }
 205 }
 206
 207 pub impl<S: Encoder> i64: Encodable<S> {
 208     fn encode(&self, s: &S) { s.emit_i64(*self) }
 209 }
 210
 211 pub impl<D: Decoder> i64: Decodable<D> {
 212     static fn decode(&self, d: &D) -> i64 {
 213         d.read_i64()
 214     }
 215 }
 216
 217 pub impl<S: Encoder> &str: Encodable<S> {
 218     fn encode(&self, s: &S) { s.emit_borrowed_str(*self) }
 219 }
 220
 221 pub impl<S: Encoder> ~str: Encodable<S> {
 222     fn encode(&self, s: &S) { s.emit_owned_str(*self) }
 223 }
 224
 225 pub impl<D: Decoder> ~str: Decodable<D> {
 226     static fn decode(&self, d: &D) -> ~str {
 227         d.read_owned_str()
 228     }
 229 }
 230
 231 pub impl<S: Encoder> @str: Encodable<S> {
 232     fn encode(&self, s: &S) { s.emit_managed_str(*self) }
 233 }
 234
 235 pub impl<D: Decoder> @str: Decodable<D> {
 236     static fn decode(&self, d: &D) -> @str {
 237         d.read_managed_str()
 238     }
 239 }
 240
 241 pub impl<S: Encoder> float: Encodable<S> {
 242     fn encode(&self, s: &S) { s.emit_float(*self) }
 243 }
 244
 245 pub impl<D: Decoder> float: Decodable<D> {
 246     static fn decode(&self, d: &D) -> float {
 247         d.read_float()
 248     }
 249 }
 250
 251 pub impl<S: Encoder> f32: Encodable<S> {
 252     fn encode(&self, s: &S) { s.emit_f32(*self) }
 253 }
 254
 255 pub impl<D: Decoder> f32: Decodable<D> {
 256     static fn decode(&self, d: &D) -> f32 {
 257         d.read_f32() }
 258 }
 259
 260 pub impl<S: Encoder> f64: Encodable<S> {
 261     fn encode(&self, s: &S) { s.emit_f64(*self) }
 262 }
 263
 264 pub impl<D: Decoder> f64: Decodable<D> {
 265     static fn decode(&self, d: &D) -> f64 {
 266         d.read_f64()
 267     }
 268 }
 269
 270 pub impl<S: Encoder> bool: Encodable<S> {
 271     fn encode(&self, s: &S) { s.emit_bool(*self) }
 272 }
 273
 274 pub impl<D: Decoder> bool: Decodable<D> {
 275     static fn decode(&self, d: &D) -> bool {
 276         d.read_bool()
 277     }
 278 }
 279
 280 pub impl<S: Encoder> (): Encodable<S> {
 281     fn encode(&self, s: &S) { s.emit_nil() }
 282 }
 283
 284 pub impl<D: Decoder> (): Decodable<D> {
 285     static fn decode(&self, d: &D) -> () {
 286         d.read_nil()
 287     }
 288 }
 289
 290 pub impl<S: Encoder, T: Encodable<S>> &T: Encodable<S> {
 291     fn encode(&self, s: &S) {
 292         s.emit_borrowed(|| (**self).encode(s))
 293     }
 294 }
 295
 296 pub impl<S: Encoder, T: Encodable<S>> ~T: Encodable<S> {
 297     fn encode(&self, s: &S) {
 298         s.emit_owned(|| (**self).encode(s))
 299     }
 300 }
 301
 302 pub impl<D: Decoder, T: Decodable<D>> ~T: Decodable<D> {
 303     static fn decode(&self, d: &D) -> ~T {
 304         d.read_owned(|| ~Decodable::decode(d))
 305     }
 306 }
 307
 308 pub impl<S: Encoder, T: Encodable<S>> @T: Encodable<S> {
 309     fn encode(&self, s: &S) {
 310         s.emit_managed(|| (**self).encode(s))
 311     }
 312 }
 313
 314 pub impl<D: Decoder, T: Decodable<D>> @T: Decodable<D> {
 315     static fn decode(&self, d: &D) -> @T {
 316         d.read_managed(|| @Decodable::decode(d))
 317     }
 318 }
 319
 320 pub impl<S: Encoder, T: Encodable<S>> &[T]: Encodable<S> {
 321     fn encode(&self, s: &S) {
 322         do s.emit_borrowed_vec(self.len()) {
 323             for self.eachi |i, e| {
 324                 s.emit_vec_elt(i, || e.encode(s))
 325             }
 326         }
 327     }
 328 }
 329
 330 pub impl<S: Encoder, T: Encodable<S>> ~[T]: Encodable<S> {
 331     fn encode(&self, s: &S) {
 332         do s.emit_owned_vec(self.len()) {
 333             for self.eachi |i, e| {
 334                 s.emit_vec_elt(i, || e.encode(s))
 335             }
 336         }
 337     }
 338 }
 339
 340 pub impl<D: Decoder, T: Decodable<D>> ~[T]: Decodable<D> {
 341     static fn decode(&self, d: &D) -> ~[T] {
 342         do d.read_owned_vec |len| {
 343             do vec::from_fn(len) |i| {
 344                 d.read_vec_elt(i, || Decodable::decode(d))
 345             }
 346         }
 347     }
 348 }
 349
 350 pub impl<S: Encoder, T: Encodable<S>> @[T]: Encodable<S> {
 351     fn encode(&self, s: &S) {
 352         do s.emit_managed_vec(self.len()) {
 353             for self.eachi |i, e| {
 354                 s.emit_vec_elt(i, || e.encode(s))
 355             }
 356         }
 357     }
 358 }
 359
 360 pub impl<D: Decoder, T: Decodable<D>> @[T]: Decodable<D> {
 361     static fn decode(&self, d: &D) -> @[T] {
 362         do d.read_managed_vec |len| {
 363             do at_vec::from_fn(len) |i| {
 364                 d.read_vec_elt(i, || Decodable::decode(d))
 365             }
 366         }
 367     }
 368 }
 369
 370 pub impl<S: Encoder, T: Encodable<S>> Option<T>: Encodable<S> {
 371     fn encode(&self, s: &S) {
 372         do s.emit_enum(~"option") {
 373             match *self {
 374               None => do s.emit_enum_variant(~"none", 0u, 0u) {
 375               },
 376
 377               Some(ref v) => do s.emit_enum_variant(~"some", 1u, 1u) {
 378                 s.emit_enum_variant_arg(0u, || v.encode(s))
 379               }
 380             }
 381         }
 382     }
 383 }
 384
 385 pub impl<D: Decoder, T: Decodable<D>> Option<T>: Decodable<D> {
 386     static fn decode(&self, d: &D) -> Option<T> {
 387         do d.read_enum(~"option") {
 388             do d.read_enum_variant |i| {
 389                 match i {
 390                   0 => None,
 391                   1 => Some(d.read_enum_variant_arg(
 392                       0u, || Decodable::decode(d))),
 393                   _ => fail(fmt!("Bad variant for option: %u", i))
 394                 }
 395             }
 396         }
 397     }
 398 }
 399
 400 pub impl<
 401     S: Encoder,
 402     T0: Encodable<S>,
 403     T1: Encodable<S>
 404 > (T0, T1): Encodable<S> {
 405     fn encode(&self, s: &S) {
 406         match *self {
 407             (ref t0, ref t1) => {
 408                 do s.emit_tup(2) {
 409                     s.emit_tup_elt(0, || t0.encode(s));
 410                     s.emit_tup_elt(1, || t1.encode(s));
 411                 }
 412             }
 413         }
 414     }
 415 }
 416
 417 pub impl<
 418     D: Decoder,
 419     T0: Decodable<D>,
 420     T1: Decodable<D>
 421 > (T0, T1): Decodable<D> {
 422     static fn decode(&self, d: &D) -> (T0, T1) {
 423         do d.read_tup(2) {
 424             (
 425                 d.read_tup_elt(0, || Decodable::decode(d)),
 426                 d.read_tup_elt(1, || Decodable::decode(d))
 427             )
 428         }
 429     }
 430 }
 431
 432 pub impl<
 433     S: Encoder,
 434     T0: Encodable<S>,
 435     T1: Encodable<S>,
 436     T2: Encodable<S>
 437 > (T0, T1, T2): Encodable<S> {
 438     fn encode(&self, s: &S) {
 439         match *self {
 440             (ref t0, ref t1, ref t2) => {
 441                 do s.emit_tup(3) {
 442                     s.emit_tup_elt(0, || t0.encode(s));
 443                     s.emit_tup_elt(1, || t1.encode(s));
 444                     s.emit_tup_elt(2, || t2.encode(s));
 445                 }
 446             }
 447         }
 448     }
 449 }
 450
 451 pub impl<
 452     D: Decoder,
 453     T0: Decodable<D>,
 454     T1: Decodable<D>,
 455     T2: Decodable<D>
 456 > (T0, T1, T2): Decodable<D> {
 457     static fn decode(&self, d: &D) -> (T0, T1, T2) {
 458         do d.read_tup(3) {
 459             (
 460                 d.read_tup_elt(0, || Decodable::decode(d)),
 461                 d.read_tup_elt(1, || Decodable::decode(d)),
 462                 d.read_tup_elt(2, || Decodable::decode(d))
 463             )
 464         }
 465     }
 466 }
 467
 468 pub impl<
 469     S: Encoder,
 470     T0: Encodable<S>,
 471     T1: Encodable<S>,
 472     T2: Encodable<S>,
 473     T3: Encodable<S>
 474 > (T0, T1, T2, T3): Encodable<S> {
 475     fn encode(&self, s: &S) {
 476         match *self {
 477             (ref t0, ref t1, ref t2, ref t3) => {
 478                 do s.emit_tup(4) {
 479                     s.emit_tup_elt(0, || t0.encode(s));
 480                     s.emit_tup_elt(1, || t1.encode(s));
 481                     s.emit_tup_elt(2, || t2.encode(s));
 482                     s.emit_tup_elt(3, || t3.encode(s));
 483                 }
 484             }
 485         }
 486     }
 487 }
 488
 489 pub impl<
 490     D: Decoder,
 491     T0: Decodable<D>,
 492     T1: Decodable<D>,
 493     T2: Decodable<D>,
 494     T3: Decodable<D>
 495 > (T0, T1, T2, T3): Decodable<D> {
 496     static fn decode(&self, d: &D) -> (T0, T1, T2, T3) {
 497         do d.read_tup(4) {
 498             (
 499                 d.read_tup_elt(0, || Decodable::decode(d)),
 500                 d.read_tup_elt(1, || Decodable::decode(d)),
 501                 d.read_tup_elt(2, || Decodable::decode(d)),
 502                 d.read_tup_elt(3, || Decodable::decode(d))
 503             )
 504         }
 505     }
 506 }
 507
 508 pub impl<
 509     S: Encoder,
 510     T0: Encodable<S>,
 511     T1: Encodable<S>,
 512     T2: Encodable<S>,
 513     T3: Encodable<S>,
 514     T4: Encodable<S>
 515 > (T0, T1, T2, T3, T4): Encodable<S> {
 516     fn encode(&self, s: &S) {
 517         match *self {
 518             (ref t0, ref t1, ref t2, ref t3, ref t4) => {
 519                 do s.emit_tup(5) {
 520                     s.emit_tup_elt(0, || t0.encode(s));
 521                     s.emit_tup_elt(1, || t1.encode(s));
 522                     s.emit_tup_elt(2, || t2.encode(s));
 523                     s.emit_tup_elt(3, || t3.encode(s));
 524                     s.emit_tup_elt(4, || t4.encode(s));
 525                 }
 526             }
 527         }
 528     }
 529 }
 530
 531 pub impl<
 532     D: Decoder,
 533     T0: Decodable<D>,
 534     T1: Decodable<D>,
 535     T2: Decodable<D>,
 536     T3: Decodable<D>,
 537     T4: Decodable<D>
 538 > (T0, T1, T2, T3, T4): Decodable<D> {
 539     static fn decode(&self, d: &D)
 540       -> (T0, T1, T2, T3, T4) {
 541         do d.read_tup(5) {
 542             (
 543                 d.read_tup_elt(0, || Decodable::decode(d)),
 544                 d.read_tup_elt(1, || Decodable::decode(d)),
 545                 d.read_tup_elt(2, || Decodable::decode(d)),
 546                 d.read_tup_elt(3, || Decodable::decode(d)),
 547                 d.read_tup_elt(4, || Decodable::decode(d))
 548             )
 549         }
 550     }
 551 }
 552
 553 // ___________________________________________________________________________
 554 // Helper routines
 555 //
 556 // In some cases, these should eventually be coded as traits.
 557
 558 pub trait EncoderHelpers {
 559     fn emit_from_vec<T>(&self, v: ~[T], f: fn(v: &T));
 560 }
 561
 562 pub impl<S: Encoder> S: EncoderHelpers {
 563     fn emit_from_vec<T>(&self, v: ~[T], f: fn(v: &T)) {
 564         do self.emit_owned_vec(v.len()) {
 565             for v.eachi |i, e| {
 566                 do self.emit_vec_elt(i) {
 567                     f(e)
 568                 }
 569             }
 570         }
 571     }
 572 }
 573
 574 pub trait DecoderHelpers {
 575     fn read_to_vec<T>(&self, f: fn() -> T) -> ~[T];
 576 }
 577
 578 pub impl<D: Decoder> D: DecoderHelpers {
 579     fn read_to_vec<T>(&self, f: fn() -> T) -> ~[T] {
 580         do self.read_owned_vec |len| {
 581             do vec::from_fn(len) |i| {
 582                 self.read_vec_elt(i, || f())
 583             }
 584         }
 585     }
 586 }