//! "Slugs" used as part of on-disk filenames and other similar purposes

//!

//! Arti uses "slugs" as parts of filenames in many places.

//! Slugs are fixed or variable strings which either

//! designate the kind of a thing, or which of various things this is.

//!

//! Slugs have a restricted character set:

//! Lowercase ASCII alphanumerics, underscore, hyphen.

//! We may extend this to allow additional characters in the future,

//! but /, +, and . (the slug separators) will never be valid slug characters.

//! Additionally, : will never be a valid slug character,

//! because Windows does not allow colons in filenames[^1],

//!

//! Slugs may not be empty, and they may not start with a hyphen.

//!

//! Slugs can be concatenated to build file names.

//! When concatenating slugs to make filenames,

//! they should be separated using `/`, `+`, or `.`

//! ([`SLUG_SEPARATOR_CHARS`]).

//! Slugs should not be concatenated without separators (for security reasons).

//!

//! On Windows only, the following slugs are forbidden,

//! because of [absurd Windows filename behaviours](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file):

//! `con` `prn` `aux` `nul`

//! `com1` `com2` `com3` `com4` `com5` `com6` `com7` `com8` `com9` `com0`

//! `lpt1` `lpt2` `lpt3` `lpt4` `lpt5` `lpt6` `lpt7` `lpt8` `lpt9` `lpt0`.

//!

//! [^1]: <https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions>

pub mod timestamp;

use std::borrow::Borrow;

use std::ffi::OsStr;

use std::fmt::{self, Display};

use std::mem;

use std::ops::Deref;

use std::path::Path;

use paste::paste;

use serde::{Deserialize, Serialize};

use thiserror::Error;

#[cfg(target_family = "windows")]

pub use os::ForbiddenOnWindows;

/// An owned slug, checked for syntax

///

/// The syntax check can be relied on for safety/soundness.

// We adopt this rule so that eventually we could have AsRef<[std::ascii::Char]>, etc.

#[derive(Debug, Clone, Serialize, Deserialize)] //

#[derive(Eq, PartialEq, Ord, PartialOrd, Hash)] //

#[derive(derive_more::Display)]

#[serde(try_from = "String", into = "String")]

// Box<str> since we don't expect to change the size; that makes it 2 words rather than 3

// (But our public APIs are in terms of String.)

pub struct Slug(Box<str>);

/// A borrwed slug, checked for syntax

///

/// The syntax check can be relied on for safety/soundness.

#[derive(Debug, Serialize)] //

#[derive(Eq, PartialEq, Ord, PartialOrd, Hash)] //

#[derive(derive_more::Display)]

#[serde(transparent)]

#[repr(transparent)] // SAFETY: this attribute is needed for unsafe in new_unchecked

pub struct SlugRef(str);

/// Characters which are good to use to separate slugs

///

/// Guaranteed to never overlap with the valid slug character set.

///

/// We might expand this set, but not ever reduce it.

pub const SLUG_SEPARATOR_CHARS: &str = "/+.";

/// Error for an invalid slug

#[derive(Error, Debug, Clone, Eq, PartialEq, Hash)]

#[non_exhaustive]

pub enum BadSlug {

    /// Slug contains a forbidden character

    BadCharacter(char),

    /// Slug starts with a disallowed character

    BadFirstCharacter(char),

    /// An empty slug was supplied where a nonempty one is required

    EmptySlugNotAllowed,

    /// We are on Windows and the slug is one of the forbidden ones

    ///

    /// On platforms other than Windows, this variant is absent.

    #[cfg(target_family = "windows")]

    ForbiddenOnWindows(ForbiddenOnWindows),

}

/// Types which can perhaps be used as a slug

///

/// This is a trait implemented by `str`, `std::fmt::Arguments`,

/// and other implementors of `ToString`, for the convenience of call sites:

/// APIs can have functions taking an `&(impl TryIntoSlug + ?Sized)` or `&dyn TryIntoSlug`

/// and callers then don't need error-handling boilerplate.

///

/// Functions that take a `TryIntoSlug` will need to do a runtime syntax check.

pub trait TryIntoSlug {

    /// Convert `self` into a `Slug`, if it has the right syntax

    fn try_into_slug(&self) -> Result<Slug, BadSlug>;

}

impl<T: ToString + ?Sized> TryIntoSlug for T {

}

impl Slug {

    /// Make a Slug out of an owned `String`, if it has the correct syntax

        Ok(unsafe {

            // SAFETY: we check, and then call new_unchecked

        })

    /// Make a Slug out of an owned `String`, without checking the syntax

    ///

    /// # Safety

    ///

    /// It's the caller's responsibility to check the syntax of the input string.

}

impl SlugRef {

    /// Make a SlugRef out of a `str`, if it has the correct syntax

        Ok(unsafe {

            // SAFETY: we check, and then call new_unchecked

        })

    /// Make a SlugRef out of a `str`, without checking the syntax

    ///

    /// # Safety

    ///

    /// It's the caller's responsibility to check the syntax of the input string.

        unsafe {

            // SAFETY

            // SlugRef is repr(transparent).  So the alignment and memory layout

            // are the same, and the pointer metadata is the same too.

            // The lifetimes is correct by construction.

            //

            // We do this, rather than `struct SlugRef<'r>(&'r str)`,

            // because that way we couldn't impl Deref.

        }

    /// Make an owned `Slug`

        unsafe {

            // SAFETY: self is a SlugRef so our syntax is right

        }

}

impl TryFrom<String> for Slug {

    type Error = BadSlug;

}

impl From<Slug> for String {

}

impl<'s> TryFrom<&'s str> for &'s SlugRef {

    type Error = BadSlug;

}

impl Deref for Slug {

    type Target = SlugRef;

        unsafe {

            // SAFETY: self is a Slug so our syntax is right

        }

}

impl Borrow<SlugRef> for Slug {

}

impl Borrow<str> for Slug {

}

impl ToOwned for SlugRef {

    type Owned = Slug;

}

/// Implement `fn as_...(&self) -> ...` and `AsRef`

macro_rules! impl_as_with_inherent { { $ty:ident } => { paste!{

    impl SlugRef {

    }

    impl_as_ref!($ty);

} } }

/// Implement `AsRef`

macro_rules! impl_as_ref { { $ty:ty } => { paste!{

    }

} } }

impl_as_with_inherent!(str);

impl_as_with_inherent!(Path);

impl_as_ref!(OsStr);

impl_as_ref!([u8]);

/// Check the string `s` to see if it would be valid as a slug

///

/// This is a low-level method for special cases.

/// Usually, use [`Slug::new`] etc.

//

// SAFETY

// This function checks the syntax, and is relied on by unsafe code

#[allow(clippy::if_same_then_else)] // clippy objects to the repeated Ok(())

    // Slugs are not allowed to start with a hyphen.

    // check legal character set

        } else {

    }

impl Display for BadSlug {

            }

                )

            }

            BadSlug::EmptySlugNotAllowed => {

            }

            #[cfg(target_family = "windows")]

            BadSlug::ForbiddenOnWindows(e) => os::fmt_error(e, f),

        }

}

/// Forbidden slug support for Windows

#[cfg(target_family = "windows")]

mod os {

    use super::*;

    /// A slug which is forbidden because we are on Windows (as found in an invalid slug error)

    ///

    /// This type is available only on Windows platforms.

    //

    // Double reference so that BadSlug has to contain only one word, not two

    pub type ForbiddenOnWindows = &'static &'static str;

    /// The forbidden slugs - windows thinks "C:\\Program Files\lpt0.json" is a printer.

    const FORBIDDEN: &[&str] = &[

        "con", "prn", "aux", "nul", //

        "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9", "com0", //

        "lpt1", "lpt2", "lpt3", "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9", "lpt0",

    ];

    /// Check whether this slug is forbidden here

    pub(super) fn check_forbidden(s: &str) -> Result<(), BadSlug> {

        for bad in FORBIDDEN {

            if s == *bad {

                return Err(BadSlug::ForbiddenOnWindows(bad));

            }

        }

        Ok(())

    }

    /// Display a forbidden slug error

    pub(super) fn fmt_error(s: &ForbiddenOnWindows, f: &mut fmt::Formatter) -> fmt::Result {

        write!(f, "slug (name) {s:?} is not allowed on Windows")

    }

}

/// Forbidden slug support for non-Windows

#[cfg(not(target_family = "windows"))]

mod os {

    use super::*;

    /// Check whether this slug is forbidden here

    #[allow(clippy::unnecessary_wraps)]

}

#[cfg(test)]

mod test {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use itertools::chain;

    #[test]

    fn bad() {

        for c in chain!(

            SLUG_SEPARATOR_CHARS.chars(), //

            ['\\', ' ', '\n', '\0']

        ) {

            let s = format!("x{c}y");

            let e_ref = SlugRef::new(&s).unwrap_err();

            assert_eq!(e_ref, BadSlug::BadCharacter(c));

            let e_own = Slug::new(s).unwrap_err();

            assert_eq!(e_ref, e_own);

        }

    }

    #[test]

    fn good() {

        let all = chain!(

            b'a'..=b'z', //

            b'0'..=b'9',

            [b'_'],

        )

        .map(char::from);

        let chk = |s: String| {

            let sref = SlugRef::new(&s).unwrap();

            let slug = Slug::new(s.clone()).unwrap();

            assert_eq!(sref.to_string(), s);

            assert_eq!(slug.to_string(), s);

        };

        chk(all.clone().collect());

        for c in all {

            chk(format!("{c}"));

        }

        // Hyphens are allowed, but not as the first character

        chk("a-".into());

        chk("a-b".into());

    }

    #[test]

    fn badchar_msg() {

        let chk = |s: &str, m: &str| {

            assert_eq!(

                SlugRef::new(s).unwrap_err().to_string(),

                m, //

            );

        };

        chk(".", "character '.' (U+002E) is not allowed");

        chk("\0", "character '\\0' (U+0000) is not allowed");

        chk(

            "\u{12345}",

            "character '\u{12345}' (U+12345) is not allowed",

        );

        chk(

            "-",

            "character '-' (U+002D) is not allowed as the first character",

        );

        chk("A", "character 'A' (U+0041) is not allowed");

    }

    #[test]

    fn windows_forbidden() {

        for s in ["con", "prn", "lpt0"] {

            let r = SlugRef::new(s);

            if cfg!(target_family = "windows") {

                assert_eq!(

                    r.unwrap_err().to_string(),

                    format!("slug (name) \"{s}\" is not allowed on Windows"),

                );

            } else {

                assert_eq!(r.unwrap().as_str(), s);

            }

        }

    }

    #[test]

    fn empty_slug() {

        assert_eq!(

            SlugRef::new("").unwrap_err().to_string(),

            "empty identifier (empty slug) not allowed"

        );

    }

}