Maintain/Build/

TomlEdit.rs

//=============================================================================//
// File Path: Element/Maintain/Source/Build/TomlEdit.rs
//=============================================================================//
// Module: TomlEdit
//
// Brief Description: Implements TOML file editing for Cargo.toml.
//
// RESPONSIBILITIES:
// ================
//
// Primary:
// - Dynamically modify name fields in Cargo.toml files
// - Update package.name, package.default-run, lib.name, and bin.name
// - Preserve the original structure and formatting
//
// Secondary:
// - Provide detailed logging of changes made
// - Return whether any modifications occurred
//
// ARCHITECTURAL ROLE:
// ===================
//
// Position:
// - Infrastructure/File manipulation layer
// - TOML editing functionality
//
// Dependencies (What this module requires):
// - External crates: toml_edit, std (fs, log)
// - Internal modules: Error::BuildError
// - Traits implemented: None
//
// Dependents (What depends on this module):
// - Build orchestration functions
// - Process function
//
// IMPLEMENTATION DETAILS:
// =======================
//
// Design Patterns:
// - Builder pattern (via toml_edit)
// - Functional pattern
//
// Performance Considerations:
// - Complexity: O(n) - parsing and modifying based on file size
// - Memory usage patterns: In-memory document manipulation
// - Hot path optimizations: None needed
//
// Thread Safety:
// - Thread-safe: No (not designed for concurrent access to files)
// - Synchronization mechanisms used: None
// - Interior mutability considerations: None
//
// Error Handling:
// - Error types returned: BuildError (Edit type)
// - Recovery strategies: Propagate error up; Guard restores original file
//
// EXAMPLES:
// =========
//
// Example 1: Product name change
use std::{fs, path::Path};

use log::{debug, info, warn};
use toml_edit::{DocumentMut as TomlDocument, Item as TomlItem, Value as TomlValue};

/// ```rust
/// use crate::Maintain::Source::Build::TomlEdit;
/// let cargo_path = PathBuf::from("Cargo.toml");
/// let old_name = "Mountain";
/// let new_name = "Debug_NodeEnvironment_Mountain";
/// let modified = TomlEdit(&cargo_path, old_name, new_name)?;
/// if modified {
/// 	println!("Cargo.toml was updated");
/// }
/// ```
// Example 2: No change needed
/// ```rust
/// use crate::Maintain::Source::Build::TomlEdit;
/// let modified = TomlEdit(&cargo_path, "Mountain", "Mountain")?;
/// // modified = false, no changes made
/// ```
//
//=============================================================================//
// IMPLEMENTATION
//=============================================================================//
use crate::Build::Error::Error as BuildError;

/// Dynamically modifies specific name fields within a `Cargo.toml` file.
///
/// This function searches for and updates the following fields if they match
/// the old name:
/// - `package.name` - The package name identifier
/// - `package.default-run` - The default binary to run
/// - `lib.name` - The library name
/// - `bin.name` - The binary name (first occurrence)
///
/// The function preserves the existing file structure and ensures that only
/// matching names are updated, preventing unintended modifications.
///
/// # Parameters
///
/// * `File` - Path to the Cargo.toml file to modify
/// * `Old` - The current name to search for and replace
/// * `Current` - The new name to set
///
/// # Returns
///
/// Returns a `Result<bool>` indicating:
/// - `Ok(true)` - The file was modified and saved
/// - `Ok(false)` - No changes were made (either no matches or old == current)
/// - `Err(BuildError)` - An error occurred during modification
///
/// # Errors
///
/// * `BuildError::Io` - If the file cannot be read or written
/// * `BuildError::Edit` - If the TOML document cannot be parsed or modified
///
/// # Behavior
///
/// - If `Old` equals `Current`, returns `Ok(false)` without modifying the file
/// - Only updates fields that exactly match the old name
/// - Updates are atomic: the file is written only if at least one change occurs
/// - Logs all changes made at INFO level
///
/// # Example
///
/// ```no_run
/// use crate::Maintain::Source::Build::TomlEdit;
/// let path = PathBuf::from("Cargo.toml");
/// let modified = TomlEdit(&path, "Mountain", "Debug_Mountain")?;
/// if modified {
/// 	println!("Successfully updated Cargo.toml");
/// }
/// ```
pub fn TomlEdit(File:&Path, Old:&str, Current:&str) -> Result<bool, BuildError> {
	debug!(target: "Build::Toml", "Attempting to modify TOML file: {}", File.display());

	let Data = fs::read_to_string(File)?;

	if Old == Current {
		info!(
			target: "Build::Toml",

			"Old name '{}' is the same as current name '{}'. No changes needed for {}.",

			Old,

			Current,

			File.display()
		);

		return Ok(false);
	}

	debug!(target: "Build::Toml", "Old name: '{}', Current name: '{}'", Old, Current);

	let mut Parsed:TomlDocument = Data.parse()?;

	let mut PackageChange = false;

	let mut LibraryChange = false;

	let mut BinaryChange = false;

	let mut DefaultChange = false;

	// Update package.name
	if let Some(PackageTable) = Parsed.get_mut("package").and_then(|Item| Item.as_table_mut()) {
		if let Some(NameItem) = PackageTable.get_mut("name") {
			if NameItem.as_str() == Some(Old) {
				*NameItem = TomlItem::Value(TomlValue::String(toml_edit::Formatted::new(Current.to_string())));

				PackageChange = true;

				debug!(target: "Build::Toml", "Changed package.name");
			}
		}

		// Update package.default-run
		if let Some(RunItem) = PackageTable.get_mut("default-run") {
			if RunItem.as_str() == Some(Old) {
				*RunItem = TomlItem::Value(TomlValue::String(toml_edit::Formatted::new(Current.to_string())));

				DefaultChange = true;

				debug!(target: "Build::Toml", "Changed package.default-run");
			}
		}
	}

	// Update lib.name
	if let Some(LibraryTable) = Parsed.get_mut("lib").and_then(|Item| Item.as_table_mut()) {
		if let Some(NameItem) = LibraryTable.get_mut("name") {
			if NameItem.as_str() == Some(Old) {
				*NameItem = TomlItem::Value(TomlValue::String(toml_edit::Formatted::new(Current.to_string())));

				LibraryChange = true;

				debug!(target: "Build::Toml", "Changed lib.name");
			}
		}
	}

	// Update bin.name (first occurrence)
	if let Some(BinArray) = Parsed.get_mut("bin").and_then(|Item| Item.as_array_of_tables_mut()) {
		for Table in BinArray.iter_mut() {
			if let Some(NameItem) = Table.get_mut("name") {
				if NameItem.as_str() == Some(Old) {
					*NameItem = TomlItem::Value(TomlValue::String(toml_edit::Formatted::new(Current.to_string())));

					BinaryChange = true;

					debug!(target: "Build::Toml", "Changed a bin.name entry to '{}'", Current);

					break;
				}
			}
		}
	}

	// Write the file if any changes were made
	if PackageChange || LibraryChange || BinaryChange || DefaultChange {
		let Output = Parsed.to_string();

		fs::write(File, Output)?;

		let mut ModifiedItems = Vec::new();

		if PackageChange {
			ModifiedItems.push("package.name");
		}

		if DefaultChange {
			ModifiedItems.push("package.default-run");
		}

		if LibraryChange {
			ModifiedItems.push("lib.name");
		}

		if BinaryChange {
			ModifiedItems.push("bin.name");
		}

		info!(
			target: "Build::Toml",

			"Temporarily changed {} in {} to: {}",

			ModifiedItems.join(", "),

			File.display(),

			Current
		);

		Ok(true)
	} else {
		warn!(
			target: "Build::Toml",

			"Name '{}' not found in relevant sections of {}. No changes made to file.",

			Old,

			File.display()
		);

		Ok(false)
	}
}