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