interface_rs/
lib.rs

1// src/lib.rs
2
3//! # Interface-rs
4//!
5//! A Rust library for parsing and manipulating an `interfaces(5)` file.
6//!
7//! This library provides structs and functions to load, parse, modify, and save
8//! network interface configurations in the Debian-style `interfaces(5)` file
9//! format. This file is typically found at `/etc/network/interfaces` on Debian-based
10//! systems but may be located elsewhere depending on your system configuration.
11//!
12//! ## Features
13//!
14//! - **Load and parse** existing configurations from an `interfaces(5)` file.
15//! - **Modify** network interface configurations programmatically.
16//! - **Add or remove** network interfaces.
17//! - **Save** changes back to the file system.
18//! - **Fluent API** using the builder pattern for creating and modifying interfaces.
19//!
20//! ## Example
21//!
22//! ### Loading Interfaces and Modifying an Existing Interface
23//!
24//! ```rust
25//! use interface_rs::NetworkInterfaces;
26//! use interface_rs::interface::{Interface, Family};
27//!
28//! fn main() -> Result<(), Box<dyn std::error::Error>> {
29//!     // Load interfaces (replace with an existing file path during tests)
30//!     let mut net_ifaces = NetworkInterfaces::load("tests/interfaces")?;
31//!
32//!     // Retrieve and modify an existing interface
33//!     if let Some(iface) = net_ifaces.get_interface("eth0") {
34//!         let modified_iface = iface.edit()
35//!             .with_method("static")
36//!             .remove_option("address")
37//!             .with_option("address", "192.168.1.50")
38//!             .with_option("netmask", "255.255.255.0")
39//!             .build();
40//!         net_ifaces.add_interface(modified_iface);
41//!     }
42//!
43//!     // Save changes
44//!     net_ifaces.save()?;
45//!     Ok(())
46//! }
47//! ```
48//!
49//! ### Adding a New Interface
50//!
51//! ```rust
52//! use interface_rs::NetworkInterfaces;
53//! use interface_rs::interface::{Interface, Family};
54//!
55//! fn main() -> Result<(), Box<dyn std::error::Error>> {
56//!     // Load interfaces (replace with an existing file path during tests)
57//!     let mut net_ifaces = NetworkInterfaces::load("tests/interfaces")?;
58//!
59//!     // Create a new interface using the builder pattern
60//!     net_ifaces.add_interface(
61//!         Interface::builder("swp1")
62//!             .with_auto(true)
63//!             .with_allow("hotplug")
64//!             .with_family(Family::Inet)
65//!             .with_method("static")
66//!             .with_option("address", "192.168.100.1")
67//!             .with_option("netmask", "255.255.255.0")
68//!             .build()
69//!     );
70//!
71//!     // Save changes back to the file
72//!     net_ifaces.save()?;
73//!
74//!     Ok(())
75//! }
76//! ```
77//!
78//! ### Deleting an Interface
79//!
80//! ```rust
81//! use interface_rs::NetworkInterfaces;
82//!
83//! fn main() -> Result<(), Box<dyn std::error::Error>> {
84//!     // Load interfaces (replace with an existing file path during tests)
85//!     let mut net_ifaces = NetworkInterfaces::load("tests/interfaces")?;
86//!
87//!     // Delete an interface by name
88//!     net_ifaces.delete_interface("eth0");
89//!
90//!     // Save changes back to the file
91//!     net_ifaces.save()?;
92//!
93//!     Ok(())
94//! }
95//! ```
96//!
97//! ## License
98//!
99//! This project is licensed under the MIT License.
100
101pub mod error;
102pub mod interface;
103pub mod network_interfaces;
104pub mod helper;
105mod parser;
106
107pub use error::NetworkInterfacesError;
108pub use interface::{Family, Interface, InterfaceBuilder, Mapping};
109pub use network_interfaces::NetworkInterfaces;
interface_rs/lib.rs

interface_rs/
lib.rs
