Skip to main content

bpaf/
error.rs

1use std::ops::Range;
2
3use crate::{
4    args::{Arg, State},
5    buffer::{Block, Color, Doc, Style, Token},
6    item::{Item, ShortLong},
7    meta_help::Metavar,
8    meta_youmean::{Suggestion, Variant},
9    Meta,
10};
11
12/// Unsuccessful command line parsing outcome, internal representation
13#[derive(Debug)]
14pub struct Error(pub(crate) Message);
15
16impl Error {
17    pub(crate) fn combine_with(self, other: Self) -> Self {
18        Error(self.0.combine_with(other.0))
19    }
20}
21
22#[derive(Debug)]
23pub(crate) enum Message {
24    // those can be caught ---------------------------------------------------------------
25    /// Tried to consume an env variable with no fallback, variable was not set
26    NoEnv(&'static str),
27
28    /// User specified an error message on some
29    ParseSome(&'static str),
30
31    /// User asked for parser to fail explicitly
32    ParseFail(&'static str),
33
34    /// pure_with failed to parse a value
35    PureFailed(String),
36
37    /// Expected one of those values
38    ///
39    /// Used internally to generate better error messages
40    Missing(Vec<MissingItem>),
41
42    // those cannot be caught-------------------------------------------------------------
43    /// Parsing failed and this is the final output
44    ParseFailure(ParseFailure),
45
46    /// Tried to consume a strict positional argument, value was present but was not strictly
47    /// positional
48    StrictPos(usize, Metavar),
49
50    /// Tried to consume a non-strict positional argument, but the value was strict
51    NonStrictPos(usize, Metavar),
52
53    /// Parser provided by user failed to parse a value
54    ParseFailed(Option<usize>, String),
55
56    /// Parser provided by user failed to validate a value
57    GuardFailed(Option<usize>, &'static str),
58
59    /// Argument requres a value but something else was passed,
60    /// required: --foo <BAR>
61    /// given: --foo --bar
62    ///        --foo -- bar
63    ///        --foo
64    NoArgument(usize, Metavar),
65
66    /// Parser is expected to consume all the things from the command line
67    /// this item will contain an index of the unconsumed value
68    Unconsumed(/* TODO - unused? */ usize),
69
70    /// argument is ambigoups - parser can accept it as both a set of flags and a short flag with no =
71    Ambiguity(usize, String),
72
73    /// Suggested fixes for typos or missing input
74    Suggestion(usize, Suggestion),
75
76    /// Two arguments are mutually exclusive
77    /// --release --dev
78    Conflict(/* winner */ usize, usize),
79
80    /// Expected one or more items in the scope, got someting else if any
81    Expected(Vec<Item>, Option<usize>),
82
83    /// Parameter is accepted but only once
84    OnlyOnce(/* winner */ usize, usize),
85}
86
87impl Message {
88    pub(crate) fn can_catch(&self) -> bool {
89        match self {
90            Message::NoEnv(_)
91            | Message::ParseSome(_)
92            | Message::ParseFail(_)
93            | Message::Missing(_)
94            | Message::PureFailed(_)
95            | Message::NonStrictPos(_, _) => true,
96            Message::StrictPos(_, _)
97            | Message::ParseFailed(_, _)
98            | Message::GuardFailed(_, _)
99            | Message::Unconsumed(_)
100            | Message::Ambiguity(_, _)
101            | Message::Suggestion(_, _)
102            | Message::Conflict(_, _)
103            | Message::ParseFailure(_)
104            | Message::Expected(_, _)
105            | Message::OnlyOnce(_, _)
106            | Message::NoArgument(_, _) => false,
107        }
108    }
109
110    /// A list of errors that `catch` can't catch
111    pub(crate) fn wrong_input(&self) -> bool {
112        matches!(
113            self,
114            Message::StrictPos(_, _)
115                | Message::NonStrictPos(_, _)
116                | Message::NoArgument(_, _)
117                | Message::Unconsumed(_)
118                | Message::Ambiguity(_, _)
119        )
120    }
121}
122
123/// Missing item in a context
124#[derive(Debug, Clone)]
125pub struct MissingItem {
126    /// Item that is missing
127    pub(crate) item: Item,
128    /// Position it is missing from - exact for positionals, earliest possible for flags
129    pub(crate) position: usize,
130    /// Range where search was performed, important for combinators that narrow the search scope
131    /// such as adjacent
132    pub(crate) scope: Range<usize>,
133}
134
135impl Message {
136    #[must_use]
137    pub(crate) fn combine_with(self, other: Self) -> Self {
138        #[allow(clippy::match_same_arms)]
139        match (self, other) {
140            // help output takes priority
141            (a @ Message::ParseFailure(_), _) => a,
142            (_, b @ Message::ParseFailure(_)) => b,
143
144            // combine missing elements
145            (Message::Missing(mut a), Message::Missing(mut b)) => {
146                a.append(&mut b);
147                Message::Missing(a)
148            }
149
150            // otherwise earliest wins
151            (a, b) => {
152                if a.can_catch() {
153                    b
154                } else {
155                    a
156                }
157            }
158        }
159    }
160}
161
162/// Unsuccessful command line parsing outcome, use it for unit tests
163///
164/// When [`OptionParser::run_inner`](crate::OptionParser::run_inner) produces `Err(ParseFailure)`
165/// it means that the parser couldn't produce the value it supposed to produce and the program
166/// should terminate.
167///
168/// If you are handling variants manually - `Stdout` contains formatted output and you can use any
169/// logging framework to produce the output, `Completion` should be printed to stdout unchanged -
170/// shell completion mechanism relies on that. In both cases application should exit with error
171/// code of 0. `Stderr` variant indicates a genuinly parsing error which should be printed to
172/// stderr or a logging framework of your choice as an error and the app should exit with error
173/// code of 1. [`ParseFailure::exit_code`] is a helper method that performs printing and produces
174/// the exit code to use.
175///
176/// For purposes of for unit testing for user parsers, you can consume it with
177/// [`ParseFailure::unwrap_stdout`] and [`ParseFailure::unwrap_stdout`] - both of which produce a
178/// an unformatted `String` that parser might produce if failure type is correct or panics
179/// otherwise.
180#[derive(Clone, Debug)]
181pub enum ParseFailure {
182    /// Print this to stdout and exit with success code
183    Stdout(Doc, bool),
184    /// This also goes to stdout with exit code of 0,
185    /// this cannot be Doc because completion needs more control about rendering
186    Completion(String),
187    /// Print this to stderr and exit with failure code
188    Stderr(Doc),
189}
190
191impl ParseFailure {
192    /// Returns the contained `stderr` values - for unit tests
193    ///
194    /// # Panics
195    ///
196    /// Panics if failure contains `stdout`
197    #[allow(clippy::must_use_candidate)]
198    #[track_caller]
199    pub fn unwrap_stderr(self) -> String {
200        match self {
201            Self::Stderr(err) => err.monochrome(true),
202            Self::Completion(..) | Self::Stdout(..) => panic!("not an stderr: {:?}", self),
203        }
204    }
205
206    /// Returns the contained `stdout` values - for unit tests
207    ///
208    /// # Panics
209    ///
210    /// Panics if failure contains `stderr`
211    #[allow(clippy::must_use_candidate)]
212    #[track_caller]
213    pub fn unwrap_stdout(self) -> String {
214        match self {
215            Self::Stdout(err, full) => err.monochrome(full),
216            Self::Completion(s) => s,
217            Self::Stderr(..) => panic!("not an stdout: {:?}", self),
218        }
219    }
220
221    /// Returns the exit code for the failure
222    #[allow(clippy::must_use_candidate)]
223    pub fn exit_code(self) -> i32 {
224        match self {
225            Self::Stdout(..) | Self::Completion(..) => 0,
226            Self::Stderr(..) => 1,
227        }
228    }
229
230    #[doc(hidden)]
231    #[deprecated = "Please use ParseFailure::print_message, with two s"]
232    pub fn print_mesage(&self, max_width: usize) {
233        self.print_message(max_width)
234    }
235
236    /// Prints a message to `stdout` or `stderr` appropriate to the failure.
237    pub fn print_message(&self, max_width: usize) {
238        let color = Color::default();
239        match self {
240            ParseFailure::Stdout(msg, full) => {
241                println!("{}", msg.render_console(*full, color, max_width));
242            }
243            ParseFailure::Completion(s) => {
244                print!("{}", s);
245            }
246            ParseFailure::Stderr(msg) => {
247                #[allow(unused_mut)]
248                let mut error;
249                #[cfg(not(feature = "color"))]
250                {
251                    error = "Error: ";
252                }
253
254                #[cfg(feature = "color")]
255                {
256                    error = String::new();
257                    color.push_str(Style::Invalid, &mut error, "Error: ");
258                }
259
260                eprintln!("{}{}", error, msg.render_console(true, color, max_width));
261            }
262        }
263    }
264}
265
266fn check_conflicts(args: &State) -> Option<Message> {
267    let (loser, winner) = args.conflict()?;
268    Some(Message::Conflict(winner, loser))
269}
270
271fn textual_part(args: &State, ix: Option<usize>) -> Option<std::borrow::Cow<'_, str>> {
272    match args.items.get(ix?)? {
273        Arg::Short(_, _, _) | Arg::Long(_, _, _) => None,
274        Arg::ArgWord(s) | Arg::Word(s) | Arg::PosWord(s) => Some(s.to_string_lossy()),
275    }
276}
277
278fn only_once(args: &State, cur: usize) -> Option<usize> {
279    if cur == 0 {
280        return None;
281    }
282    let mut iter = args.items[..cur].iter().rev();
283    let offset = match args.items.get(cur)? {
284        Arg::Short(s, _, _) => iter.position(|a| a.match_short(*s)),
285        Arg::Long(l, _, _) => iter.position(|a| a.match_long(l)),
286        Arg::ArgWord(_) | Arg::Word(_) | Arg::PosWord(_) => None,
287    };
288    Some(cur - offset? - 1)
289}
290
291impl Message {
292    #[allow(clippy::too_many_lines)] // it's a huge match with lots of simple cases
293    pub(crate) fn render(mut self, args: &State, meta: &Meta) -> ParseFailure {
294        // try to come up with a better error message for a few cases
295        match self {
296            Message::Unconsumed(ix) => {
297                if let Some(conflict) = check_conflicts(args) {
298                    self = conflict;
299                } else if let Some(prev_ix) = only_once(args, ix) {
300                    self = Message::OnlyOnce(prev_ix, ix);
301                } else if let Some((ix, suggestion)) = crate::meta_youmean::suggest(args, meta) {
302                    self = Message::Suggestion(ix, suggestion);
303                }
304            }
305            Message::Missing(xs) => {
306                self = summarize_missing(&xs, meta, args);
307            }
308            _ => {}
309        }
310
311        let mut doc = Doc::default();
312        match self {
313            // already rendered
314            Message::ParseFailure(f) => return f,
315
316            // this case is handled above
317            Message::Missing(_) => {
318                // this one is unreachable
319            }
320
321            // Error: --foo is not expected in this context
322            Message::Unconsumed(ix) => {
323                let item = &args.items[ix];
324                doc.token(Token::BlockStart(Block::TermRef));
325                doc.write(item, Style::Invalid);
326                doc.token(Token::BlockEnd(Block::TermRef));
327                doc.text(" is not expected in this context");
328            }
329
330            // Error: environment variable FOO is not set
331            Message::NoEnv(name) => {
332                doc.text("environment variable ");
333                doc.token(Token::BlockStart(Block::TermRef));
334                doc.invalid(name);
335                doc.token(Token::BlockEnd(Block::TermRef));
336                doc.text(" is not set");
337            }
338
339            // Error: FOO expected to be  in the right side of --
340            Message::StrictPos(_ix, metavar) => {
341                doc.text("expected ");
342                doc.token(Token::BlockStart(Block::TermRef));
343                doc.metavar(metavar);
344                doc.token(Token::BlockEnd(Block::TermRef));
345                doc.text(" to be on the right side of ");
346                doc.token(Token::BlockStart(Block::TermRef));
347                doc.literal("--");
348                doc.token(Token::BlockEnd(Block::TermRef));
349            }
350
351            // Error: FOO expected to be on the left side of --
352            Message::NonStrictPos(_ix, metavar) => {
353                doc.text("expected ");
354                doc.token(Token::BlockStart(Block::TermRef));
355                doc.metavar(metavar);
356                doc.token(Token::BlockEnd(Block::TermRef));
357                doc.text(" to be on the left side of ");
358                doc.token(Token::BlockStart(Block::TermRef));
359                doc.literal("--");
360                doc.token(Token::BlockEnd(Block::TermRef));
361            }
362
363            // Error: <message from some or fail>
364            Message::ParseSome(s) | Message::ParseFail(s) => {
365                doc.text(s);
366            }
367
368            // Error: couldn't parse FIELD: <FromStr message>
369            Message::ParseFailed(mix, s) => {
370                doc.text("couldn't parse");
371                if let Some(field) = textual_part(args, mix) {
372                    doc.text(" ");
373                    doc.token(Token::BlockStart(Block::TermRef));
374                    doc.invalid(&field);
375                    doc.token(Token::BlockEnd(Block::TermRef));
376                }
377                doc.text(": ");
378                doc.text(&s);
379            }
380
381            // Error: ( FIELD:  | check failed: ) <message from guard>
382            Message::GuardFailed(mix, s) => {
383                if let Some(field) = textual_part(args, mix) {
384                    doc.token(Token::BlockStart(Block::TermRef));
385                    doc.invalid(&field);
386                    doc.token(Token::BlockEnd(Block::TermRef));
387                    doc.text(": ");
388                } else {
389                    doc.text("check failed: ");
390                }
391                doc.text(s);
392            }
393
394            // Error: --foo requires an argument FOO, got a flag --bar, try --foo=-bar to use it as an argument
395            // Error: --foo requires an argument FOO
396            Message::NoArgument(x, mv) => match args.get(x + 1) {
397                Some(Arg::Short(_, _, os) | Arg::Long(_, _, os)) => {
398                    let arg = &args.items[x];
399                    let os = &os.to_string_lossy();
400
401                    doc.token(Token::BlockStart(Block::TermRef));
402                    doc.write(arg, Style::Literal);
403                    doc.token(Token::BlockEnd(Block::TermRef));
404                    doc.text(" requires an argument ");
405                    doc.token(Token::BlockStart(Block::TermRef));
406                    doc.metavar(mv);
407                    doc.token(Token::BlockEnd(Block::TermRef));
408                    doc.text(", got a flag ");
409                    doc.token(Token::BlockStart(Block::TermRef));
410                    doc.write(os, Style::Invalid);
411                    doc.token(Token::BlockEnd(Block::TermRef));
412                    doc.text(", try ");
413                    doc.token(Token::BlockStart(Block::TermRef));
414                    doc.write(arg, Style::Literal);
415                    doc.literal("=");
416                    doc.write(os, Style::Literal);
417                    doc.token(Token::BlockEnd(Block::TermRef));
418                    doc.text(" to use it as an argument");
419                }
420                // "Some" part of this branch is actually unreachable
421                Some(Arg::ArgWord(_) | Arg::Word(_) | Arg::PosWord(_)) | None => {
422                    let arg = &args.items[x];
423                    doc.token(Token::BlockStart(Block::TermRef));
424                    doc.write(arg, Style::Literal);
425                    doc.token(Token::BlockEnd(Block::TermRef));
426                    doc.text(" requires an argument ");
427                    doc.token(Token::BlockStart(Block::TermRef));
428                    doc.metavar(mv);
429                    doc.token(Token::BlockEnd(Block::TermRef));
430                }
431            },
432            // Error: <message from pure_with>
433            Message::PureFailed(s) => {
434                doc.text(&s);
435            }
436            // Error: app supports -f as both an option and an option-argument, try to split -foo
437            // into invididual options (-f -o ..) or use -f=oo syntax to disambiguate
438            Message::Ambiguity(ix, name) => {
439                let mut chars = name.chars();
440                let first = chars.next().unwrap();
441                let rest = chars.as_str();
442                let second = chars.next().unwrap();
443                let s = args.items[ix].os_str().to_str().unwrap();
444
445                if let Some(name) = args.path.first() {
446                    doc.literal(name);
447                    doc.text(" supports ");
448                } else {
449                    doc.text("app supports ");
450                }
451
452                doc.token(Token::BlockStart(Block::TermRef));
453                doc.literal("-");
454                doc.write_char(first, Style::Literal);
455                doc.token(Token::BlockEnd(Block::TermRef));
456                doc.text(" as both an option and an option-argument, try to split ");
457                doc.token(Token::BlockStart(Block::TermRef));
458                doc.write(s, Style::Literal);
459                doc.token(Token::BlockEnd(Block::TermRef));
460                doc.text(" into individual options (");
461                doc.literal("-");
462                doc.write_char(first, Style::Literal);
463                doc.literal(" -");
464                doc.write_char(second, Style::Literal);
465                doc.literal(" ..");
466                doc.text(") or use ");
467                doc.token(Token::BlockStart(Block::TermRef));
468                doc.literal("-");
469                doc.write_char(first, Style::Literal);
470                doc.literal("=");
471                doc.literal(rest);
472                doc.token(Token::BlockEnd(Block::TermRef));
473                doc.text(" syntax to disambiguate");
474            }
475            // Error: No such (flag|argument|command), did you mean  ...
476            Message::Suggestion(ix, suggestion) => {
477                let actual = &args.items[ix].to_string();
478                match suggestion {
479                    Suggestion::Variant(v) => {
480                        let ty = match &args.items[ix] {
481                            _ if actual.starts_with('-') => "flag",
482                            Arg::Short(_, _, _) | Arg::Long(_, _, _) => "flag",
483                            Arg::ArgWord(_) => "argument value",
484                            Arg::Word(_) | Arg::PosWord(_) => "command or positional",
485                        };
486
487                        doc.text("no such ");
488                        doc.text(ty);
489                        doc.text(": ");
490                        doc.token(Token::BlockStart(Block::TermRef));
491                        doc.invalid(actual);
492                        doc.token(Token::BlockEnd(Block::TermRef));
493                        doc.text(", did you mean ");
494                        doc.token(Token::BlockStart(Block::TermRef));
495
496                        match v {
497                            Variant::CommandLong(name) => doc.literal(name),
498                            Variant::Flag(ShortLong::Long(l) | ShortLong::Both(_, l)) => {
499                                doc.literal("--");
500                                doc.literal(l);
501                            }
502                            Variant::Flag(ShortLong::Short(s)) => {
503                                doc.literal("-");
504                                doc.write_char(s, Style::Literal);
505                            }
506                        };
507
508                        doc.token(Token::BlockEnd(Block::TermRef));
509                        doc.text("?");
510                    }
511                    Suggestion::MissingDash(name) => {
512                        doc.text("no such flag: ");
513                        doc.token(Token::BlockStart(Block::TermRef));
514                        doc.literal("-");
515                        doc.literal(name);
516                        doc.token(Token::BlockEnd(Block::TermRef));
517                        doc.text(" (with one dash), did you mean ");
518                        doc.token(Token::BlockStart(Block::TermRef));
519                        doc.literal("--");
520                        doc.literal(name);
521                        doc.token(Token::BlockEnd(Block::TermRef));
522                        doc.text("?");
523                    }
524                    Suggestion::ExtraDash(name) => {
525                        doc.text("no such flag: ");
526                        doc.token(Token::BlockStart(Block::TermRef));
527                        doc.literal("--");
528                        doc.write_char(name, Style::Literal);
529                        doc.token(Token::BlockEnd(Block::TermRef));
530                        doc.text(" (with two dashes), did you mean ");
531                        doc.token(Token::BlockStart(Block::TermRef));
532                        doc.literal("-");
533                        doc.write_char(name, Style::Literal);
534                        doc.token(Token::BlockEnd(Block::TermRef));
535                        doc.text("?");
536                    }
537                    Suggestion::Nested(x, v) => {
538                        let ty = match v {
539                            Variant::CommandLong(_) => "subcommand",
540                            Variant::Flag(_) => "flag",
541                        };
542                        doc.text(ty);
543                        doc.text(" ");
544                        doc.token(Token::BlockStart(Block::TermRef));
545                        doc.literal(actual);
546                        doc.token(Token::BlockEnd(Block::TermRef));
547                        doc.text(
548                            " is not valid in this context, did you mean to pass it to command ",
549                        );
550                        doc.token(Token::BlockStart(Block::TermRef));
551                        doc.literal(&x);
552                        doc.token(Token::BlockEnd(Block::TermRef));
553                        doc.text("?");
554                    }
555                }
556            }
557            // Error: Expected (no arguments|--foo), got ..., pass --help
558            Message::Expected(exp, actual) => {
559                doc.text("expected ");
560                match exp.len() {
561                    0 => {
562                        doc.text("no arguments");
563                    }
564                    1 => {
565                        doc.token(Token::BlockStart(Block::TermRef));
566                        doc.write_item(&exp[0]);
567                        doc.token(Token::BlockEnd(Block::TermRef));
568                    }
569                    2 => {
570                        doc.token(Token::BlockStart(Block::TermRef));
571                        doc.write_item(&exp[0]);
572                        doc.token(Token::BlockEnd(Block::TermRef));
573                        doc.text(" or ");
574                        doc.token(Token::BlockStart(Block::TermRef));
575                        doc.write_item(&exp[1]);
576                        doc.token(Token::BlockEnd(Block::TermRef));
577                    }
578                    _ => {
579                        doc.token(Token::BlockStart(Block::TermRef));
580                        doc.write_item(&exp[0]);
581                        doc.token(Token::BlockEnd(Block::TermRef));
582                        doc.text(", ");
583                        doc.token(Token::BlockStart(Block::TermRef));
584                        doc.write_item(&exp[1]);
585                        doc.token(Token::BlockEnd(Block::TermRef));
586                        doc.text(", or more");
587                    }
588                }
589                match actual {
590                    Some(actual) => {
591                        doc.text(", got ");
592                        doc.token(Token::BlockStart(Block::TermRef));
593                        doc.write(&args.items[actual], Style::Invalid);
594                        doc.token(Token::BlockEnd(Block::TermRef));
595                        doc.text(". Pass ");
596                    }
597                    None => {
598                        doc.text(", pass ");
599                    }
600                }
601                doc.token(Token::BlockStart(Block::TermRef));
602                doc.literal("--help");
603                doc.token(Token::BlockEnd(Block::TermRef));
604                doc.text(" for usage information");
605            }
606
607            // Error: --intel cannot be used at the same time as --att
608            Message::Conflict(winner, loser) => {
609                doc.token(Token::BlockStart(Block::TermRef));
610                doc.write(&args.items[loser], Style::Literal);
611                doc.token(Token::BlockEnd(Block::TermRef));
612                doc.text(" cannot be used at the same time as ");
613                doc.token(Token::BlockStart(Block::TermRef));
614                doc.write(&args.items[winner], Style::Literal);
615                doc.token(Token::BlockEnd(Block::TermRef));
616            }
617
618            // Error: argument FOO cannot be used multiple times in this context
619            Message::OnlyOnce(_winner, loser) => {
620                doc.text("argument ");
621                doc.token(Token::BlockStart(Block::TermRef));
622                doc.write(&args.items[loser], Style::Literal);
623                doc.token(Token::BlockEnd(Block::TermRef));
624                doc.text(" cannot be used multiple times in this context");
625            }
626        };
627
628        ParseFailure::Stderr(doc)
629    }
630}
631
632/// go over all the missing items, pick the left most scope
633pub(crate) fn summarize_missing(items: &[MissingItem], inner: &Meta, args: &State) -> Message {
634    // missing items can belong to different scopes, pick the best scope to work with
635    let best_item = match items
636        .iter()
637        .max_by_key(|item| (item.position, item.scope.start))
638    {
639        Some(x) => x,
640        None => return Message::ParseSome("parser requires an extra flag, argument or parameter, but its name is hidden by the author"),
641    };
642
643    let mut best_scope = best_item.scope.clone();
644
645    let mut saw_command = false;
646    let expected = items
647        .iter()
648        .filter_map(|i| {
649            let cmd = matches!(i.item, Item::Command { .. });
650            if i.scope == best_scope && !(saw_command && cmd) {
651                saw_command |= cmd;
652                Some(i.item.clone())
653            } else {
654                None
655            }
656        })
657        .collect::<Vec<_>>();
658
659    best_scope.start = best_scope.start.max(best_item.position);
660    let mut args = args.clone();
661    args.set_scope(best_scope);
662    if let Some((ix, _arg)) = args.items_iter().next() {
663        if let Some((ix, sugg)) = crate::meta_youmean::suggest(&args, inner) {
664            Message::Suggestion(ix, sugg)
665        } else {
666            Message::Expected(expected, Some(ix))
667        }
668    } else {
669        Message::Expected(expected, None)
670    }
671}
672
673/*
674#[inline(never)]
675/// the idea is to post some context for the error
676fn snip(buffer: &mut Buffer, args: &State, items: &[usize]) {
677    for ix in args.scope() {
678        buffer.write(ix, Style::Text);
679    }
680}
681*/