rumtk-core 0.17.0

/*
 * rumtk attempts to implement HL7 and medical protocols for interoperability in medicine.
 * This toolkit aims to be reliable, simple, performant, and standards compliant.
 * Copyright (C) 2025  Luis M. Santos, M.D. <lsantos@medicalmasses.com>
 * Copyright (C) 2025  MedicalMasses L.L.C. <contact@medicalmasses.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

///
/// Tools for handling reading and writing from the standard I/O/E.
///
/// Per this [stackoverflow discussion](https://unix.stackexchange.com/questions/37508/in-what-order-do-piped-commands-run).
/// Note:
///```text
///  Piped commands run concurrently. When you run ps | grep …, it's the luck of the draw (or a matter of details of the workings of the shell combined with scheduler fine-tuning deep in the bowels of the kernel) as to whether ps or grep starts first, and in any case they continue to execute concurrently.
///
///  This is very commonly used to allow the second program to process data as it comes out from the first program, before the first program has completed its operation. For example
///
///  grep pattern very-large-file | tr a-z A-Z
///  begins to display the matching lines in uppercase even before grep has finished traversing the large file.
///
///  grep pattern very-large-file | head -n 1
///  displays the first matching line, and may stop processing well before grep has finished reading its input file.
///
///  If you read somewhere that piped programs run in sequence, flee this document. Piped programs run concurrently and always have.
/// ```
///
/// I bring the note above because that was my original understanding, but I have had to spend a
/// crazy amount of time trying to get data flowing from one process to another without the initial
/// process first exiting.
///
pub mod cli_utils {
    use crate::base::{RUMResult, RUMVec};
    use crate::cpu::CPU_PAGE_SIZE;
    use crate::strings::rumtk_format;
    use std::io::{stdin, stdout, BufWriter, Read, Write};
    use std::os::fd::{AsRawFd, FromRawFd};

    const STD_IN_STEP_SIZE: usize = u16::MAX as usize;

    pub type BufferSlice = Vec<u8>;
    pub type BufferChunk = [u8; STD_IN_STEP_SIZE];

    ///
    /// Consumes the incoming buffer in chunks of [CPU_PAGE_SIZE](CPU_PAGE_SIZE) bytes size
    /// until no more bytes are present.
    ///
    /// To avoid calling a blocking read, we check if the read yielded an amount of bytes fewer than
    /// the requested chunk size.
    ///
    /// ## Example
    ///
    /// ```
    /// use rumtk_core::cli::cli_utils::{read_stdin};
    /// use rumtk_core::cpu::CPU_PAGE_SIZE;
    ///
    /// let stdin_data = read_stdin(CPU_PAGE_SIZE).unwrap();
    ///
    /// assert_eq!(stdin_data.len(), 0, "Returned data with {} size even though we expected 0 bytes!", stdin_data.len())
    /// ```
    ///
    pub fn read_stdin(minimum_size: usize) -> RUMResult<RUMVec<u8>> {
        let mut stdin_buffer = RUMVec::with_capacity(minimum_size);

        loop {
            let s = read_some_stdin(&mut stdin_buffer)?;

            // If we attempt the next read, it is likely to be a 0 byte read. Why does this matter?
            // Well, if the other end of the pipe is still open, the read call will stall in Rust's
            // std and it is because it expects EOF but that never comes.
            // If you look at https://man7.org/linux/man-pages/man2/read.2.html, read should return
            // 0 and simply let us naturally break, but a read < than requested buffer appears to be
            // an equally valid way to handle terminal and piped data.
            // We have to check against 0 because the more optimal the buffer size we ask for (e.g.
            // larger reads for minimum syscall time) the less likely the kernel is ready with the
            // requested data.

            // Example reads at u16::Max
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 8192 bytes
            // Read 65535 bytes
            // Read 61441 bytes
            // Read 65535 bytes
            // Read 41974 bytes
            // Read 0 bytes
            // Total: 2331637 => 2.2MB
            if s == 0 {
                break;
            }
        }

        Ok(stdin_buffer)
    }

    ///
    /// Consumes the incoming buffer in chunks of [CPU_SIMD_64_SIZE](crate::cpu::CPU_SIMD_64_SIZE) bytes size.
    ///
    /// ## Example
    ///
    /// ```
    /// use std::io::stdin;
    /// use std::io::prelude::*;
    /// use std::process::{Command, Stdio};
    /// use rumtk_core::cli::cli_utils::{read_some_stdin};
    /// use rumtk_core::cpu::CPU_PAGE_SIZE;
    /// use rumtk_core::base::RUMVec;
    ///
    /// let mut stdin_buffer = RUMVec::with_capacity(CPU_PAGE_SIZE);
    /// let mut s = read_some_stdin(&mut stdin_buffer).unwrap();
    /// let mut totas_s = s;
    /// while s > 0 {
    ///    s = read_some_stdin(&mut stdin_buffer).unwrap();
    ///    totas_s += s;
    /// }
    ///
    /// assert_eq!(totas_s, 0, "Returned data with {} size even though we expected 0 bytes!", totas_s)
    /// ```
    ///
    #[inline]
    pub fn read_some_stdin(buf: &mut BufferSlice) -> RUMResult<usize> {
        let mut chunk: BufferChunk = [0; STD_IN_STEP_SIZE];

        match stdin().read(&mut chunk[..]) {
            Ok(s) => {
                buf.extend_from_slice(&chunk[..s]);
                Ok(s)
            }
            Err(e) => Err(rumtk_format!("Error reading stdin chunk because {}!", e)),
        }
    }

    ///
    /// writes [`stringview`] to `stdout`.
    ///
    pub fn write_string_stdout(data: &str) -> RUMResult<()> {
        write_stdout(&data.as_bytes())
    }

    ///
    /// Writes [RUMBuffer] to `stdout`.
    ///
    #[cfg(target_os = "windows")]
    pub fn write_stdout(data: &[u8]) -> RUMResult<()> {
        match stdout().write_all(data) {
            Ok(_) => {}
            Err(e) => return Err(rumtk_format!("Error writing to stdout because => {}", e)),
        };
        flush_stdout()?;
        Ok(())
    }

    #[cfg(any(target_os = "unix", target_os = "linux", target_os = "macos"))]
    pub fn write_stdout(data: &[u8]) -> RUMResult<()> {
        // Create an unbuffered File handle from file descriptor 1 (stdout)
        let stdout_fd = stdout().as_raw_fd();

        {
            let mut file = BufWriter::new(unsafe { std::fs::File::from_raw_fd(stdout_fd) });

            // Write bytes directly
            match file.write_all(data) {
                Ok(_) => {
                    file.flush().unwrap_or_default();
                    std::mem::forget(file);
                },
                Err(e) => return Err(rumtk_format!("Error writing to stdout because {}", e)),
            };
        }

        flush_stdout()?;
        Ok(())
    }

    fn flush_stdout() -> RUMResult<()> {
        match stdout().flush() {
            Ok(_) => Ok(()),
            Err(e) => Err(rumtk_format!("Error flushing stdout because => {}", e)),
        }
    }

    pub fn print_license_notice(program: &str, year: &str, author_list: &Vec<&str>) {
        let authors = author_list.join(", ");
        let notice = rumtk_format!(
            r"  {program}  Copyright (C) {year}  {authors}
                This program comes with ABSOLUTELY NO WARRANTY.
                This is free software, and you are welcome to redistribute it
                under certain conditions."
        );
        eprintln!("{}", notice);
    }
}

pub mod macros {
    ///
    /// Reads STDIN and unescapes the incoming message.
    /// Return this unescaped message.
    ///
    /// # Example
    ///
    /// ## Without specifying the minimum read size.
    /// ```
    /// use rumtk_core::base::{RUMResult, RUMVec};
    /// use rumtk_core::buffers::*;
    /// use rumtk_core::rumtk_read_stdin;
    ///
    /// fn test_read_stdin() -> RUMResult<RUMVec<u8>> {
    ///     rumtk_read_stdin!()
    /// }
    ///
    /// match test_read_stdin() {
    ///     Ok(s) => (),
    ///     Err(e) => panic!("Error reading stdin because => {}", e)
    /// }
    /// ```
    ///
    /// ## With specifying the minimum read size.
    /// ```
    /// use rumtk_core::base::{RUMResult, RUMVec};
    /// use rumtk_core::buffers::*;
    /// use rumtk_core::rumtk_read_stdin;
    ///
    /// fn test_read_stdin() -> RUMResult<RUMVec<u8>> {
    ///     rumtk_read_stdin!(1024)
    /// }
    ///
    /// match test_read_stdin() {
    ///     Ok(s) => (),
    ///     Err(e) => panic!("Error reading stdin because => {}", e)
    /// }
    /// ```
    ///
    #[macro_export]
    macro_rules! rumtk_read_stdin {
        (  ) => {{
            use $crate::cpu::CPU_PAGE_SIZE;
            use $crate::cli::cli_utils::{read_stdin};
            read_stdin(CPU_PAGE_SIZE * CPU_PAGE_SIZE)
        }};
        ( $min_expected_size:expr ) => {{
            use $crate::cli::cli_utils::{read_stdin};
            read_stdin($min_expected_size)
        }};
    }

    ///
    /// Writes [RUMString](crate::strings::RUMString) or [RUMBuffer](crate::types::RUMBuffer) to `stdout`.
    ///
    /// If the `binary` parameter is passed, we push the `message` parameter directly to `stdout`. the
    /// `message` parameter has to be of type [RUMBuffer](crate::types::RUMBuffer).
    ///
    /// ## Example
    ///
    /// ### Default / Pushing a String
    /// ```
    /// use rumtk_core::rumtk_write_stdout;
    ///
    /// rumtk_write_stdout!("I ❤ my wife!");
    /// ```
    ///
    /// ## Pushing Binary Buffer
    /// ```
    /// use rumtk_core::rumtk_write_stdout;
    /// use rumtk_core::buffers::{new_random_rumbuffer, DEFAULT_BUFFER_CHUNK_SIZE};
    ///
    /// let buffer = new_random_rumbuffer::<DEFAULT_BUFFER_CHUNK_SIZE>();
    /// rumtk_write_stdout!(buffer, true);
    /// ```
    ///
    #[macro_export]
    macro_rules! rumtk_write_stdout {
        ( $message:expr ) => {{
            use $crate::cli::cli_utils::write_string_stdout;
            write_string_stdout(&$message)
        }};
        ( $message:expr, $binary:expr ) => {{
            use $crate::cli::cli_utils::write_stdout;
            write_stdout(&$message)
        }};
    }

    ///
    /// Prints the mandatory GPL License Notice to terminal!
    ///
    /// # Example
    /// ## Default
    /// ```
    /// use rumtk_core::rumtk_print_license_notice;
    ///
    /// rumtk_print_license_notice!();
    /// ```
    /// ## Program Only
    /// ```
    /// use rumtk_core::rumtk_print_license_notice;
    ///
    /// rumtk_print_license_notice!("RUMTK");
    /// ```
    /// ## Program + Year
    /// ```
    /// use rumtk_core::rumtk_print_license_notice;
    ///
    /// rumtk_print_license_notice!("RUMTK", "2025");
    /// ```
    /// ## Program + Year + Authors
    /// ```
    /// use rumtk_core::rumtk_print_license_notice;
    ///
    /// rumtk_print_license_notice!("RUMTK", "2025", &vec!["Luis M. Santos, M.D."]);
    /// ```
    ///
    #[macro_export]
    macro_rules! rumtk_print_license_notice {
        ( ) => {{
            use $crate::cli::cli_utils::print_license_notice;

            print_license_notice("RUMTK", "2025", &vec!["Luis M. Santos, M.D."]);
        }};
        ( $program:expr ) => {{
            use $crate::cli::cli_utils::print_license_notice;
            print_license_notice(&$program, "2025", &vec!["2025", "Luis M. Santos, M.D."]);
        }};
        ( $program:expr, $year:expr ) => {{
            use $crate::cli::cli_utils::print_license_notice;
            print_license_notice(&$program, &$year, &vec!["Luis M. Santos, M.D."]);
        }};
        ( $program:expr, $year:expr, $authors:expr ) => {{
            use $crate::cli::cli_utils::print_license_notice;
            print_license_notice(&$program, &$year, &$authors);
        }};
    }
}