Merge sub-crates to the crossterm crate

[zrzka]

Goal

Provide all the features we do provide now through the crossterm crate only. Archive sub-crates and inform all users.

This does not include crossterm_winapi, which can still be used by anyone outside the crossterm ecosystem.

We will end up with three active repositories:

• crossterm-rs/crossterm
• crossterm-rs/crossterm-winapi
• crossterm-rs/examples

Motivation

There're dependencies between sub-crates we would like to avoid. Some of them are also using sys module, which needs to be public, but it shouldn't be. It's not part of the public API contract.

There're inconsistencies in examples, book, readmes, ... Some of the use crossterm crate with features, some of the use crossterm-* sub-crates, ... User can be puzzled what to use. In fact, it doesn't matter what the user will use, but the question is why we do provide two ways to achieve same thing.

And the last one is crossterm_utils, which is published as a crate, but it's not useful outside of them crossterm ecosystem.

Timeframe

There's no date set. I would like to focus on phase 1 now to finish the cleanup process I started. Once I finish it, I'll focus on bugs. Then, can be even distant future, discuss with Timon if it's the right time to merge.

Phase 1 - Cleanup

Improve & polish crates public (docs.rs & README) documentation (@zrzka):

• cursor - Internal refactoring and docs crossterm-cursor#2 & Sync docs style crossterm-cursor#7
• terminal - Internal refactoring and documentation crossterm-terminal#3
• screen - Refactoring and docs crossterm-screen#5
• style - Refactors crossterm-style#2 & Sync documentation style crossterm-style#3
• input - Refactor crossterm-input#3 & Improves the documentation crossterm-input#4
• utils - Deprecation note crossterm-utils#3
• crossterm - Docs update #269
• Publish new book with info that the book is deprecated & no longer maintained

This includes copying the book chapters to their respective lib.rs modules.

Phase 2 - Book removal

Then remove the book references from:

• cursor - Remove all references to the crossterm book crossterm-cursor#8
• terminal - Remove all references to the crossterm book crossterm-terminal#4
• screen - Remove all references to the crossterm book crossterm-screen#6
• style - Remove all references to the crossterm book crossterm-style#4
• input- Remove all references to the crossterm book crossterm-input#6
• utils- Remove all references to the crossterm book crossterm-utils#4
• crossterm (& the book itself) - Remove the crossterm book #270

Phase 3 - Bug fixing

Fix known bugs. The motivation here is to avoid archiving (GH) / deprecating (crates.io) buggy crates. Not all bugs can be fixed, especially those we don't know about, but rest should be fixed.

List of issues/tasks

Windows related

• Make read sync block for windows systems
  • Issue Make read sync block for windows systems #195
  • PR Don't return when not reading any input events crossterm-winapi#2
• Sync raw mode behavior
  • Issue Sync raw mode behavior #250
  • PR change console modes for raw screen crossterm-screen#3
• Sync grey/white color
  • Issue Windows 7 grey/white foreground swapped #263
  • PR Swapped INTENSITY crossterm-style#5

All platforms

• Add Commands: EnterAlternateScreen/LeaveAlternateScreen
  • PR Add Enter/LeaveAlternateScreen commands crossterm-screen#7
• Sync mouse button coordinates
  • Issue Synchronize mouse button events coordinates with the cursor #267
  • PR Mouse coordinates synchronized with the cursor crossterm-input#7
• Remove unsafe
  • Issue Remove unsafe globals #245
  • PRs Remove static mut crossterm-utils#5 & Replace RAW_MODE_ENABLED with is_raw_mode_enabled crossterm-cursor#9
• Reexport ResetColor
  • Issue crossterm_style's ResetColor is not re-exported in lib.rs #273
  • PR Exported ResetColor command #274

UNIX

• Async reader doesn't produce MouseEvents and cursor position is swallowed by the async reader
  • Issue Async reader doesn't produce MouseEvents #271
  • Issue Cursor position swallowed by input reader #199
  • Issue read_sync fails under LLDB debugging in Linux #253
  • PR Refactor unix (a)sync readers crossterm-input#9

Reminder

Just a check to go through the issues again if there isn't any new critical issue.

• Known bugs fixed and we're happy to proceed with phase 4

Phase 4 - Release

For every sub-crate:

• Add a note to the README that the crate is deprecated and no longer maintained.
• Add a note to the lib.rs that the crate is deprecated and no longer maintained.
• Bump patch in the Cargo.toml and add [badges] maintenance = { status = "deprecated" }
• Update CHANGELOG.md with the same info
• Release
• Archive on the GitHub

• crossterm_winapi
  • PR Release 0.2.2 crossterm-winapi#4
• crossterm_utils
  • PR Deprecated release crossterm-utils#7
• crossterm_screen
  • PR Deprecated release crossterm-screen#9
• crossterm_style
  • PR Deprecated release crossterm-style#6
• crossterm_input
  • PR Deprecated release crossterm-input#10
• crossterm_cursor
  • PR Deprecated release crossterm-cursor#11
• crossterm_terminal
  • PR Deprecated release crossterm-terminal#5

crossterm crate

• Release new crossterm crate with updated dependencies
  • PR Release 0.12 #277

By the end of this phase, all sub-crates are polished, hopefully, bug-free and marked as deprecated.

Phase 5 - Merge

For every sub-crate

Stop accepting sub-crates PRs (already archived) and copy the code to the crossterm crate. This step requires (for every sub-crate):

• copy the code to the respective crossterm module (crossterm_cursor -> cursor)
• feature gate the module and root re-exports
• fix docstring docs/examples (use crossterm_cursor -> crossterm)
• fix paths (crate will differ, etc.)
• update features (if there's a sub-crate dependency, like input requires screen, the input feature must enable screen feature as well)

• utils
• screen
• style
• input
• cursor
• terminal

crossterm crate

Once everything is merged, documentation is updated, etc.

• Add a note to the README that all the subcrates are deprecated/no longer maintained
• Merge the old command API docs & emphasis that it's recommended to use it
• Bump patch and release new crossterm crate version

Phase 6 - Inform users

• Discord
• Broot - Update crossterm dependencies Canop/broot#70

Not need to inform the following projects

All of them are using crossterm crate directly.

• Cursive - https://github.com/gyscos/Cursive
• TUI - https://github.com/fdehau/tui-rs
• Rust-sloth - https://github.com/jonathandturner/rust-sloth/tree/crossterm-port

[Canop]

Beautiful!
Well done.

[TimonPost]

Everyone that contributed to this version thanks! https://crates.io/crates/crossterm/0.12.1