improve config function consistency

[suaviloquence]

Fixes #764

Config structs (Check, GlobalConfig, PackageSelection) now adhere to the following conventions for setter methods:

• method is called set_[property]
• method signature is fn(&mut self, T) -> &mut Self

[suaviloquence]

Edited migration guide:

Migration Guide

Major changes

• Check::check_release takes a new &mut GlobalConfig parameter, and GlobalConfig now holds log level and color settings.

  • Change:

    let mut check = Check::new(rustdoc);
    check.with_packages(packages)
         .with_log_level(Some(log_level))
         .with_color_choice(Some(termcolor::ColorChoice::Always));
    let result = check.check_release();

  • To:

    let mut config = GlobalConfig::new()
       .set_level(Some(log_level));
    config.set_color_choice(true); // or set_{err,out)_color_choice for finer-grained control
    
    let mut check = Check::new(rustdoc);
    check.with_packages(packages);
    let result = check.check_release(&mut config);

• Set color choice in one of three ways:

  • Change:

    let choice: termcolor::ColorChoice = ...;
    config = config.set_color_choice(choice);

  • To: one of the three following options, depending on desired granularity
    1. Set global color choice for all crates using the anstream library:

       let choice: anstream::ColorChoice = ...;
       // set *before* creating `GlobalConfig` instance (if using default stdout/stderr)
       // or before calling `GlobalConfig::set_std{out,err}` (if configuring them)
       choice.write_global(); // configures `choice` for all crates using `anstream`

    2. Set whether to use colors for both stdout and stderr in the cargo-semver-checks library:

       let use_colors: bool = ...;
       config.set_color_choice(use_colors);

    3. Set whether to use colors for a specific stream in the cargo-semver-checks library:

       let use_colors_for_stderr: bool = ...;
       let use_colors_for_stdout: bool = ...;
       config.set_err_color_choice(use_colors_for_stderr);
       config.set_out_color_choice(use_colors_for_stdout);

• config structs (Check, GlobalConfig, PackageSelection) now have a consistent setter convention: pub fn set_[property](&mut self, prop: T) -> &mut Self:

  • note: this does not apply to Check::with_[...]_features() methods as they are toggles vs property setters.
  • Change:

    selection.with_excluded_packages(packages);
    check.with_selection(selection).with_all_features();

  • To:

    selection.set_excluded_packages(packages);
    check.set_package_selection(selection).with_all_features();

  • Change:

    config = config.set_level(level);

  • To:

    config.set_log_level(level); // now takes and returns &mut Self instead of owned Self

New features

• Users can configure the stdout and stderr streams for cargo-semver-checks to be different from default:

  let stderr: Box<dyn std::io::Write> = Box::new(stderr_buffer);
  config.set_stderr(stderr);

Minor changes

• #[must_use] added on GlobalConfig::std{err,out}
• GlobalConfig::shell_print takes an anstyle::Color instead of a termcolor::Color:
  • Change config.shell_print(status, message, termcolor::Color::Red, justified)
  • To config.shell_print(status, message, anstyle::Color::Ansi(anstyle::AnsiColor::Red, justified)
• To write colors to stdout/stderr, use writeln!(config.stdout(), "{}styled text", anstyle::Style::new().bold().[...]); instead of the termcolor API
• use GlobalConfig::{out,err}_color_choice() to query whether to print colors for the stdout/stderr stream instead of using GlobalConfig::is_err_tty as a heuristic
• GlobalConfig::std{out,err} returns an opaque impl Write + '_ type instead of a termcolor::StandardStream

[obi1kenobi]

Great, ship it 🚀