src/libfmt_macros/lib.rs

   1 // Copyright 2013 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 //! Macro support for format strings
  12 //!
  13 //! These structures are used when parsing format strings for the compiler.
  14 //! Parsing does not happen at runtime: structures of `std::fmt::rt` are
  15 //! generated instead.
  16
  17 #![crate_name = "fmt_macros"]
  18 #![experimental]
  19 #![crate_type = "rlib"]
  20 #![crate_type = "dylib"]
  21 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
  22        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
  23        html_root_url = "http://doc.rust-lang.org/nightly/",
  24        html_playground_url = "http://play.rust-lang.org/")]
  25
  26 #![feature(macro_rules, globs, slicing_syntax)]
  27 #![feature(associated_types)]
  28
  29 pub use self::Piece::*;
  30 pub use self::Position::*;
  31 pub use self::Alignment::*;
  32 pub use self::Flag::*;
  33 pub use self::Count::*;
  34
  35 use std::str;
  36 use std::string;
  37
  38 /// A piece is a portion of the format string which represents the next part
  39 /// to emit. These are emitted as a stream by the `Parser` class.
  40 #[derive(Copy, PartialEq)]
  41 pub enum Piece<'a> {
  42     /// A literal string which should directly be emitted
  43     String(&'a str),
  44     /// This describes that formatting should process the next argument (as
  45     /// specified inside) for emission.
  46     NextArgument(Argument<'a>),
  47 }
  48
  49 /// Representation of an argument specification.
  50 #[derive(Copy, PartialEq)]
  51 pub struct Argument<'a> {
  52     /// Where to find this argument
  53     pub position: Position<'a>,
  54     /// How to format the argument
  55     pub format: FormatSpec<'a>,
  56 }
  57
  58 /// Specification for the formatting of an argument in the format string.
  59 #[derive(Copy, PartialEq)]
  60 pub struct FormatSpec<'a> {
  61     /// Optionally specified character to fill alignment with
  62     pub fill: Option<char>,
  63     /// Optionally specified alignment
  64     pub align: Alignment,
  65     /// Packed version of various flags provided
  66     pub flags: uint,
  67     /// The integer precision to use
  68     pub precision: Count<'a>,
  69     /// The string width requested for the resulting format
  70     pub width: Count<'a>,
  71     /// The descriptor string representing the name of the format desired for
  72     /// this argument, this can be empty or any number of characters, although
  73     /// it is required to be one word.
  74     pub ty: &'a str
  75 }
  76
  77 /// Enum describing where an argument for a format can be located.
  78 #[derive(Copy, PartialEq)]
  79 pub enum Position<'a> {
  80     /// The argument will be in the next position. This is the default.
  81     ArgumentNext,
  82     /// The argument is located at a specific index.
  83     ArgumentIs(uint),
  84     /// The argument has a name.
  85     ArgumentNamed(&'a str),
  86 }
  87
  88 /// Enum of alignments which are supported.
  89 #[derive(Copy, PartialEq)]
  90 pub enum Alignment {
  91     /// The value will be aligned to the left.
  92     AlignLeft,
  93     /// The value will be aligned to the right.
  94     AlignRight,
  95     /// The value will be aligned in the center.
  96     AlignCenter,
  97     /// The value will take on a default alignment.
  98     AlignUnknown,
  99 }
 100
 101 /// Various flags which can be applied to format strings. The meaning of these
 102 /// flags is defined by the formatters themselves.
 103 #[derive(Copy, PartialEq)]
 104 pub enum Flag {
 105     /// A `+` will be used to denote positive numbers.
 106     FlagSignPlus,
 107     /// A `-` will be used to denote negative numbers. This is the default.
 108     FlagSignMinus,
 109     /// An alternate form will be used for the value. In the case of numbers,
 110     /// this means that the number will be prefixed with the supplied string.
 111     FlagAlternate,
 112     /// For numbers, this means that the number will be padded with zeroes,
 113     /// and the sign (`+` or `-`) will precede them.
 114     FlagSignAwareZeroPad,
 115 }
 116
 117 /// A count is used for the precision and width parameters of an integer, and
 118 /// can reference either an argument or a literal integer.
 119 #[derive(Copy, PartialEq)]
 120 pub enum Count<'a> {
 121     /// The count is specified explicitly.
 122     CountIs(uint),
 123     /// The count is specified by the argument with the given name.
 124     CountIsName(&'a str),
 125     /// The count is specified by the argument at the given index.
 126     CountIsParam(uint),
 127     /// The count is specified by the next parameter.
 128     CountIsNextParam,
 129     /// The count is implied and cannot be explicitly specified.
 130     CountImplied,
 131 }
 132
 133 /// The parser structure for interpreting the input format string. This is
 134 /// modelled as an iterator over `Piece` structures to form a stream of tokens
 135 /// being output.
 136 ///
 137 /// This is a recursive-descent parser for the sake of simplicity, and if
 138 /// necessary there's probably lots of room for improvement performance-wise.
 139 pub struct Parser<'a> {
 140     input: &'a str,
 141     cur: str::CharIndices<'a>,
 142     /// Error messages accumulated during parsing
 143     pub errors: Vec<string::String>,
 144 }
 145
 146 impl<'a> Iterator for Parser<'a> {
 147     type Item = Piece<'a>;
 148
 149     fn next(&mut self) -> Option<Piece<'a>> {
 150         match self.cur.clone().next() {
 151             Some((pos, '{')) => {
 152                 self.cur.next();
 153                 if self.consume('{') {
 154                     Some(String(self.string(pos + 1)))
 155                 } else {
 156                     let ret = Some(NextArgument(self.argument()));
 157                     self.must_consume('}');
 158                     ret
 159                 }
 160             }
 161             Some((pos, '}')) => {
 162                 self.cur.next();
 163                 if self.consume('}') {
 164                     Some(String(self.string(pos + 1)))
 165                 } else {
 166                     self.err("unmatched `}` found");
 167                     None
 168                 }
 169             }
 170             Some((pos, _)) => { Some(String(self.string(pos))) }
 171             None => None
 172         }
 173     }
 174 }
 175
 176 impl<'a> Parser<'a> {
 177     /// Creates a new parser for the given format string
 178     pub fn new(s: &'a str) -> Parser<'a> {
 179         Parser {
 180             input: s,
 181             cur: s.char_indices(),
 182             errors: vec!(),
 183         }
 184     }
 185
 186     /// Notifies of an error. The message doesn't actually need to be of type
 187     /// String, but I think it does when this eventually uses conditions so it
 188     /// might as well start using it now.
 189     fn err(&mut self, msg: &str) {
 190         self.errors.push(msg.to_string());
 191     }
 192
 193     /// Optionally consumes the specified character. If the character is not at
 194     /// the current position, then the current iterator isn't moved and false is
 195     /// returned, otherwise the character is consumed and true is returned.
 196     fn consume(&mut self, c: char) -> bool {
 197         match self.cur.clone().next() {
 198             Some((_, maybe)) if c == maybe => {
 199                 self.cur.next();
 200                 true
 201             }
 202             Some(..) | None => false,
 203         }
 204     }
 205
 206     /// Forces consumption of the specified character. If the character is not
 207     /// found, an error is emitted.
 208     fn must_consume(&mut self, c: char) {
 209         self.ws();
 210         match self.cur.clone().next() {
 211             Some((_, maybe)) if c == maybe => {
 212                 self.cur.next();
 213             }
 214             Some((_, other)) => {
 215                 self.err(format!("expected `{}`, found `{}`", c, other)[]);
 216             }
 217             None => {
 218                 self.err(format!("expected `{}` but string was terminated",
 219                                  c)[]);
 220             }
 221         }
 222     }
 223
 224     /// Consumes all whitespace characters until the first non-whitespace
 225     /// character
 226     fn ws(&mut self) {
 227         loop {
 228             match self.cur.clone().next() {
 229                 Some((_, c)) if c.is_whitespace() => { self.cur.next(); }
 230                 Some(..) | None => { return }
 231             }
 232         }
 233     }
 234
 235     /// Parses all of a string which is to be considered a "raw literal" in a
 236     /// format string. This is everything outside of the braces.
 237     fn string(&mut self, start: uint) -> &'a str {
 238         loop {
 239             // we may not consume the character, so clone the iterator
 240             match self.cur.clone().next() {
 241                 Some((pos, '}')) | Some((pos, '{')) => {
 242                     return self.input[start..pos];
 243                 }
 244                 Some(..) => { self.cur.next(); }
 245                 None => {
 246                     self.cur.next();
 247                     return self.input[start..self.input.len()];
 248                 }
 249             }
 250         }
 251     }
 252
 253     /// Parses an Argument structure, or what's contained within braces inside
 254     /// the format string
 255     fn argument(&mut self) -> Argument<'a> {
 256         Argument {
 257             position: self.position(),
 258             format: self.format(),
 259         }
 260     }
 261
 262     /// Parses a positional argument for a format. This could either be an
 263     /// integer index of an argument, a named argument, or a blank string.
 264     fn position(&mut self) -> Position<'a> {
 265         match self.integer() {
 266             Some(i) => { ArgumentIs(i) }
 267             None => {
 268                 match self.cur.clone().next() {
 269                     Some((_, c)) if c.is_alphabetic() => {
 270                         ArgumentNamed(self.word())
 271                     }
 272                     _ => ArgumentNext
 273                 }
 274             }
 275         }
 276     }
 277
 278     /// Parses a format specifier at the current position, returning all of the
 279     /// relevant information in the FormatSpec struct.
 280     fn format(&mut self) -> FormatSpec<'a> {
 281         let mut spec = FormatSpec {
 282             fill: None,
 283             align: AlignUnknown,
 284             flags: 0,
 285             precision: CountImplied,
 286             width: CountImplied,
 287             ty: self.input[0..0],
 288         };
 289         if !self.consume(':') { return spec }
 290
 291         // fill character
 292         match self.cur.clone().next() {
 293             Some((_, c)) => {
 294                 match self.cur.clone().skip(1).next() {
 295                     Some((_, '>')) | Some((_, '<')) | Some((_, '^')) => {
 296                         spec.fill = Some(c);
 297                         self.cur.next();
 298                     }
 299                     Some(..) | None => {}
 300                 }
 301             }
 302             None => {}
 303         }
 304         // Alignment
 305         if self.consume('<') {
 306             spec.align = AlignLeft;
 307         } else if self.consume('>') {
 308             spec.align = AlignRight;
 309         } else if self.consume('^') {
 310             spec.align = AlignCenter;
 311         }
 312         // Sign flags
 313         if self.consume('+') {
 314             spec.flags |= 1 << (FlagSignPlus as uint);
 315         } else if self.consume('-') {
 316             spec.flags |= 1 << (FlagSignMinus as uint);
 317         }
 318         // Alternate marker
 319         if self.consume('#') {
 320             spec.flags |= 1 << (FlagAlternate as uint);
 321         }
 322         // Width and precision
 323         let mut havewidth = false;
 324         if self.consume('0') {
 325             // small ambiguity with '0$' as a format string. In theory this is a
 326             // '0' flag and then an ill-formatted format string with just a '$'
 327             // and no count, but this is better if we instead interpret this as
 328             // no '0' flag and '0$' as the width instead.
 329             if self.consume('$') {
 330                 spec.width = CountIsParam(0);
 331                 havewidth = true;
 332             } else {
 333                 spec.flags |= 1 << (FlagSignAwareZeroPad as uint);
 334             }
 335         }
 336         if !havewidth {
 337             spec.width = self.count();
 338         }
 339         if self.consume('.') {
 340             if self.consume('*') {
 341                 spec.precision = CountIsNextParam;
 342             } else {
 343                 spec.precision = self.count();
 344             }
 345         }
 346         // Finally the actual format specifier
 347         if self.consume('?') {
 348             spec.ty = "?";
 349         } else {
 350             spec.ty = self.word();
 351         }
 352         return spec;
 353     }
 354
 355     /// Parses a Count parameter at the current position. This does not check
 356     /// for 'CountIsNextParam' because that is only used in precision, not
 357     /// width.
 358     fn count(&mut self) -> Count<'a> {
 359         match self.integer() {
 360             Some(i) => {
 361                 if self.consume('$') {
 362                     CountIsParam(i)
 363                 } else {
 364                     CountIs(i)
 365                 }
 366             }
 367             None => {
 368                 let tmp = self.cur.clone();
 369                 match self.word() {
 370                     word if word.len() > 0 => {
 371                         if self.consume('$') {
 372                             CountIsName(word)
 373                         } else {
 374                             self.cur = tmp;
 375                             CountImplied
 376                         }
 377                     }
 378                     _ => {
 379                         self.cur = tmp;
 380                         CountImplied
 381                     }
 382                 }
 383             }
 384         }
 385     }
 386
 387     /// Parses a word starting at the current position. A word is considered to
 388     /// be an alphabetic character followed by any number of alphanumeric
 389     /// characters.
 390     fn word(&mut self) -> &'a str {
 391         let start = match self.cur.clone().next() {
 392             Some((pos, c)) if c.is_xid_start() => {
 393                 self.cur.next();
 394                 pos
 395             }
 396             Some(..) | None => { return self.input[0..0]; }
 397         };
 398         let mut end;
 399         loop {
 400             match self.cur.clone().next() {
 401                 Some((_, c)) if c.is_xid_continue() => {
 402                     self.cur.next();
 403                 }
 404                 Some((pos, _)) => { end = pos; break }
 405                 None => { end = self.input.len(); break }
 406             }
 407         }
 408         self.input[start..end]
 409     }
 410
 411     /// Optionally parses an integer at the current position. This doesn't deal
 412     /// with overflow at all, it's just accumulating digits.
 413     fn integer(&mut self) -> Option<uint> {
 414         let mut cur = 0;
 415         let mut found = false;
 416         loop {
 417             match self.cur.clone().next() {
 418                 Some((_, c)) => {
 419                     match c.to_digit(10) {
 420                         Some(i) => {
 421                             cur = cur * 10 + i;
 422                             found = true;
 423                             self.cur.next();
 424                         }
 425                         None => { break }
 426                     }
 427                 }
 428                 None => { break }
 429             }
 430         }
 431         if found {
 432             return Some(cur);
 433         } else {
 434             return None;
 435         }
 436     }
 437 }
 438
 439 #[cfg(test)]
 440 mod tests {
 441     use super::*;
 442
 443     fn same(fmt: &'static str, p: &[Piece<'static>]) {
 444         let mut parser = Parser::new(fmt);
 445         assert!(p == parser.collect::<Vec<Piece<'static>>>());
 446     }
 447
 448     fn fmtdflt() -> FormatSpec<'static> {
 449         return FormatSpec {
 450             fill: None,
 451             align: AlignUnknown,
 452             flags: 0,
 453             precision: CountImplied,
 454             width: CountImplied,
 455             ty: "",
 456         }
 457     }
 458
 459     fn musterr(s: &str) {
 460         let mut p = Parser::new(s);
 461         p.next();
 462         assert!(p.errors.len() != 0);
 463     }
 464
 465     #[test]
 466     fn simple() {
 467         same("asdf", &[String("asdf")]);
 468         same("a{{b", &[String("a"), String("{b")]);
 469         same("a}}b", &[String("a"), String("}b")]);
 470         same("a}}", &[String("a"), String("}")]);
 471         same("}}", &[String("}")]);
 472         same("\\}}", &[String("\\"), String("}")]);
 473     }
 474
 475     #[test] fn invalid01() { musterr("{") }
 476     #[test] fn invalid02() { musterr("}") }
 477     #[test] fn invalid04() { musterr("{3a}") }
 478     #[test] fn invalid05() { musterr("{:|}") }
 479     #[test] fn invalid06() { musterr("{:>>>}") }
 480
 481     #[test]
 482     fn format_nothing() {
 483         same("{}", &[NextArgument(Argument {
 484             position: ArgumentNext,
 485             format: fmtdflt(),
 486         })]);
 487     }
 488     #[test]
 489     fn format_position() {
 490         same("{3}", &[NextArgument(Argument {
 491             position: ArgumentIs(3),
 492             format: fmtdflt(),
 493         })]);
 494     }
 495     #[test]
 496     fn format_position_nothing_else() {
 497         same("{3:}", &[NextArgument(Argument {
 498             position: ArgumentIs(3),
 499             format: fmtdflt(),
 500         })]);
 501     }
 502     #[test]
 503     fn format_type() {
 504         same("{3:a}", &[NextArgument(Argument {
 505             position: ArgumentIs(3),
 506             format: FormatSpec {
 507                 fill: None,
 508                 align: AlignUnknown,
 509                 flags: 0,
 510                 precision: CountImplied,
 511                 width: CountImplied,
 512                 ty: "a",
 513             },
 514         })]);
 515     }
 516     #[test]
 517     fn format_align_fill() {
 518         same("{3:>}", &[NextArgument(Argument {
 519             position: ArgumentIs(3),
 520             format: FormatSpec {
 521                 fill: None,
 522                 align: AlignRight,
 523                 flags: 0,
 524                 precision: CountImplied,
 525                 width: CountImplied,
 526                 ty: "",
 527             },
 528         })]);
 529         same("{3:0<}", &[NextArgument(Argument {
 530             position: ArgumentIs(3),
 531             format: FormatSpec {
 532                 fill: Some('0'),
 533                 align: AlignLeft,
 534                 flags: 0,
 535                 precision: CountImplied,
 536                 width: CountImplied,
 537                 ty: "",
 538             },
 539         })]);
 540         same("{3:*<abcd}", &[NextArgument(Argument {
 541             position: ArgumentIs(3),
 542             format: FormatSpec {
 543                 fill: Some('*'),
 544                 align: AlignLeft,
 545                 flags: 0,
 546                 precision: CountImplied,
 547                 width: CountImplied,
 548                 ty: "abcd",
 549             },
 550         })]);
 551     }
 552     #[test]
 553     fn format_counts() {
 554         same("{:10s}", &[NextArgument(Argument {
 555             position: ArgumentNext,
 556             format: FormatSpec {
 557                 fill: None,
 558                 align: AlignUnknown,
 559                 flags: 0,
 560                 precision: CountImplied,
 561                 width: CountIs(10),
 562                 ty: "s",
 563             },
 564         })]);
 565         same("{:10$.10s}", &[NextArgument(Argument {
 566             position: ArgumentNext,
 567             format: FormatSpec {
 568                 fill: None,
 569                 align: AlignUnknown,
 570                 flags: 0,
 571                 precision: CountIs(10),
 572                 width: CountIsParam(10),
 573                 ty: "s",
 574             },
 575         })]);
 576         same("{:.*s}", &[NextArgument(Argument {
 577             position: ArgumentNext,
 578             format: FormatSpec {
 579                 fill: None,
 580                 align: AlignUnknown,
 581                 flags: 0,
 582                 precision: CountIsNextParam,
 583                 width: CountImplied,
 584                 ty: "s",
 585             },
 586         })]);
 587         same("{:.10$s}", &[NextArgument(Argument {
 588             position: ArgumentNext,
 589             format: FormatSpec {
 590                 fill: None,
 591                 align: AlignUnknown,
 592                 flags: 0,
 593                 precision: CountIsParam(10),
 594                 width: CountImplied,
 595                 ty: "s",
 596             },
 597         })]);
 598         same("{:a$.b$s}", &[NextArgument(Argument {
 599             position: ArgumentNext,
 600             format: FormatSpec {
 601                 fill: None,
 602                 align: AlignUnknown,
 603                 flags: 0,
 604                 precision: CountIsName("b"),
 605                 width: CountIsName("a"),
 606                 ty: "s",
 607             },
 608         })]);
 609     }
 610     #[test]
 611     fn format_flags() {
 612         same("{:-}", &[NextArgument(Argument {
 613             position: ArgumentNext,
 614             format: FormatSpec {
 615                 fill: None,
 616                 align: AlignUnknown,
 617                 flags: (1 << FlagSignMinus as uint),
 618                 precision: CountImplied,
 619                 width: CountImplied,
 620                 ty: "",
 621             },
 622         })]);
 623         same("{:+#}", &[NextArgument(Argument {
 624             position: ArgumentNext,
 625             format: FormatSpec {
 626                 fill: None,
 627                 align: AlignUnknown,
 628                 flags: (1 << FlagSignPlus as uint) | (1 << FlagAlternate as uint),
 629                 precision: CountImplied,
 630                 width: CountImplied,
 631                 ty: "",
 632             },
 633         })]);
 634     }
 635     #[test]
 636     fn format_mixture() {
 637         same("abcd {3:a} efg", &[String("abcd "), NextArgument(Argument {
 638             position: ArgumentIs(3),
 639             format: FormatSpec {
 640                 fill: None,
 641                 align: AlignUnknown,
 642                 flags: 0,
 643                 precision: CountImplied,
 644                 width: CountImplied,
 645                 ty: "a",
 646             },
 647         }), String(" efg")]);
 648     }
 649 }