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