gaia_types/reader/

mod.rs

#![doc = include_str!("readme.md")]

pub use self::{token::Token, token_stream::TokenStream};
use crate::{GaiaDiagnostics, GaiaError};
use byteorder::{ByteOrder, ReadBytesExt};
use serde::{Deserialize, Serialize};
use std::{
    io::{Read, Seek, SeekFrom},
    marker::PhantomData,
};
use url::Url;

mod token;
mod token_stream;

/// Binary reader for reading data from types that implement ReadBytesExt.
///
/// This is a generic struct that can wrap any type implementing ReadBytesExt,
/// providing binary data reading functionality.
#[derive(Debug)]
pub struct BinaryReader<R, E> {
    reader: R,
    position: u64,
    endian: PhantomData<E>,
    errors: Vec<GaiaError>,
}

impl<R: Read, E> Read for BinaryReader<R, E> {
    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
        let bytes_read = self.reader.read(buffer)?;
        self.position += bytes_read as u64;
        Ok(bytes_read)
    }
}

impl<R: Seek, E> Seek for BinaryReader<R, E> {
    fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
        let new_position = self.reader.seek(pos)?;
        self.position = new_position;
        Ok(new_position)
    }
}

impl<R, E> BinaryReader<R, E> {
    /// Create a new binary reader.
    ///
    /// # Arguments
    /// * `reader` - The data source to read from.
    ///
    /// # Returns
    /// A new BinaryReader instance.
    pub fn new(reader: R) -> Self {
        Self { reader, position: 0, endian: Default::default(), errors: vec![] }
    }

    /// Get the current reading position.
    ///
    /// # Returns
    /// The current byte offset position.
    pub fn get_position(&self) -> u64 {
        self.position
    }

    /// Set the reading position.
    ///
    /// Note: This function will return an error if the underlying reader does not support Seek operations.
    ///
    /// # Arguments
    /// * `position` - The new reading position.
    ///
    /// # Returns
    /// The operation result containing the new position.
    pub fn set_position(&mut self, position: u64) -> Result<u64, GaiaError>
    where
        R: Seek,
    {
        self.reader.seek(SeekFrom::Start(position))?;
        self.position = position;
        Ok(position)
    }
    /// Finish reading and return the results with diagnostics.
    pub fn finish(self) -> GaiaDiagnostics<R> {
        GaiaDiagnostics { result: Ok(self.reader), diagnostics: self.errors }
    }

    /// Get and clear the currently accumulated error list.
    /// This method returns all errors encountered during reading and resets the internal error storage.
    pub fn take_errors(&mut self) -> Vec<GaiaError> {
        std::mem::take(&mut self.errors)
    }
}

impl<R: ReadBytesExt, E: ByteOrder> BinaryReader<R, E> {
    /// Read a u8 value.
    ///
    /// # Returns
    /// The read u8 value or an IO error.
    pub fn read_u8(&mut self) -> std::io::Result<u8> {
        let value = self.reader.read_u8()?;
        self.position += 1;
        Ok(value)
    }

    /// Read a u16 value.
    ///
    /// # Returns
    /// The read u16 value or an IO error.
    pub fn read_u16(&mut self) -> std::io::Result<u16> {
        let value = self.reader.read_u16::<E>()?;
        self.position += 2;
        Ok(value)
    }

    /// Read an i16 value.
    ///
    /// # Returns
    /// The read i16 value or an IO error.
    pub fn read_i16(&mut self) -> std::io::Result<i16> {
        let value = self.reader.read_i16::<E>()?;
        self.position += 2;
        Ok(value)
    }

    /// Read a u32 value.
    ///
    /// # Returns
    /// The read u32 value or an IO error.
    pub fn read_u32(&mut self) -> std::io::Result<u32> {
        let value = self.reader.read_u32::<E>()?;
        self.position += 4;
        Ok(value)
    }

    /// Read a u64 value.
    ///
    /// # Returns
    /// The read u64 value or an IO error.
    pub fn read_u64(&mut self) -> std::io::Result<u64> {
        let value = self.reader.read_u64::<E>()?;
        self.position += 8;
        Ok(value)
    }

    /// Read an i32 value.
    ///
    /// # Returns
    /// The read i32 value or an IO error.
    pub fn read_i32(&mut self) -> std::io::Result<i32> {
        let value = self.reader.read_i32::<E>()?;
        self.position += 4;
        Ok(value)
    }

    /// Read an i64 value.
    ///
    /// # Returns
    /// The read i64 value or an IO error.
    pub fn read_i64(&mut self) -> std::io::Result<i64> {
        let value = self.reader.read_i64::<E>()?;
        self.position += 8;
        Ok(value)
    }

    /// Read an f32 value.
    ///
    /// # Returns
    /// The read f32 value or an IO error.
    pub fn read_f32(&mut self) -> std::io::Result<f32> {
        let value = self.reader.read_f32::<E>()?;
        self.position += 4;
        Ok(value)
    }

    /// Read an f64 value.
    ///
    /// # Returns
    /// The read f64 value or an IO error.
    pub fn read_f64(&mut self) -> std::io::Result<f64> {
        let value = self.reader.read_f64::<E>()?;
        self.position += 8;
        Ok(value)
    }

    /// Read a byte array of specified length.
    ///
    /// # Arguments
    /// * `len` - The number of bytes to read.
    ///
    /// # Returns
    /// The read byte array or an IO error.
    pub fn read_bytes(&mut self, len: usize) -> std::io::Result<Vec<u8>> {
        let mut buf = vec![0u8; len];
        self.reader.read_exact(&mut buf)?;
        self.position += len as u64;
        Ok(buf)
    }

    /// Read a fixed-length byte array.
    ///
    /// # Returns
    /// Returns the read byte array or an IO error.
    pub fn read_array<const N: usize>(&mut self) -> std::io::Result<[u8; N]> {
        let mut buf = [0u8; N];
        self.reader.read_exact(&mut buf)?;
        self.position += N as u64;
        Ok(buf)
    }

    /// Skip the specified number of bytes.
    ///
    /// Note: This function will return an error if the underlying reader does not support Seek operations.
    ///
    /// # Arguments
    /// * `count` - The number of bytes to skip.
    ///
    /// # Returns
    /// Returns the operation result.
    pub fn skip(&mut self, count: u64) -> std::io::Result<u64>
    where
        R: Seek,
    {
        let new_pos = self.reader.seek(SeekFrom::Current(count as i64))?;
        self.position = new_pos;
        Ok(new_pos)
    }

    /// Read a LEB128 encoded unsigned 32-bit integer.
    ///
    /// # Returns
    /// Returns the read u32 value or an IO error.
    pub fn read_u32_leb128(&mut self) -> std::io::Result<u32> {
        let mut result = 0u32;
        let mut shift = 0;

        loop {
            let byte = self.read_u8()?;
            result |= ((byte & 0x7F) as u32) << shift;

            if byte & 0x80 == 0 {
                break;
            }

            shift += 7;
            if shift >= 32 {
                return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "LEB128 value too large for u32"));
            }
        }

        Ok(result)
    }

    /// Read a LEB128 encoded signed 32-bit integer.
    ///
    /// # Returns
    /// Returns the read i32 value or an IO error.
    pub fn read_i32_leb128(&mut self) -> std::io::Result<i32> {
        let mut result = 0i32;
        let mut shift = 0;
        let mut byte;

        loop {
            byte = self.read_u8()?;
            result |= ((byte & 0x7F) as i32) << shift;
            shift += 7;

            if byte & 0x80 == 0 {
                break;
            }

            if shift >= 32 {
                return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "LEB128 value too large for i32"));
            }
        }

        // Sign extension
        if shift < 32 && (byte & 0x40) != 0 {
            result |= !0 << shift;
        }

        Ok(result)
    }

    /// Read a LEB128 encoded signed 64-bit integer.
    ///
    /// # Returns
    /// Returns the read i64 value or an IO error.
    pub fn read_i64_leb128(&mut self) -> std::io::Result<i64> {
        let mut result = 0i64;
        let mut shift = 0;
        let mut byte;

        loop {
            byte = self.read_u8()?;
            result |= ((byte & 0x7F) as i64) << shift;
            shift += 7;

            if byte & 0x80 == 0 {
                break;
            }

            if shift >= 64 {
                return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "LEB128 value too large for i64"));
            }
        }

        // Sign extension
        if shift < 64 && (byte & 0x40) != 0 {
            result |= !0 << shift;
        }

        Ok(result)
    }
}

impl<R, E> BinaryReader<R, E> {
    /// Calculate the byte length of a LEB128 encoded value (static method).
    ///
    /// # Arguments
    /// * `value` - The value to calculate the length for.
    ///
    /// # Returns
    /// Returns the encoded byte length.
    pub fn leb128_size(mut value: u32) -> u32 {
        let mut size = 0;
        loop {
            value >>= 7;
            size += 1;
            if value == 0 {
                break;
            }
        }
        size
    }
}

/// Source code position information, representing the position of code in a source file.
///
/// This struct is used to track source code position information, including line number, column number, etc.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct SourcePosition {
    /// Line number, starting from 1.
    ///
    /// Represents the line number of the current position, the first line is 1.
    pub line: u32,
    /// Column number, starting from 1.
    ///
    /// Represents the column number of the current position, the first column is 1.
    pub column: u32,
    /// Byte offset, starting from 0.
    ///
    /// Represents the byte offset from the start of the file to the current position.
    pub offset: usize,
    /// Length, representing the number of bytes covered by this position.
    ///
    /// Usually used to represent the length of a token or symbol.
    pub length: usize,
}

/// Source location, including file URL and position information.
///
/// This struct extends SourcePosition by adding file URL information,
/// allowing it to represent the position of code in a specific file.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct SourceLocation {
    /// Line number, starting from 1.
    ///
    /// Represents the line number of the current position.
    pub line: u32,
    /// Column number, starting from 1.
    ///
    /// Represents the column number of the current position.
    pub column: u32,
    /// The URL of the source file, optional.
    ///
    /// If present, represents the URL or path of the file containing the code.
    /// Can be a filesystem path or a network URL.
    pub url: Option<Url>,
}

impl Default for SourceLocation {
    fn default() -> Self {
        Self { line: 1, column: 1, url: None }
    }
}