oak_core/helpers/
mod.rs

1//! Helper utilities for common operations in the Oak Core parsing framework.
2//!
3//! This module provides utility functions for file system operations, URL handling,
4//! and other common tasks that are useful when working with the parsing framework.
5
6use crate::errors::OakError;
7
8use crate::source::SourceText;
9
10use std::fs::File;
11
12use url::Url;
13#[cfg(feature = "testing")]
14mod lexing;
15#[cfg(feature = "testing")]
16pub use self::lexing::LexerTester;
17
18#[cfg(feature = "testing")]
19mod parsing;
20#[cfg(feature = "testing")]
21pub use self::parsing::ParserTester;
22
23#[cfg(feature = "testing")]
24mod building;
25#[cfg(feature = "testing")]
26pub use self::building::BuilderTester;
27
28/// Converts a file system path to a URL.
29///
30/// # Arguments
31///
32/// * `path` - The file system path to convert
33///
34/// # Returns
35///
36/// A `Result` containing the URL if successful, or an `OakError` if the path is invalid
37///
38/// # Examples
39///
40/// ```ignore
41/// let path = std::path::Path::new("/home/user/file.txt");
42/// let url = url_from_path(path)?;
43/// ```
44pub fn url_from_path(path: &std::path::Path) -> Result<Url, OakError> {
45    match Url::from_file_path(path) {
46        Ok(o) => Ok(o),
47        Err(_) => Err(OakError::custom_error(format!("invalid url {}", path.display()))),
48    }
49}
50
51/// Reads source text from a file path.
52///
53/// This function reads the contents of a file and creates a `SourceText` with
54/// the appropriate URL metadata. It's a convenience function for loading source
55/// files into the parsing system.
56///
57/// # Arguments
58///
59/// * `path` - The file system path to read from
60///
61/// # Returns
62///
63/// A `Result` containing the `SourceText` if successful, or an `OakError` if reading fails
64///
65/// # Examples
66///
67/// ```ignore
68/// let path = std::path::Path::new("source.rs");
69/// let source = source_from_path(path)?;
70/// ```
71pub fn source_from_path(path: &std::path::Path) -> Result<SourceText, OakError> {
72    let url = url_from_path(path)?;
73    match std::fs::read_to_string(path) {
74        Ok(o) => Ok(SourceText::new_with_url(o, url)),
75        Err(e) => Err(OakError::io_error(e, url)),
76    }
77}
78
79/// Reads JSON data from a file path.
80///
81/// This function reads the contents of a file and parses it as JSON.
82///
83/// # Arguments
84///
85/// * `path`: The file system path to read from
86///
87/// returns: Result<T, OakError>
88///
89/// # Examples
90///
91/// ```
92/// ```
93#[cfg(feature = "serde_json")]
94pub fn json_from_path<T>(path: &std::path::Path) -> Result<T, OakError>
95where
96    T: for<'de> serde::Deserialize<'de>,
97{
98    let url = url_from_path(path)?;
99    match File::open(path) {
100        Ok(o) => Ok(serde_json::from_reader(o)?),
101        Err(e) => Err(OakError::io_error(e, url)),
102    }
103}
104
105/// Opens a file and returns a file handle.
106///
107/// # Arguments
108///
109/// * `path` - The file system path to open
110///
111/// # Returns
112///
113/// A `Result` containing the file handle if successful, or an `OakError` if opening fails
114///
115/// # Examples
116///
117/// ```ignore
118/// let path = std::path::Path::new("source.rs");
119/// let file = open_file(path)?;
120/// ```
121pub fn open_file(path: &std::path::Path) -> Result<File, OakError> {
122    let url = url_from_path(path)?;
123    match File::open(path) {
124        Ok(o) => Ok(o),
125        Err(e) => Err(OakError::io_error(e, url)),
126    }
127}
128
129/// Creates a file and returns a file handle.
130///
131/// # Arguments
132///
133/// * `path` - The file system path to create
134///
135/// # Returns
136///
137/// A `Result` containing the file handle if successful, or an `OakError` if creation fails
138///
139/// # Examples
140///
141/// ```ignore
142/// let path = std::path::Path::new("output.txt");
143/// let file = create_file(path)?;
144/// ```
145pub fn create_file(path: &std::path::Path) -> Result<File, OakError> {
146    let url = url_from_path(path)?;
147    match File::create(path) {
148        Ok(o) => Ok(o),
149        Err(e) => Err(OakError::io_error(e, url)),
150    }
151}
oak_core/helpers/mod.rs

oak_core/helpers/
mod.rs
