Add support for hyperlinks and other OSC codes

[mhelsley]

Add support for producing colorized/stylized hyperlinks, among a selection of other OS Control (OSC) codes such as setting the window title, application/window icon, and notifying the terminal about the current working directory. The main goal is to satisfy #6 while also supporting a few other very common OSC codes.

There has already been some discussion and a change proposed for handling hyperlinks in the dormant rust-ansi-term repo: (See: ogham#61) The above proposed change breaks the Copy trait for Style and would require changing downstream projects that rely on it.

These features aren't really about styling text so much as adding more information for the terminal emulator to present to the user either outside of the typical area for rendered terminal output or somewhat out-of-band with it.

So this change takes a different approach than taken in the referenced pull request.

An enum describing the supported OSC codes, which is not exposed outside the crate, is used to indicate that a Style has additional terminal prefix and suffix output control codes to take care of for hyperlinks, titles, etc. These let us keep the prefix/suffix handling consistent.

However rather than library users using these enums directly or calling externally visible functions on Style or Color struct, AnsiGenericString uses them to implement its hyperlink(), title(), etc. functions. These store the hyperlink "src" string, title, etc. within the
AnsiGenericString rather than in the Style.

Style remains Copy-able, and, since it already stores strings, AnsiGenericString traits are consistent with this choice. The locations of the functions better reflect what's happening because the supplied strings are not meant to be rendered inline with the ANSI-styled output.

The OSControl enum also nicely describes the subset of OSC codes the package currently supports.

[fdncred]

Thanks for this. I like your approach better. We want to stay away from breaking changes as much as possible. I'm wondering if FTCS should be added too? (maybe in a later PR)

[mhelsley]

Thanks for this. I like your approach better. We want to stay away from breaking changes as much as possible. I'm wondering if FTCS should be added too? (maybe in a later PR)

I think it can be implemented in the same way. I suppose whether it's a separate PR or not is a matter of taste. At what point do you want to break it up into multiple commits? Multiple PRs? For example, I could break up this single commit into one per enum added (first commit for the hyperlink, next commit introduces the window title, etc.) and submit them all in this PR. (happy to do that)

My sense is at some point separate PRs will be necessary though -- there are just too many OSC sequences to implement in one commit and/or PR. I chose these because they're a widely-supported subset of OSC escape codes to get started with and two of them (hyperlinks and window title) are of interest to me in another project.

I didn't know about FTCS and OSC 133 before you mentioned it so I did some digging and thought I'd put it here for future reference:

FTCS (which I guess stands for FinalTerm Control Sequence) uses OSC 133 (among others) to delineate portions of terminal output as either part of the prompt, part of the command exectued, or the command's output.

External references:

• iTerm description: https://iterm2.com/documentation-escape-codes.html
• A freedesktop.org terminal working group standard proposal for "Semantic Prompts": https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md

[fdncred]

At what point do you want to break it up into multiple commits?

I'm not picky. I prefer to let you decide because it depends on how long it takes. I wouldn't want a PR sitting waiting several weeks for something to get done when we can have several things added easily/quickly like this PR already does. But, if you'd prefer to put it all in one PR, I'm fine with that too. In the end, we squash and merge.

Yes, you found the right research links for FTCS, sorry I wasn't more verbose. We use FTCS (among others) in nushell. I was just kind of thinking that it may make it easier if nu-ansi-term had that built in. I'm not sure it'll make any big difference though.

You can see in the nushell repo, if you search for OSC, you'll find OCS 8 (links) and OSC 7 (title) as well as FTCS A, B, C, D (you'll have to search for 133; because I didn't label them with OSC).

[mhelsley]

Changes to the PR:

• fixed up the build failure with --all-features (optional serde features)
• fixed up the existing test failure
• added a bunch more tests for Style::title(), Style::icon(), and Style::cwd() by themselves and in combination with plain/styled strings joined using AnsiStrings.

I think the PR is ready for review.

[fdncred]

These tests seem pretty stubborn, the ones that keep failing. :)

[mhelsley]

That's odd. On my machine that assert is passing and one of the fixes I mentioned required changing the expected output from "...[4;..." to "...[04;...". At the moment I'm not seeing the cause of the problem but I'll keep looking.

[mhelsley]

That's odd. On my machine that assert is passing and one of the fixes I mentioned required changing the expected output from "...[4;..." to "...[04;...". At the moment I'm not seeing the cause of the problem but I'll keep looking.

Ok, found it more quickly than expected. It's the gnu_legacy feature that's different between my test run versus that CI run. I'll fix that in the new testcases and re-push soon.

[mhelsley]

OK, I believe I managed to address the issue. In the src/display.rs test module I converted the feature flag to a string fed into assert_eq!(..., format!(...[{L}4;...));

#[cfg(feature = "gnu_legacy")]
const L: &str = "0";
#[cfg(not(feature = "gnu_legacy"))]
const L: &str = "";

This seemed better than copy-pasting the expected strings and manually adjusting the expected output. It's a bit different than how I saw this solved elsewhere so I thought it'd be worth mentioning. Happy to change it if you prefer the other way.

[fdncred]

Looks like it failed again. We like to keep the code formatted with cargo fmt.

I converted the feature flag to a string

I'd prefer to have two asserts, one with gnu_legacy and one without it. For me, tests are not really about optimal coding, it's about understanding what is being tested and knowing what to do when it fails. So, I just think it would be easier to have something along the lines of

        // Assemble with link first
        let joined = AnsiStrings(&[link.clone(), after.clone()]).to_string();
        #[cfg(feature = "gnu_legacy")]
        assert_eq!(joined, format!("\x1B[04;34m\x1B]8;;https://example.com\x1B\\Link to example.com.\x1B]8;;\x1B\\\x1B[0m\x1B[32m After link.\x1B[0m"));
        #[cfg(not(feature = "gnu_legacy"))]
        assert_eq!(joined, format!("\x1B[4;34m\x1B]8;;https://example.com\x1B\\Link to example.com.\x1B]8;;\x1B\\\x1B[0m\x1B[32m After link.\x1B[0m"));

[sholderbach]

I agree with @fdncred that your proposed API is nicer from a compatibility/stability perspective than ogham#61.

With #5 we removed the transparent Deref that lets the styled types act transparently like a base &str but had some rather confusing behavior. So handling the OSC codes by directly writing into the string seems fine to me.

If you can resolve the tests, we are very happy to have this feature!

[mhelsley]

OK, I converted the asserts, dealt with all the clippy suggestions, and applied cargo fmt. Unless I'm misreading the example run output I think it should be good to go on my end at least.

[fdncred]

Thanks for this. Looks good!

[sholderbach]

It slipped through the cracks but adding this as a pub(crate) breaks the public API that previously allowed to construct Style directly (or to destructure it in totality).

See #46 for what we should do about this.

cc @mhelsley