brlapi 0.4.1

// SPDX-License-Identifier: LGPL-2.1

//! Text output operations for braille displays
//!
//! This module provides functionality for writing text to braille displays.
//! All text operations require the connection to be in TTY mode.

use crate::{Result, brlapi_call};
use brlapi_sys::*;
use libc::wchar_t;
use std::ffi::CString;

/// Cursor position for text display operations
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CursorPosition {
    /// Leave cursor position unchanged
    Leave,
    /// Turn cursor off (no cursor displayed)
    Off,
    /// Position cursor at specific character position (0-based)
    At(u32),
}

impl From<CursorPosition> for i32 {
    fn from(pos: CursorPosition) -> i32 {
        match pos {
            CursorPosition::Leave => BRLAPI_CURSOR_LEAVE,
            CursorPosition::Off => BRLAPI_CURSOR_OFF as i32,
            CursorPosition::At(position) => position as i32,
        }
    }
}

/// Text writer for handling braille display output
///
/// This struct provides methods for writing text to the braille display
/// in various formats. It requires an active TTY mode and borrows from
/// the `TtyMode` to ensure TTY mode remains active during its lifetime.
///
/// # Safety
///
/// `TextWriter` can only be created from an active `TtyMode`, ensuring
/// that text operations are only performed when TTY mode is properly active.
/// This prevents runtime errors from attempting text operations without TTY mode.
///
/// # Example
/// ```no_run
/// use brlapi::{Connection, TtyMode, text::CursorPosition};
///
/// fn main() -> Result<(), brlapi::BrlApiError> {
///     let connection = Connection::open()?;
///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
///     let writer = tty_mode.writer();
///
///     // Write text with cursor positioning
///     writer.write_with_cursor("Hello World!", CursorPosition::At(0))?;
///
///     Ok(())
/// }
/// ```
#[derive(Debug)]
pub struct TextWriter<'a> {
    tty_mode: &'a crate::TtyMode<'a>,
}

impl<'a> TextWriter<'a> {
    /// Create a new text writer from an active TTY mode
    ///
    /// This is the safe way to create a TextWriter, ensuring that TTY mode
    /// is active and will remain active for the lifetime of the TextWriter.
    ///
    /// # Safety
    ///
    /// This constructor ensures that text operations can only be performed
    /// when TTY mode is properly active, preventing runtime errors.
    pub fn from_tty_mode(tty_mode: &'a crate::TtyMode<'a>) -> Self {
        Self { tty_mode }
    }

    /// Internal constructor used by TtyMode - kept for compatibility
    ///
    /// This method is used internally by `TtyMode::writer()` and similar methods.
    /// It's not meant for direct public use - use `from_tty_mode()` instead.
    #[doc(hidden)]
    pub fn new(tty_mode: &'a crate::TtyMode<'a>) -> Self {
        Self::from_tty_mode(tty_mode)
    }

    /// Write text to the braille display
    ///
    /// The text will be displayed starting at the beginning of the display.
    /// The cursor position is left unchanged, allowing BRLTTY to continue
    /// managing cursor positioning based on screen reader focus tracking.
    /// This is appropriate for status displays and notifications that shouldn't
    /// interfere with the user's current cursor context.
    ///
    /// For messages that don't need cursor indication, use
    /// `write_notification()` or `write_with_cursor(text, CursorPosition::Off)`.
    pub fn write_text(&self, text: &str) -> Result<()> {
        self.write_with_cursor(text, CursorPosition::Leave)
    }

    /// Write text to the braille display with cursor positioning
    ///
    /// # Arguments
    /// * `text` - The text to display
    /// * `cursor` - Where to position the cursor
    ///
    /// # Important Note about Contractions
    ///
    /// This function writes text directly to the braille display using BrlAPI's
    /// simple character-to-braille mapping. It does NOT apply contractions.
    /// BrlAPI requires client-side contraction processing - see the `write_contracted()`
    /// methods for proper contraction support using liblouis.
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode, text::{TextWriter, CursorPosition}};
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///     
    ///     // Position cursor at character 5
    ///     writer.write_with_cursor("Hello world", CursorPosition::At(5))?;
    ///     
    ///     // Turn cursor off
    ///     writer.write_with_cursor("No cursor", CursorPosition::Off)?;
    ///     
    ///     // Leave cursor unchanged
    ///     writer.write_with_cursor("Keep cursor", CursorPosition::Leave)?;
    ///     
    ///     // TTY mode automatically exited when tty_mode is dropped
    ///     Ok(())
    /// }
    /// ```
    pub fn write_with_cursor(&self, text: &str, cursor: CursorPosition) -> Result<()> {
        let c_text = CString::new(text)?;

        // SAFETY: self.tty_mode.connection().handle_ptr() returns a valid handle in TTY mode.
        // cursor.into() converts to valid BrlAPI cursor constant.
        // c_text.as_ptr() points to valid null-terminated C string.
        brlapi_call!(unsafe {
            brlapi__writeText(
                self.tty_mode.connection().handle_ptr(),
                cursor.into(),
                c_text.as_ptr(),
            )
        })?;
        Ok(())
    }

    /// Write text to the braille display with cursor turned off
    ///
    /// This is a convenience method for notifications and temporary messages
    /// that don't need cursor indication. Equivalent to
    /// `write_with_cursor(text, CursorPosition::Off)`.
    pub fn write_notification(&self, text: &str) -> Result<()> {
        self.write_with_cursor(text, CursorPosition::Off)
    }

    /// Write text with contraction using liblouis
    ///
    /// This function translates text using the specified liblouis contraction table,
    /// then writes the contracted braille to the display. This provides proper
    /// literary braille output with contractions as expected by braille readers.
    ///
    /// # Arguments
    /// * `text` - The text to contract and display
    /// * `table` - The liblouis table name (e.g., "en-us-g2.ctb")
    /// * `cursor` - Where to position the cursor
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode, text::CursorPosition};
    /// use liblouis::Table;
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///
    ///     // Write contracted text using US Grade 2 braille
    ///     writer.write_contracted("Hello and welcome", "en-us-g2.ctb", CursorPosition::Off)?;
    ///
    ///     Ok(())
    /// }
    /// ```
    pub fn write_contracted(&self, text: &str, table: &str, cursor: CursorPosition) -> Result<()> {
        let translator = liblouis::Translator::new();
        let contracted_text = translator.translate_string(table, text)?;
        self.write_with_cursor(&contracted_text, cursor)
    }

    /// Write text with contraction using liblouis and cursor tracking
    ///
    /// This function translates text using the specified liblouis contraction table
    /// and properly maps cursor positions from the original text to the contracted output.
    ///
    /// # Arguments
    /// * `text` - The text to contract and display
    /// * `table` - The liblouis table name (e.g., "en-us-g2.ctb")
    /// * `cursor_pos` - Original cursor position in uncontracted text
    ///
    /// # Returns
    /// Returns the new cursor position in the contracted text
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode};
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///
    ///     // Write with cursor tracking
    ///     let new_cursor_pos = writer.write_contracted_with_cursor_tracking(
    ///         "Hello and welcome", "en-us-g2.ctb", 6
    ///     )?;
    ///     println!("Cursor moved to position {}", new_cursor_pos);
    ///
    ///     Ok(())
    /// }
    /// ```
    pub fn write_contracted_with_cursor_tracking(
        &self,
        text: &str,
        table: &str,
        cursor_pos: usize,
    ) -> Result<usize> {
        let translator = liblouis::Translator::new();
        let (contracted_text, new_cursor_pos) =
            translator.translate_string_with_cursor(table, text, cursor_pos)?;
        self.write_with_cursor(&contracted_text, CursorPosition::At(new_cursor_pos as u32))?;
        Ok(new_cursor_pos)
    }

    /// Write text using user's configured contraction table (convenience method)
    ///
    /// This method reads the user's preferred literary braille table from BRLTTY preferences
    /// and uses it for contraction. Falls back to "en-us-g2.ctb" if preferences cannot be read.
    ///
    /// This respects the user's accessibility preferences rather than hardcoding a table.
    pub fn write_contracted_user_preference(
        &self,
        text: &str,
        cursor: CursorPosition,
    ) -> Result<()> {
        let connection = self.tty_mode.connection();
        let table = connection.user_contraction_table()?;
        self.write_contracted(text, &table, cursor)
    }

    /// Write text using US English Grade 2 contractions (convenience method)
    ///
    /// This is a convenience method that explicitly uses US English Grade 2.
    /// Consider using `write_contracted_user_preference()` to respect user's table choice.
    pub fn write_contracted_en_us_g2(&self, text: &str, cursor: CursorPosition) -> Result<()> {
        self.write_contracted(text, "en-us-g2.ctb", cursor)
    }

    /// Write text using UK English Grade 2 contractions (convenience method)
    ///
    /// This is a convenience method for UK English Grade 2 contractions.
    /// Equivalent to `write_contracted(text, "en-gb-g2.ctb", cursor)`.
    pub fn write_contracted_en_gb_g2(&self, text: &str, cursor: CursorPosition) -> Result<()> {
        self.write_contracted(text, "en-gb-g2.ctb", cursor)
    }

    /// Write text using a liblouis Table (type-safe method)
    ///
    /// This method uses the liblouis::Table type for type-safe table management.
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode, text::CursorPosition};
    /// use liblouis::Table;
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///
    ///     let table = Table::en_us_g2();
    ///     writer.write_with_table(&table, "Hello world", CursorPosition::Off)?;
    ///
    ///     Ok(())
    /// }
    /// ```
    pub fn write_with_table(
        &self,
        table: &liblouis::Table,
        text: &str,
        cursor: CursorPosition,
    ) -> Result<()> {
        let translator = liblouis::Translator::new();
        let contracted_text = table.translate(&translator, text)?;
        self.write_with_cursor(&contracted_text, cursor)
    }

    /// Write text optimized for computer braille (uncontracted)
    ///
    /// This function is explicitly intended for computer braille output where
    /// character-by-character representation is desired. It's suitable for:
    /// - Programming code
    /// - Technical text
    /// - When precise character representation is needed
    pub fn write_computer_braille(&self, text: &str, cursor: CursorPosition) -> Result<()> {
        self.write_with_cursor(text, cursor)
    }

    /// Write Unicode text to the braille display
    ///
    /// This function writes Unicode text directly to the display without
    /// encoding conversion. It's useful for applications that work with
    /// wide characters or need precise Unicode handling.
    ///
    /// # Arguments
    /// * `text` - Unicode text as a string slice
    /// * `cursor` - Where to position the cursor
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode, text::{TextWriter, CursorPosition}};
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///     
    ///     // Write Unicode text
    ///     writer.write_unicode("Hello World!", CursorPosition::Off)?;
    ///     
    ///     // TTY mode automatically exited when tty_mode is dropped
    ///     Ok(())
    /// }
    /// ```
    pub fn write_unicode(&self, text: &str, cursor: CursorPosition) -> Result<()> {
        // Convert UTF-8 string to wide string (wchar_t)
        // wchar_t size varies by platform - use proper conversion
        let wide_text: Vec<wchar_t> = text
            .chars()
            .map(|c| c as wchar_t)
            .chain(std::iter::once(0))
            .collect();

        // SAFETY: self.tty_mode.connection().handle_ptr() returns a valid handle in TTY mode.
        // cursor.into() converts to valid BrlAPI cursor constant.
        // wide_text.as_ptr() points to valid null-terminated wide character array.
        brlapi_call!(unsafe {
            brlapi__writeWText(
                self.tty_mode.connection().handle_ptr(),
                cursor.into(),
                wide_text.as_ptr(),
            )
        })?;
        Ok(())
    }

    /// Write raw braille dots to the display
    ///
    /// This function allows direct control over each braille cell by specifying
    /// the dot pattern for each character position. Each byte represents one
    /// braille cell with dots encoded according to ISO/TR 11548-1:
    /// - bit 0: dot 1
    /// - bit 1: dot 2
    /// - bit 2: dot 3
    /// - bit 3: dot 4
    /// - bit 4: dot 5
    /// - bit 5: dot 6
    /// - bit 6: dot 7
    /// - bit 7: dot 8
    ///
    /// # Arguments
    /// * `dots` - Array of dot patterns, one per display cell
    ///
    /// # Examples
    /// ```no_run
    /// use brlapi::{Connection, TtyMode, text::TextWriter, Display};
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     let connection = Connection::open()?;
    ///     let display = Display::from_connection(&connection)?;
    ///     let (tty_mode, _) = TtyMode::enter_auto(&connection, None)?;
    ///     let writer = tty_mode.writer();
    ///     
    ///     // Create a pattern of alternating dots
    ///     let mut pattern = Vec::new();
    ///     for i in 0..display.width() {
    ///         if i % 2 == 0 {
    ///             pattern.push(0b10101010); // dots 2,4,6,8
    ///         } else {
    ///             pattern.push(0b01010101); // dots 1,3,5,7
    ///         }
    ///     }
    ///     
    ///     writer.write_dots(&pattern)?;
    ///     
    ///     // TTY mode automatically exited when tty_mode is dropped
    ///     Ok(())
    /// }
    /// ```
    pub fn write_dots(&self, dots: &[u8]) -> Result<()> {
        // SAFETY: self.tty_mode.connection().handle_ptr() returns a valid handle in TTY mode.
        // dots.as_ptr() points to valid byte array representing braille dot patterns.
        // BrlAPI expects dots array to be null-terminated or match display width.
        brlapi_call!(unsafe {
            brlapi__writeDots(self.tty_mode.connection().handle_ptr(), dots.as_ptr())
        })?;
        Ok(())
    }

    /// Get the TTY mode this text writer is associated with
    pub fn tty_mode(&self) -> &crate::TtyMode<'a> {
        self.tty_mode
    }

    /// Get the connection this text writer is associated with
    pub fn connection(&self) -> &crate::Connection {
        self.tty_mode.connection()
    }
}

/// Utility functions for text output
pub mod util {
    use super::*;
    use crate::Connection;

    /// Write a quick message to the braille display (convenience function)
    ///
    /// This handles connection establishment, TTY mode management, and cleanup automatically.
    /// It's the most convenient way to send a single message.
    ///
    /// For multiple messages, it's more efficient to maintain a connection and use
    /// `TtyMode` with `TextWriter`.
    ///
    /// # Example
    /// ```no_run
    /// use brlapi::text::util;
    ///
    /// fn main() -> Result<(), brlapi::BrlApiError> {
    ///     util::send_message("Hello from BrlAPI!")?;
    ///     Ok(())
    /// }
    /// ```
    pub fn send_message(text: &str) -> Result<()> {
        let connection = Connection::open()?;
        write_message(&connection, text)
    }

    /// Write a quick message using an existing connection (convenience function)
    ///
    /// This automatically enters TTY mode, writes the text, and exits TTY mode.
    /// More efficient than `send_message()` when you already have a connection.
    pub fn write_message(connection: &Connection, text: &str) -> Result<()> {
        use crate::TtyMode;
        let (tty_mode, _) = TtyMode::enter_auto(connection, None)?;
        let writer = tty_mode.writer();
        writer.write_text(text)
    }

    /// Write a quick message with cursor positioning using an existing connection
    ///
    /// This automatically enters TTY mode, writes the text, and exits TTY mode.
    pub fn write_message_with_cursor(
        connection: &Connection,
        text: &str,
        cursor: CursorPosition,
    ) -> Result<()> {
        use crate::TtyMode;
        // Validate text early to avoid entering TTY mode unnecessarily
        let _ = CString::new(text)?;

        let (tty_mode, _) = TtyMode::enter_auto(connection, None)?;
        let writer = tty_mode.writer();
        writer.write_with_cursor(text, cursor)
    }

    /// Write a notification message using an existing connection
    ///
    /// This is a convenience function for temporary messages that don't need cursor indication.
    pub fn write_notification(connection: &Connection, text: &str) -> Result<()> {
        write_message_with_cursor(connection, text, CursorPosition::Off)
    }

    /// Write contracted text using an existing connection (convenience function)
    ///
    /// This automatically enters TTY mode, contracts and writes the text, then exits TTY mode.
    pub fn write_contracted_message(
        connection: &Connection,
        text: &str,
        table: &str,
    ) -> Result<()> {
        use crate::TtyMode;
        let (tty_mode, _) = TtyMode::enter_auto(connection, None)?;
        let writer = tty_mode.writer();
        writer.write_contracted(text, table, CursorPosition::Off)
    }

    /// Write contracted text using user's preferred table (convenience function)
    ///
    /// This is the most convenient way to send a single contracted message using
    /// the user's configured contraction table from BRLTTY preferences.
    /// Falls back to "en-us-g2.ctb" if preferences cannot be read.
    pub fn send_contracted_message(text: &str) -> Result<()> {
        let connection = Connection::open()?;
        let table = connection.user_contraction_table()?;
        write_contracted_message(&connection, text, &table)
    }

    /// Write contracted text using US English Grade 2 (explicit function)
    ///
    /// This explicitly uses US English Grade 2 regardless of user preferences.
    /// Consider using `send_contracted_message()` to respect user's table choice.
    pub fn send_contracted_message_en_us_g2(text: &str) -> Result<()> {
        let connection = Connection::open()?;
        write_contracted_message(&connection, text, "en-us-g2.ctb")
    }
}