mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Demanding what the argument layer is allowed to leave out.
//!
//! The argument layer lets these be absent so that publishing the contract
//! costs nothing, which makes this the place the requirement is really
//! enforced.

use crate::cli::schema::{DdlArgs, SearchArgs};
use crate::error::{Failure, Result};

/// Demands the table the argument layer is allowed to leave out.
///
/// # Errors
///
/// Returns a usage failure naming the flag that carries the table and showing
/// a form that carries it. The argument layer lets the table be absent so that
/// publishing the contract costs nothing, which makes this the place the
/// requirement is really enforced.
pub(super) fn table_of(named: Option<&String>) -> Result<String> {
    named.cloned().ok_or_else(|| {
        Failure::usage(
            "schema.table_missing",
            "this reading needs a table to read about",
        )
        .with_hint("name one with --table, as in `schema columns --table clientes`")
    })
}

/// Demands the pattern the argument layer is allowed to leave out.
///
/// # Errors
///
/// Returns a usage failure showing the form that carries the pattern, for the
/// reason given on [`table_of`].
/// The flag wins over the bare word, because the flag is the form the manual
/// publishes and a caller who wrote both meant the one they named.
pub(super) fn pattern_of(args: &SearchArgs) -> Result<String> {
    args.like
        .clone()
        .or_else(|| args.pattern.clone())
        .ok_or_else(|| {
            Failure::usage(
                "schema.pattern_missing",
                "the search needs a pattern to look for",
            )
            .with_hint("give one with --like, as in `schema search --like 'cliente%'`")
        })
}

/// Demands the object the argument layer is allowed to leave out.
///
/// # Errors
///
/// Returns a usage failure showing the form that carries the object, for the
/// reason given on [`table_of`].
pub(super) fn object_of(args: &DdlArgs) -> Result<String> {
    args.object.clone().ok_or_else(|| {
        Failure::usage(
            "schema.object_missing",
            "writing out a definition needs the object to write out",
        )
        .with_hint("name one as the first word, as in `schema ddl clientes`")
    })
}

/// The failure for a kind of object this product does not write out.
pub(super) fn unknown_kind(asked: &str) -> Failure {
    Failure::usage("schema.unknown_kind", format!("`{asked}`"))
        .with_detail("detail", format!("`{asked}`"))
        .with_detail("reason", "written")
        .with_detail(
            "kinds",
            "table, view, procedure, function, trigger, event, sequence",
        )
        .with_hint("the kinds are: table, view, procedure, function, trigger, event, sequence")
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Publishing the contract must cost nothing, so the table is optional to
    /// the argument layer. That moves the requirement here, where a reading
    /// with no table has to be refused with a code and told which flag carries
    /// it, rather than reaching the server without a subject.
    #[test]
    fn a_reading_without_a_table_is_refused_with_a_code() {
        let failure = table_of(None).expect_err("must refuse");

        assert_eq!(failure.code(), "schema.table_missing");
        assert_eq!(failure.exit_number().code(), 2);
        assert!(
            failure.hint().is_some_and(|hint| hint.contains("--table")),
            "the refusal names the flag that carries the table"
        );
    }

    /// A search with nothing to look for is refused for the same reason.
    #[test]
    fn a_search_without_a_pattern_is_refused_with_a_code() {
        let failure = pattern_of(&SearchArgs {
            pattern: None,
            like: None,
            kind: Vec::new(),
            detail: None,
        })
        .expect_err("must refuse");

        assert_eq!(failure.code(), "schema.pattern_missing");
        assert_eq!(failure.exit_number().code(), 2);
        assert!(failure.hint().is_some_and(|hint| hint.contains("--like")));
    }

    /// The pattern written as a flag is the one the search uses, and the bare
    /// word still works for a caller who learned it from this build.
    #[test]
    fn the_pattern_may_be_written_either_way_and_the_flag_wins() {
        let bare = SearchArgs {
            pattern: Some("bare%".to_owned()),
            like: None,
            kind: Vec::new(),
            detail: None,
        };
        assert_eq!(pattern_of(&bare).expect("a pattern"), "bare%");

        let both = SearchArgs {
            like: Some("flag%".to_owned()),
            ..bare
        };
        assert_eq!(pattern_of(&both).expect("a pattern"), "flag%");
    }

    /// So is asking for a definition without saying of what.
    #[test]
    fn a_definition_without_an_object_is_refused_with_a_code() {
        let failure = object_of(&DdlArgs {
            object: None,
            kind: None,
        })
        .expect_err("must refuse");

        assert_eq!(failure.code(), "schema.object_missing");
        assert_eq!(failure.exit_number().code(), 2);
        assert!(failure
            .hint()
            .is_some_and(|hint| hint.contains("schema ddl")));
    }
}