Is it still possible to create a Message with no title?

[Jayonas]

I recently updated my app from using annotate-snippets version 0.10.1 to version 0.11.1. Most of the API changes were pretty straight-forward, and I'm overall happy with its direction and new features. However, in the old version I was able to create a Snippet (now a Message) without a title, and I couldn't find a way to do that in the new version. Looks like Level::title is the only way to create a Message now, and even if I pass an empty string it still (unsurprisingly) renders the text for the Level. Did I miss this functionality elsewhere in the new API or is it actually gone? If it is gone, is there any chance that it can/will come back? I have situations in my app where I essentially render my own (more detailed) title prior to calling the annotate-snippets Renderer, so having the Renderer also render a title ends up being redundant.

[Muscraft]

Do you mind sharing a few examples of the custom titles?

[epage]

To clarify, it would help to understand your use case so we can better understand what people are trying to accomplish to see if there are holes in the design that need filling (or if we filled it and we need to better document it!).

[Jayonas]

Yup, sure. My custom title basically displays the source chain for the error. I have it behind a verbosity flag, though, so at normal verbosity I just use the title that annotate-snippets provides, and when the verbosity is increased I (want to) replace that default title with my own expanded source chain.

For example, with the normal default title:

error: invalid digit found in string
  --> data/config/full-test.xml:1:1
   |
 1 | [...]

And with the expanded/custom source chain title (including the redundant default title from annotate-snippets):

error:   a config operation failed
because: failed to read/write XML data
because: the XML is invalid for node: element 'settings'
because: the XML is invalid for node: element 'palette'
because: the XML is invalid for node: element 'color'
because: XML element 'color' has an invalid value for attribute 'col'
because: invalid digit found in string
error: invalid digit found in string
  --> data/config/full-test.xml:1:1
   |
 1 | [...]

In relation to the default title, my custom title basically inserts a bunch of stuff in between "error" (or whatever Level) and the error message. So the default title is fully redundant when my custom title is displayed.

Thanks for your consideration.

[epage]

What is the problem with including all of that in the title itself?

[Jayonas]

Well, I'm a little embarrassed to say that I think the only problem is that I didn't think of it. It's not necessarily obvious to throw multiple lines of text into the title, and it's also not necessarily obvious that I could re-style it in any way that I need, and yet I've basically done both of those things before in other circumstances, so I'm really not sure why I didn't think to try that. I guess I was probably just stuck in the mindset of mechanically updating my code to match the new API shape, and waiting to confirm that this functionality was gone before I started exploring other ways to deal with it.

Now that you've got me thinking about it, I can't think of any reasons up front that it wouldn't work. The only case that I can think of that would be problematic is if I had wanted to remove the Level text entirely, but I don't want to do that; in fact, my case is a little easier because I still want the Level text at the very beginning of the title.

It's going take a little bit of re-arranging for me to implement that, but I'll just close this issue now on the assumption that it will work out fine; I can always re-open if it turns out otherwise. Thanks for your help! Next time I'll consult more extensively with my rubber duck before I post.

[epage]

Well, you had a couple things going against you

• It is called "title" which implies a single line. Would something like "header" better describe the role?
• The idea of APIs accepting styled text and then adapting that when writing out to a stream is a relatively new CLI API pattern that I started with clap and have been slowly expanding to other APIs. If there are things we can do to make support for that clearer in the API, that could likely help people in the future.

[Jayonas]

Yeah, I do think that "header" would be an improvement over "title", both for that reason and because it's nicely symmetric with the already used "footer". Though if we're talking about the name of the Level method which creates a Message, I would honestly rather it be called "message". Naming it after its parameter ("title" or "header") makes me think that it's a builder method that applies a title (or header) to the Level, which is completely not what it does. It's much more intuitive for me when constructor methods are named after the thing they construct (unless they construct Self, in which case some variant of "new" or "from"). So I'd personally name that method "message" and call its parameter "header".

Regarding the APIs accepting styled text -- I'm surprised to learn that they might not have at one point. Does that mean you used to do extra work to strip styling out of the provided string before using it? I already pass styled text for annotations (which is one reason I feel silly for not thinking about passing it for titles, though I think the newlines tripped me up more than the styling) and would have been pretty surprised if that hadn't worked.