Solar Parse

https://docs.rs/solar-parse/latest/
Admin
Solar Parse is a Solidity and Yul lexer and parser implementation adapted from Rust compiler...
Tokens:758,016
Snippets:3,937
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Example: Parse Solidity File with Rust Parser

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates parsing a Solidity file using the `solar-parse` crate. This example requires the `solar` crate for `Session`, `ast`, and `interface` components. It initializes a session, sets up the parser from a file path, parses the file content, and returns any emitted diagnostics.

```rust
use solar::
    ast,
    interface::{Session, diagnostics::EmittedDiagnostics},
    parse::Parser;
use std::path::Path;

#[test]
fn main() -> Result<(), EmittedDiagnostics> {
    let path = Path::new("src/Counter.sol");

    // Create a new session with a buffer emitter.
    // This is required to capture the emitted diagnostics and to return them at the end.
    let sess = Session::builder().with_buffer_emitter(solar::interface::ColorChoice::Auto).build();

    // Enter the context and parse the file.
    let _ = sess.enter(|| -> solar::interface::Result<()> {
        // Set up the parser.
        let arena = ast::Arena::new();
        let mut parser = Parser::from_file(&sess, &arena, path)?;

        // Parse the file.
        let ast = parser.parse_file().map_err(|e| e.emit())?;
        println!("parsed {path:?}: {ast:#?}");
        Ok(())
    });

    // Return the emitted diagnostics as a `Result<(), _>`.
    // If any errors were emitted, this returns `Err(_)`, otherwise `Ok(())`.
    // Note that this discards warnings and other non-error diagnostics.
    sess.emitted_errors().unwrap()
}
```

--------------------------------

### Create Solidity Lexer

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=std%3A%3Avec

This code creates a new lexer instance for Solidity or Yul. It initializes the lexer with the source code and session information, along with the starting position. It provides methods for creating a lexer from a string or a source file, and also allows setting a starting position.

```rust
    /// Creates a new `Lexer` for the given source string.
    pub fn new(sess: &'sess Session, src: &'src str) -> Self {
        Self::with_start_pos(sess, src, BytePos(0))
    }

    /// Creates a new `Lexer` for the given source file.
    ///
    /// Note that the source file must be added to the source map before calling this function.
    pub fn from_source_file(sess: &'sess Session, file: &'src SourceFile) -> Self {
        Self::with_start_pos(sess, &file.src, file.start_pos)
    }

    /// Creates a new `Lexer` for the given source string and starting position.
    pub fn with_start_pos(sess: &'sess Session, src: &'src str, start_pos: BytePos) -> Self {
        assert!(sess.is_entered(), "session should be entered before lexing");
        Self {
            sess,
            start_pos,
            pos: start_pos,
            src,
            cursor: Cursor::new(src),
            nbsp_is_whitespace: false,
        }
    }
```

--------------------------------

### Lexer Initialization with Start Position (Rust)

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

A flexible constructor for `Lexer` that allows specifying a custom starting position for tokenization. It performs an assertion to ensure the session is properly entered, which is a prerequisite for lexing operations. This method is used internally by `new` and `from_source_file`.

```rust
pub fn with_start_pos(sess: &'sess Session, src: &'src str, start_pos: BytePos) -> Self {
        assert!(sess.is_entered(), "session should be entered before lexing");
        Self {
            sess,
            start_pos,
            pos: start_pos,
            src,
            cursor: Cursor::new(src),
            nbsp_is_whitespace: false,
        }
    }
```

--------------------------------

### Slice Source Text from Start (Rust)

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=std%3A%3Avec

This function creates a slice of the source text from a given start position up to but excluding the current position. It utilizes `str_from_to` to perform the slicing.

```Rust
fn str_from(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.pos)
}
```

--------------------------------

### Slice Source Text from Start (Rust)

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=std%3A%3Avec

This function creates a slice of the source text from a given start position up to but excluding the current position. It utilizes `symbol_from_to` to perform the slicing.

```Rust
fn symbol_from(&self, start: BytePos) -> Symbol {
    self.symbol_from_to(start, self.pos)
}
```

--------------------------------

### Get Symbol from to Position in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function extracts a symbol from the source text, from a start to an end position. It calls str_from_to to get the string slice and interns it.

```Rust
/// Same as `symbol_from`, with an explicit endpoint.
#[cfg_attr(debug_assertions, track_caller)]
fn symbol_from_to(&self, start: BytePos, end: BytePos) -> Symbol {
    self.intern(self.str_from_to(start, end))
}
```

--------------------------------

### Example: Parse Solidity File

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=u32+-%3E+bool

Demonstrates how to use the `Parser` to parse a Solidity file. It includes setting up a session, creating a parser instance from a file path, and handling potential parsing errors.

```rust
use solar::{
    ast,
    interface::{Session, diagnostics::EmittedDiagnostics},
    parse::Parser,
};
use std::path::Path;

#[test]
fn main() -> Result<(), EmittedDiagnostics> {
    let path = Path::new("src/Counter.sol");

    // Create a new session with a buffer emitter.
    // This is required to capture the emitted diagnostics and to return them at the end.
    let sess = Session::builder().with_buffer_emitter(solar::interface::ColorChoice::Auto).build();

    // Enter the context and parse the file.
    let _ = sess.enter(|| -> solar::interface::Result<()> {
        // Set up the parser.
        let arena = ast::Arena::new();
        let mut parser = Parser::from_file(&sess, &arena, path)?;

        // Parse the file.
        let ast = parser.parse_file().map_err(|e| e.emit())?;
        println!("parsed {path:?}: {ast:#?}");
        Ok(())
    });

    // Return the emitted diagnostics as a `Result<(), _>`.
    // If any errors were emitted, this returns `Err(_)`, otherwise `Ok(())`.
    // Note that this discards warnings and other non-error diagnostics.
    sess.emitted_errors().unwrap()
}
```

--------------------------------

### Get Symbol from to Position

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This function gets a symbol from a start and end position within the source text. The result is the interned string slice between these positions. This function is designed to extract and intern substrings.

```rust
#[cfg_attr(debug_assertions, track_caller)]
fn symbol_from_to(&self, start: BytePos, end: BytePos) -> Symbol {
    self.intern(self.str_from_to(start, end))
}
```

--------------------------------

### Lexer Initialization and Tokenization in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create and use the Lexer for tokenizing Solidity and Yul source code. It covers creating a Lexer from a string or a SourceFile and converting the lexed tokens into a vector, excluding comments.

```rust
use solar_ast::token::Token;
use solar_interface::{Session, SourceFile};

// Assuming Lexer and other necessary types are imported

// Example 1: Creating a Lexer from a string
let sess = Session::new(); // Assuming Session can be created like this
let src = "contract Test { uint a; }";
let mut lexer = Lexer::new(&sess, src);

// Example 2: Creating a Lexer from a SourceFile (assuming SourceFile is properly set up)
// let source_file = SourceFile { src: src.to_string(), ... };
// let mut lexer_from_file = Lexer::from_source_file(&sess, &source_file);

// Tokenizing the source code into a vector of tokens
let tokens: Vec<Token> = lexer.into_tokens();

println!("Number of tokens: {}", tokens.len());

```

--------------------------------

### Get String from Start to End

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This function slices the source text from a start position until the end of the source. It calculates the end position using the source length. The function returns a string slice.

```rust
#[cfg_attr(debug_assertions, track_caller)]
fn str_from_to_end(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.start_pos + BytePos::from_usize(self.src.len()))
}
```

--------------------------------

### Get String Slice by Start and End

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This function slices the source text from a start to an end position, excluding the end position character. It uses unsafe code in release builds for performance. The function returns a string slice.

```rust
#[cfg_attr(debug_assertions, track_caller)]
fn str_from_to(&self, start: BytePos, end: BytePos) -> &'src str {
    let range = self.src_index(start)..self.src_index(end);
    if cfg!(debug_assertions) {
        &self.src[range]
    } else {
        // SAFETY: Should never be out of bounds.
        unsafe { self.src.get_unchecked(range) }
    }
}
```

--------------------------------

### Rust Cursor Initialization and Methods

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Cursor_search=u32+-%3E+bool

Demonstrates how to create and use the `Cursor` struct in Rust. Includes methods for creating a new cursor, associating positions with tokens, and accessing the underlying input data.

```Rust
pub fn new(input: &'a str) -> Self
Creates a new cursor over the given input string slice.

pub fn with_position(self) -> CursorWithPosition<'a>
Creates a new iterator that also returns the position of each token in the input string.
Note that the position currently always starts at 0 when this method is called, so if called after tokens are parsed the position will be relative to when this method is called, not the beginning of the string.

pub fn slop(&mut self) -> RawToken
Slops up a token from the input string.
Advances the cursor by the length of the token. Prefer using `Cursor::with_position`, or using it as an iterator instead.

pub fn as_bytes(&self) -> &'a [u8]
Returns the remaining input as a byte slice.

pub fn as_ptr(&self) -> *const u8
Returns the pointer to the first byte of the remaining input.
```

--------------------------------

### Get Source Index - Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs

This inline function calculates the source index from a given byte position, relative to the starting position.  It converts the byte position to a usize and is used internally to access source text. The output represents the offset from the starting position.

```Rust
fn src_index(&self, pos: BytePos) -> usize {
    (pos - self.start_pos).to_usize()
}
```

--------------------------------

### Lexer Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Lexer

Provides methods for creating a new Lexer instance with different configurations.

```APIDOC
## Lexer Initialization

### `new(sess: &'sess Session, src: &'src str) -> Self`

Creates a new `Lexer` for the given source string.

### `from_source_file(sess: &'sess Session, file: &'src SourceFile) -> Self`

Creates a new `Lexer` for the given source file.
Note that the source file must be added to the source map before calling this function.

### `with_start_pos(sess: &'sess Session, src: &'src str, start_pos: BytePos) -> Self`

Creates a new `Lexer` for the given source string and starting position.
```

--------------------------------

### Get Source Index in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function calculates the index of a position within the source code. It subtracts the start position from the given position and converts the result to a usize.

```Rust
#[inline]
fn src_index(&self, pos: BytePos) -> usize {
    (pos - self.start_pos).to_usize()
}
```

--------------------------------

### Rust Crate Initialization and Re-exports

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lib.rs_search=

This snippet shows the initialization of the solar-parse Rust crate, including setting up documentation attributes, feature flags, and re-exporting essential modules and types. It re-exports modules like `lexer` and `parser`, as well as types from `solar_interface`, `ruint`, and `bumpalo`. It also defines convenience type aliases for parser errors and results.

```Rust
#![doc = include_str!("../README.md")]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/solar/main/assets/logo.png",
    html_favicon_url = "https://raw.githubusercontent.com/paradigmxyz/solar/main/assets/favicon.ico"
)]
#![cfg_attr(docsrs, feature(doc_cfg))]

// Feature flag.
use ruint as _;

#[macro_use]
extern crate tracing;

use solar_interface::diagnostics::{DiagBuilder, ErrorGuaranteed};

pub mod lexer;
pub use lexer::{Cursor, Lexer, unescape};

mod parser;
pub use parser::{Parser, Recovered};

// Convenience re-exports.
pub use bumpalo;
pub use solar_ast::{self as ast, token};
pub use solar_interface as interface;

/// Parser error type.
pub type PErr<'a> = DiagBuilder<'a, ErrorGuaranteed>;

/// Parser result type. This is a shorthand for `Result<T, PErr<'a>>`.
pub type PResult<'a, T> = Result<T, PErr<'a>>;
```

--------------------------------

### Slice Source Text between Positions (Rust)

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=std%3A%3Avec

This function slices the source text from a start position to an end position, returning a `Symbol`. It first gets the text slice using `str_from_to` and then interns it.

```Rust
fn symbol_from_to(&self, start: BytePos, end: BytePos) -> Symbol {
    self.intern(self.str_from_to(start, end))
}
```

--------------------------------

### Source Text Slicing in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=u32+-%3E+bool

The `symbol_from` and `str_from` methods extract slices of the source text from a starting position up to the current position. These methods are used for lexical analysis to get source code segments.

```rust
fn symbol_from(&self, start: BytePos) -> Symbol {
    self.symbol_from_to(start, self.pos)
}

fn str_from(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.pos)
}
```

--------------------------------

### Initialize Parser

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=u32+-%3E+bool

Provides methods for creating a `Parser` instance. This includes creating a new parser with a vector of tokens or initializing it from source code or a file path.

```rust
pub fn new(sess: &'sess Session, arena: &'ast Arena, tokens: Vec<Token>) -> Self>
```

```rust
pub fn from_source_code(
    sess: &'sess Session,
    arena: &'ast Arena,
    filename: FileName,
    src: impl Into<String>,
) -> Result<Self>
```

```rust
pub fn from_file(
    sess: &'sess Session,
    arena: &'ast Arena,
    path: &Path,
) -> Result<Self>
```

--------------------------------

### Rust DiagBuilder Highlighted Help Method

Source: https://docs.rs/solar-parse/latest/solar_parse/type.PErr_search=std%3A%3Avec

Explains the `highlighted_help` method for creating help messages with distinct styles for multiple parts. This allows for more visually structured and actionable help suggestions.

```rust
pub fn highlighted_help( self, messages: Vec<(impl Into<DiagMsg>, Style)>, ) -> DiagBuilder<'_, G>
```

--------------------------------

### Token Extraction in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=u32+-%3E+bool

This function extracts a token with rational kind from a source string. It uses `self.symbol_from_to` to get the token's text representation from start to end positions within the source code.

```rust
(TokenLitKind::Rational, self.symbol_from_to(start, end))
```

--------------------------------

### Parser Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for initializing the Parser, either from a file, source code, or a pre-existing token stream.

```APIDOC
## POST /initialize/parser/from_file

### Description
Creates a new parser instance from a file path.

### Method
POST

### Endpoint
`/initialize/parser/from_file`

### Parameters
#### Path Parameters
- **sess** (Session) - Required - The parser session.
- **arena** (Arena) - Required - The arena for AST node allocation.
- **path** (Path) - Required - The path to the source file.

### Request Body
```json
{
  "sess": "<Session object>",
  "arena": "<Arena object>",
  "path": "<file_path>"
}
```

### Response
#### Success Response (200)
- **parser** (Parser) - The initialized parser object.

#### Response Example
```json
{
  "parser": "<Parser object>"
}
```

## POST /initialize/parser/from_source_code

### Description
Creates a new parser instance from a source code string.

### Method
POST

### Endpoint
`/initialize/parser/from_source_code`

### Parameters
#### Path Parameters
- **sess** (Session) - Required - The parser session.
- **arena** (Arena) - Required - The arena for AST node allocation.
- **filename** (FileName) - Required - The name of the file being parsed.
- **src** (String) - Required - The source code content.

### Request Body
```json
{
  "sess": "<Session object>",
  "arena": "<Arena object>",
  "filename": "<file_name>",
  "src": "<source_code_string>"
}
```

### Response
#### Success Response (200)
- **parser** (Parser) - The initialized parser object.

#### Response Example
```json
{
  "parser": "<Parser object>"
}
```

## POST /initialize/parser/new

### Description
Creates a new parser instance with a provided token vector.

### Method
POST

### Endpoint
`/initialize/parser/new`

### Parameters
#### Path Parameters
- **sess** (Session) - Required - The parser session.
- **arena** (Arena) - Required - The arena for AST node allocation.
- **tokens** (Vec<Token>) - Required - A vector of tokens to be parsed.

### Request Body
```json
{
  "sess": "<Session object>",
  "arena": "<Arena object>",
  "tokens": "<Token vector>"
}
```

### Response
#### Success Response (200)
- **parser** (Parser) - The initialized parser object.

#### Response Example
```json
{
  "parser": "<Parser object>"
}
```
```

--------------------------------

### Get String Slice from to Position in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function extracts a string slice from the source text, between a start and an end position. It calculates the range within the source and uses get_unchecked for efficient access in release mode.

```Rust
/// Slice of the source text spanning from `start` up to but excluding `end`.
#[cfg_attr(debug_assertions, track_caller)]
fn str_from_to(&self, start: BytePos, end: BytePos) -> &'src str {
    let range = self.src_index(start)..self.src_index(end);
    if cfg!(debug_assertions) {
        &self.src[range]
    } else {
        // SAFETY: Should never be out of bounds.
        unsafe { self.src.get_unchecked(range) }
    }
}
```

--------------------------------

### Get String from to End Position in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function extracts a string slice from the source text, starting from a given position to the end of the source. It calculates the end position based on the source's length and then calls str_from_to.

```Rust
/// Slice of the source text spanning from `start` until the end.
#[cfg_attr(debug_assertions, track_caller)]
fn str_from_to_end(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.start_pos + BytePos::from_usize(self.src.len()))
}
```

--------------------------------

### TryFrom and TryInto Implementations

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Lexer_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for generic implementations of `TryFrom` and `TryInto` traits, facilitating fallible type conversions.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>

### Description
Provides a mechanism to attempt converting a type `U` into type `T`, where `U` can be converted into `T` via `Into`. This conversion can fail.

### Method
`fn`

### Endpoint
N/A (Trait implementation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Assuming MyStruct implements TryFrom<i32>
let value: i32 = 10;
match MyStruct::try_from(value) {
    Ok(instance) => println!("Conversion successful: {:?}", instance),
    Err(e) => println!("Conversion failed: {:?}", e),
}
```

### Response
#### Success Response (200)
- `Result<T, <T as TryFrom<U>>::Error>`: Ok containing the converted value of type `T` or Err containing the conversion error.

#### Response Example
```rust
// Example successful result
// Ok(MyStruct { ... })

// Example error result
// Err(MyError::InvalidValue)
```

## impl<T, U> TryInto<U> for T
where U: TryFrom<T>

### Description
Provides a mechanism to attempt converting a type `T` into type `U`, where `U` can be converted from `T` via `TryFrom`. This conversion can fail.

### Method
`fn`

### Endpoint
N/A (Trait implementation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Assuming MyOtherStruct implements TryFrom<MyStruct>
let instance: MyStruct = MyStruct { ... };
match instance.try_into() {
    Ok(converted_value) => println!("Conversion successful: {:?}", converted_value),
    Err(e) => println!("Conversion failed: {:?}", e),
}
```

### Response
#### Success Response (200)
- `Result<U, <U as TryFrom<T>>::Error>`: Ok containing the converted value of type `U` or Err containing the conversion error.

#### Response Example
```rust
// Example successful result
// Ok(MyOtherStruct { ... })

// Example error result
// Err(AnotherError::ConversionFailed)
```
```

--------------------------------

### Get Symbol from to Position

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This function slices the source text from a start position to the current position and returns a symbol. It calls the `str_from_to` function internally and interns the result. The function's main purpose is to extract a substring based on byte positions.

```rust
#[cfg_attr(debug_assertions, track_caller)]
fn symbol_from(&self, start: BytePos) -> Symbol {
    self.symbol_from_to(start, self.pos)
}
```

--------------------------------

### Lexer Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Lexer_search=u32+-%3E+bool

Methods for creating a new Lexer instance for processing source code.

```APIDOC
## Lexer Initialization

### `new`

Creates a new `Lexer` for the given source string.

### Method

```
pub fn new<'sess, 'src>(sess: &'sess Session, src: &'src str) -> Self
```

### Parameters

#### Path Parameters

- **sess** (`&'sess Session`) - Required - A session context for diagnostics.
- **src** (`&'src str`) - Required - The source code string to lex.

### `from_source_file`

Creates a new `Lexer` for the given source file.

Note that the source file must be added to the source map before calling this function.

### Method

```
pub fn from_source_file<'sess, 'src>(sess: &'sess Session, file: &'src SourceFile) -> Self
```

### Parameters

#### Path Parameters

- **sess** (`&'sess Session`) - Required - A session context for diagnostics.
- **file** (`&'src SourceFile`) - Required - The source file to lex.

### `with_start_pos`

Creates a new `Lexer` for the given source string and starting position.

### Method

```
pub fn with_start_pos<'sess, 'src>(sess: &'sess Session, src: &'src str, start_pos: BytePos) -> Self
```

### Parameters

#### Path Parameters

- **sess** (`&'sess Session`) - Required - A session context for diagnostics.
- **src** (`&'src str`) - Required - The source code string to lex.
- **start_pos** (`BytePos`) - Required - The starting byte position for lexing.

```

--------------------------------

### Lexer Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Lexer_search=

Provides methods to create a new Lexer instance for processing source code.

```APIDOC
## POST /lexer/new

### Description
Creates a new `Lexer` for the given source string.

### Method
POST

### Endpoint
/lexer/new

### Parameters
#### Request Body
- **sess** (object) - Required - Session context.
- **src** (string) - Required - The source code string to lex.

### Request Example
```json
{
  "sess": {}, 
  "src": "contract MyContract { uint x; }"
}
```

### Response
#### Success Response (200)
- **lexer_id** (string) - A unique identifier for the created lexer instance.

#### Response Example
```json
{
  "lexer_id": "lexer_12345"
}
```

## POST /lexer/from_source_file

### Description
Creates a new `Lexer` for the given source file. The source file must be added to the source map before calling this function.

### Method
POST

### Endpoint
/lexer/from_source_file

### Parameters
#### Request Body
- **sess** (object) - Required - Session context.
- **file** (object) - Required - The source file object.

### Request Example
```json
{
  "sess": {}, 
  "file": { "name": "MyContract.sol", "source": "contract MyContract { uint x; }" }
}
```

### Response
#### Success Response (200)
- **lexer_id** (string) - A unique identifier for the created lexer instance.

#### Response Example
```json
{
  "lexer_id": "lexer_67890"
}
```

## POST /lexer/with_start_pos

### Description
Creates a new `Lexer` for the given source string and starting position.

### Method
POST

### Endpoint
/lexer/with_start_pos

### Parameters
#### Request Body
- **sess** (object) - Required - Session context.
- **src** (string) - Required - The source code string to lex.
- **start_pos** (integer) - Required - The starting byte position in the source string.

### Request Example
```json
{
  "sess": {}, 
  "src": "contract MyContract { uint x; }", 
  "start_pos": 10
}
```

### Response
#### Success Response (200)
- **lexer_id** (string) - A unique identifier for the created lexer instance.

#### Response Example
```json
{
  "lexer_id": "lexer_abcde"
}
```
```

--------------------------------

### Get Symbol from Range - Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs

These functions slice source text to create a Symbol. `symbol_from` and `symbol_from_to` create a symbol from the source text, taking start and end byte positions as input. `str_from` and `str_from_to` perform similar actions, returning string slices instead.

```Rust
fn symbol_from(&self, start: BytePos) -> Symbol {
    self.symbol_from_to(start, self.pos)
}
```

```Rust
fn str_from(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.pos)
}
```

```Rust
fn symbol_from_to(&self, start: BytePos, end: BytePos) -> Symbol {
    self.intern(self.str_from_to(start, end))
}
```

```Rust
fn str_from_to_end(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.start_pos + BytePos::from_usize(self.src.len()))
}
```

```Rust
fn str_from_to(&self, start: BytePos, end: BytePos) -> &'src str {
    let range = self.src_index(start)..self.src_index(end);
    if cfg!(debug_assertions) {
        &self.src[range]
    } else {
        unsafe { self.src.get_unchecked(range) }
    }
}
```

--------------------------------

### PResult Implementations and Methods

Source: https://docs.rs/solar-parse/latest/solar_parse/type.PResult_search=

Documentation for various implementations of `Result` that are relevant to `PResult`, including methods for copying, cloning, transposing, flattening, and checking the status of the result.

```APIDOC
## Implementations for Result

### `impl<T, E> Result<&T, E>`

#### `copied(self) -> Result<T, E>`
Maps a `Result<&T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### `cloned(self) -> Result<T, E>`
Maps a `Result<&T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### `impl<T, E> Result<&mut T, E>`

#### `copied(self) -> Result<T, E>`
Maps a `Result<&mut T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### `cloned(self) -> Result<T, E>`
Maps a `Result<&mut T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### `impl<T, E> Result<Option<T>, E>`

#### `transpose(self) -> Option<Result<T, E>>`
Transposes a `Result` of an `Option` into an `Option` of a `Result`. `Ok(None)` will be mapped to `None`. `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))`.

##### Examples
```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

### `impl<T, E> Result<Result<T, E>, E>`

#### `flatten(self) -> Result<T, E>`
Converts from `Result<Result<T, E>, E>` to `Result<T, E>`.

##### Examples
```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());

// Flattening only removes one level of nesting at a time:
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

### `impl<T, E> Result<T, E>`

#### `is_ok(&self) -> bool`
Returns `true` if the result is `Ok`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

#### `is_ok_and<F>(self, f: F) -> bool` where F: FnOnce(T) -> bool
Returns `true` if the result is `Ok` and the value inside of it matches a predicate.

##### Examples
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);
```

#### `is_err(&self) -> bool`
Returns `true` if the result is `Err`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

#### `is_err_and<F>(self, f: F) -> bool` where F: FnOnce(E) -> bool
Returns `true` if the result is `Err` and the value inside of it matches a predicate.
```

--------------------------------

### Handle File Metadata Errors with Result::and_then

Source: https://docs.rs/solar-parse/latest/solar_parse/type.PResult_search=u32+-%3E+bool

Illustrates using `and_then` with `Path::metadata` to chain fallible file system operations. It attempts to get metadata for the root directory and a non-existent path. The example shows successful retrieval for the root and an expected `NotFound` error for the bad path, demonstrating error kind checking.

```Rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Identifier Start Byte Check

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/fn.is_id_start_byte

Checks if a given byte is a valid start character for a Solidity identifier.

```APIDOC
## is_id_start_byte

### Description
Returns `true` if the given character is valid at the start of a Solidity identifier.

### Function Signature
```rust
pub const fn is_id_start_byte(c: u8) -> bool
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Request Example
*Not applicable for this function.*

### Response
#### Success Response (200)
* **Return Value** (bool) - `true` if the byte is a valid identifier start, `false` otherwise.

#### Response Example
*Not applicable for this function.*

### Error Handling
*Not applicable for this function.*
```

--------------------------------

### TryFrom and TryInto Implementations

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Lexer_search=

Documentation for the `TryFrom` and `TryInto` trait implementations, enabling fallible type conversions.

```APIDOC
### impl<T, U> TryFrom<U> for T
where U: Into<T>

#### Description
Provides a mechanism to perform fallible conversions from type `U` into type `T`.

#### Type Alias
`type Error = Infallible`
The type returned in the event of a conversion error. `Infallible` indicates that this conversion will never fail.

#### Method
`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`
Performs the conversion from `U` to `T`.

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>

#### Description
Provides a mechanism to perform fallible conversions from type `T` into type `U`.

#### Type Alias
`type Error = <U as TryFrom<T>>::Error`
The type returned in the event of a conversion error.

#### Method
`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`
Performs the conversion from `T` to `U`.
```

--------------------------------

### Rust BinOpToken Clone and Copy Implementations

Source: https://docs.rs/solar-parse/latest/solar_parse/token/enum.BinOpToken_search=

Demonstrates the Clone and Copy trait implementations for BinOpToken. This allows tokens to be duplicated efficiently, either by explicit cloning or implicit copying.

```Rust
impl Clone for BinOpToken {
    fn clone(&self) -> BinOpToken
    fn clone_from(&mut self, source: &Self)
}

impl Copy for BinOpToken
```

--------------------------------

### Parse Indexing Expression (Rust)

Source: https://docs.rs/solar-parse/latest/src/solar_parse/parser/expr.rs_search=std%3A%3Avec

Parses Rust indexing expressions, which can include simple indices or ranges within square brackets. It handles cases like `expr[]`, `expr[start]`, `expr[start:end]`, `expr[:end]`, and `expr[start:]`. This function is essential for parsing array or slice access.

```rust
    /// Parses a `[]` indexing expression.
    pub(super) fn parse_expr_index_kind(&mut self) -> PResult<'sess, IndexKind<'ast>> {
        self.expect(TokenKind::OpenDelim(Delimiter::Bracket))?;
        let kind = if self.check(TokenKind::CloseDelim(Delimiter::Bracket)) {
            // expr[]
            IndexKind::Index(None)
        } else {
            let start = if self.check(TokenKind::Colon) { None } else { Some(self.parse_expr()?) };
            if self.eat_noexpect(TokenKind::Colon) {
                // expr[start?:end?]
                let end = if self.check(TokenKind::CloseDelim(Delimiter::Bracket)) {
                    None
                } else {
                    Some(self.parse_expr()?)
                };
                IndexKind::Range(start, end)
            } else {
                // expr[start?]
                IndexKind::Index(start)
            }
        };
        self.expect(TokenKind::CloseDelim(Delimiter::Bracket))?;
        Ok(kind)
    }
```

--------------------------------

### Parser Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=

Methods for creating a new parser instance from different sources.

```APIDOC
## `from_lazy_source_code`

### Description
Creates a new parser from a source code closure. The closure will not be called if the file name has already been added into the source map.

### Method
`pub fn from_lazy_source_code`

### Parameters
- `sess` ('sess Session) - Session context.
- `arena` ('ast Arena) - AST arena for allocation.
- `filename` (FileName) - The name of the file being parsed.
- `get_src` (impl FnOnce() -> Result<String>) - A closure that returns the source code.

### Returns
`Result<Self>` - A new parser instance or an error.
```

```APIDOC
## `from_source_file`

### Description
Creates a new parser from a source file. Note that the source file must be added to the source map before calling this function. Prefer using `from_source_code` or `from_file` instead.

### Method
`pub fn from_source_file`

### Parameters
- `sess` ('sess Session) - Session context.
- `arena` ('ast Arena) - AST arena for allocation.
- `file` (&SourceFile) - The source file to parse.

### Returns
`Self` - A new parser instance.
```

```APIDOC
## `from_lexer`

### Description
Creates a new parser from a lexer.

### Method
`pub fn from_lexer`

### Parameters
- `arena` ('ast Arena) - AST arena for allocation.
- `lexer` (Lexer<'sess, '_>) - The lexer to use for parsing.

### Returns
`Self` - A new parser instance.
```

--------------------------------

### Get Current Character in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/parser/item.rs_search=u32+-%3E+bool

Retrieves the current character being processed by the parser. It relies on `current_str` to get the string slice and then extracts the first character.

```rust
fn current_char(&self) -> Option<char> {
        self.current_str()?.chars().next()
    }
```

--------------------------------

### Parser Initialization

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=std%3A%3Avec

Methods for creating a new parser instance from different sources.

```APIDOC
## `from_lazy_source_code`

### Description
Creates a new parser from a source code closure. The closure will not be called if the file name has already been added into the source map.

### Method
`pub fn from_lazy_source_code(&'sess Session, &'ast Arena, FileName, impl FnOnce() -> Result<String>) -> Result<Self>`

### Parameters
* `sess` (*&'sess Session*) - The session context.
* `arena` (*&'ast Arena*) - The AST arena for allocations.
* `filename` (*FileName*) - The name of the file being parsed.
* `get_src` (*impl FnOnce() -> Result<String>*) - A closure that provides the source code string.

### Response
#### Success Response (Result<Self>)
* `Self` - A new parser instance.

### Source
[Link to source code]
```

```APIDOC
## `from_source_file`

### Description
Creates a new parser from a source file. Note that the source file must be added to the source map before calling this function. Prefer using `from_source_code` or `from_file` instead.

### Method
`pub fn from_source_file(&'sess Session, &'ast Arena, &SourceFile) -> Self`

### Parameters
* `sess` (*&'sess Session*) - The session context.
* `arena` (*&'ast Arena*) - The AST arena for allocations.
* `file` (*&SourceFile*) - The source file to parse.

### Response
#### Success Response (Self)
* `Self` - A new parser instance.

### Source
[Link to source code]
```

```APIDOC
## `from_lexer`

### Description
Creates a new parser from a lexer.

### Method
`pub fn from_lexer(&'ast Arena, Lexer<'sess, '_>) -> Self`

### Parameters
* `arena` (*&'ast Arena*) - The AST arena for allocations.
* `lexer` (*Lexer<'sess, '_>*) - The lexer to use for tokenization.

### Response
#### Success Response (Self)
* `Self` - A new parser instance.

### Source
[Link to source code]
```

--------------------------------

### Check and Get Identifier or Error - Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/parser/mod.rs_search=std%3A%3Avec

Attempts to get an identifier from the current token. If the token is not an identifier, it returns an error, optionally attempting to recover. This is a core function for identifier parsing.

```rust
/// Returns Ok if the current token is an identifier. Does not advance the parser.
    #[track_caller]
    fn ident_or_err(&mut self, recover: bool) -> PResult<'sess, Ident> {
        match self.token.ident() {
            Some(ident) => Ok(ident),
            None => self.expected_ident_found(recover),
        }
    }

    #[cold]
    #[track_caller]
    fn expected_ident_found(&mut self, recover: bool) -> PResult<'sess, Ident> {
        self.expected_ident_found_other(self.token, recover)
    }

    #[cold]
    #[track_caller]
    fn expected_ident_found_other(&mut self, token: Token, recover: bool) -> PResult<'sess, Ident> {
        let msg = format!("expected identifier, found {}", token.full_description());
        // In a real scenario, this would likely involve creating and returning an error type
        // For this example, we'll just return a placeholder or panic if not recoverable
        if recover {
             // Placeholder for error emission
             Err(ParseError::new(token.span, msg)) // Assuming ParseError exists
        } else {
             Err(ParseError::new(token.span, msg))
        }
    }
```

--------------------------------

### Get String from to Position in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function extracts a string slice from the source text, up to a given position. It internally calls str_from_to to get a string slice.

```Rust
/// Slice of the source text from `start` up to but excluding `self.pos`,
/// meaning the slice does not include the character `self.ch`.
#[cfg_attr(debug_assertions, track_caller)]
fn str_from(&self, start: BytePos) -> &'src str {
    self.str_from_to(start, self.pos)
}
```

--------------------------------

### Parser Creation Methods

Source: https://docs.rs/solar-parse/latest/solar_parse/struct.Parser_search=u32+-%3E+bool

Methods for initializing a parser instance using different sources like source code closures, source files, or lexers.

```APIDOC
## `from_lazy_source_code`

### Description
Creates a new parser from a source code closure. The closure will not be called if the file name has already been added into the source map.

### Method
`pub fn from_lazy_source_code`

### Parameters
- `sess` ('sess Session) - The session context.
- `arena` ('ast Arena) - The AST arena for allocation.
- `filename` (FileName) - The name of the file being parsed.
- `get_src` (impl FnOnce() -> Result<String>) - A closure that returns the source code string.

### Returns
`Result<Self>` - A new parser instance or an error.
```

```APIDOC
## `from_source_file`

### Description
Creates a new parser from a source file. The source file must be added to the source map before calling this function. Prefer using `from_source_code` or `from_file` instead.

### Method
`pub fn from_source_file`

### Parameters
- `sess` ('sess Session) - The session context.
- `arena` ('ast Arena) - The AST arena for allocation.
- `file` (&SourceFile) - The source file to parse from.

### Returns
`Self` - A new parser instance.
```

```APIDOC
## `from_lexer`

### Description
Creates a new parser from a lexer.

### Method
`pub fn from_lexer`

### Parameters
- `arena` ('ast Arena) - The AST arena for allocation.
- `lexer` (Lexer<'sess, '_>) - The lexer to use for parsing.

### Returns
`Self` - A new parser instance.
```

--------------------------------

### Get Symbol from to Position in Rust

Source: https://docs.rs/solar-parse/latest/src/solar_parse/lexer/mod.rs_search=

This function extracts a symbol from the source text, up to a given position. It internally calls str_from_to to get a string slice and then interns it.

```Rust
/// Slice of the source text from `start` up to but excluding `self.pos`,
/// meaning the slice does not include the character `self.ch`.
#[cfg_attr(debug_assertions, track_caller)]
fn symbol_from(&self, start: BytePos) -> Symbol {
    self.symbol_from_to(start, self.pos)
}
```

--------------------------------

### Pad Using

Source: https://docs.rs/solar-parse/latest/solar_parse/lexer/struct.Cursor_search=

Pads a sequence to a minimum length by filling missing elements using a closure.

```APIDOC
## fn pad_using<F>(self, min: usize, f: F) -> PadUsing<Self, F>

### Description
Returns an iterator adaptor that pads the sequence to a minimum length of `min` by filling missing elements using a closure `f`.

### Method
(Implicitly available via trait extension)

### Endpoint
N/A (In-memory operation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
An iterator yielding elements padded to the specified minimum length.
```
Tokens:
Raw