Enum PreprocessorError 

pub enum PreprocessorError<'a> {
    Endif {
        endif_span: Span<'a>,
    },
    NoEndif {
        cond_token: Token<'a>,
        cond_token_span: Span<'a>,
    },
    Elsif {
        elsif_span: Span<'a>,
    },
    Else {
        else_span: Span<'a>,
    },
    EndKeywords {
        end_keywords_span: Span<'a>,
    },
    NoEndKeywords {
        begin_keywords_span: Span<'a>,
    },
    InvalidDefineParameter {
        other_token: Token<'a>,
        other_span: Span<'a>,
    },
    InvalidDefineArgument {
        other_token: Token<'a>,
        other_span: Span<'a>,
    },
    InvalidVersionSpecifier {
        invalid_version: Token<'a>,
        invalid_version_span: Span<'a>,
    },
    IncompleteDirective {
        directive_span: Span<'a>,
    },
    IncompleteDefine {
        other_token: Token<'a>,
        other_span: Span<'a>,
    },
    UndefinedMacro {
        undefined_name: &'a str,
        undefined_span: Span<'a>,
    },
    DuplicateMacroParameter {
        define_name: &'a str,
        param_name: &'a str,
        dup_span: Span<'a>,
        prev_span: Span<'a>,
    },
    NoDefaultAfterDefault {
        default_param: &'a str,
        default_param_span: Span<'a>,
        non_default_param: &'a str,
        non_default_param_span: Span<'a>,
    },
    NoMacroArguments {
        macro_name: &'a str,
        define_span: Span<'a>,
        use_span: Span<'a>,
    },
    TooManyMacroArguments {
        macro_name: &'a str,
        define_span: Span<'a>,
        use_span: Span<'a>,
        expected: usize,
        found: usize,
    },
    MissingMacroArgument {
        define_span: Span<'a>,
        use_span: Span<'a>,
        param_name: &'a str,
    },
    InvalidIdentifierFormation {
        param_name: &'a str,
        arg_span: Span<'a>,
    },
    InvalidRelativeTimescales {
        timescale_span: Span<'a>,
    },
    IncompleteMacroWithToken {
        error_token: Token<'a>,
        error_span: Span<'a>,
    },
    Include {
        include_path: &'a str,
        include_path_span: Span<'a>,
        read_err: ErrorKind,
    },
    IncludeDepth {
        include_span: Span<'a>,
    },
    VerboseError {
        err: VerboseError<'a>,
    },
    NotPreviouslyDefinedMacro {
        macro_name: &'a str,
        macro_span: Span<'a>,
    },
    RedefinedMacro {
        macro_name: &'a str,
        redef_span: Span<'a>,
        prev_def_span: Span<'a>,
    },
    NewlineInDefine(Span<'a>),
    EndOfFunctionArgument(SpannedToken<'a>),
}

An error encountered during preprocessing

As preprocessing can affect the interpretation of later source code, these errors are often irrecoverable

Errors marked with INTERNAL are meant for use inside the preprocessor for passing information, and should not be returned

Variants

Endif

An `endif encountered outside a conditional preprocessor block

let source = "
`endif
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::Endif{ .. })));

Fields

endif_span: Span<'a>

The Span of the `endif

NoEndif

No terminating `endif for a conditional preprocessor block

let source = "
`ifdef TEST
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::NoEndif{
    cond_token: Token::DirIfdef,
    ..
})));

Fields

cond_token: Token<'a>

The conditional token (either Token::DirIfdef, Token::DirIfndef, Token::DirElsif, or Token::DirElse) with no matching `endif

cond_token_span: Span<'a>

The Span of the conditional token

Elsif

An `elsif encountered outside a conditional preprocessor block

let source = "
`elsif
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::Elsif{ .. })));

Fields

elsif_span: Span<'a>

The Span of the `elsif

Else

An `else encountered outside a conditional preprocessor block

let source = "
`else
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::Else{ .. })));

Fields

else_span: Span<'a>

The Span of the `else

EndKeywords

An `end_keywords encountered outside a `begin_keywords block

let source = "
`end_keywords
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::EndKeywords{ .. })));

Fields

end_keywords_span: Span<'a>

The Span of the `end_keywords

NoEndKeywords

No terminating `end_keywords for a `begin_keywords block

let source = "
`begin_keywords \"1800-2009\"
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::NoEndKeywords{ .. })));

Fields

begin_keywords_span: Span<'a>

The Span of the unterminated `begin_keywords

InvalidDefineParameter

A missing parameter in a `define function declaration where one is expected

let source = "
`define TEST()
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::InvalidDefineParameter{
    other_token: Token::EParen,
    ..
})));

Fields

other_token: Token<'a>

The Token found instead of the `define parameter

other_span: Span<'a>

The Span of the token found instead

InvalidDefineArgument

A missing or invalid argument specification in a `define function

let source = "
`define TEST(a, b c)
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::InvalidDefineArgument{
    other_token: Token::SimpleIdentifier("c"),
    ..
})));

Fields

other_token: Token<'a>

The Token found instead of the valid `define argument

other_span: Span<'a>

The Span of the token found instead

InvalidVersionSpecifier

An invalid version specifier for a `begin_keywords directive

let source = "
`begin_keywords \"MyVersion\"
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::InvalidVersionSpecifier{
    invalid_version: Token::StringLiteral("MyVersion"),
    ..
})));

Fields

invalid_version: Token<'a>

The Token provided instead of a valid version specifier

If the token is a Token::StringLiteral, the string isn’t a version recognized by 1800-2023

invalid_version_span: Span<'a>

The Span of the invalid version specifier

IncompleteDirective

A directive that doesn’t have all of the required components

In general, PreprocessorError::VerboseError is preferred, but may not be suitable due to a lack of subsequent tokens

let source = "`line";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::IncompleteDirective{ .. })));

Fields

directive_span: Span<'a>

The Span of the incomplete preprocessor directive

This is usually the primary directive, but can be other more indicative tokens as well, such as an unmatched opening parenthesis

IncompleteDefine

An incomplete preprocessor definition, specifically with function macro arguments

let source = "
`define TEST(
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::IncompleteDefine{
    other_token: Token::Paren,
    ..
})));

Fields

other_token: Token<'a>

If known, the Token found instead of a valid function macro argument specification

In the case that the token wasn’t tracked, the opening Token::Paren is referenced instead

other_span: Span<'a>

The Span of the token found instead

UndefinedMacro

Use of a text macro that wasn’t previously defined

let source = "
`TEST
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::UndefinedMacro{
    undefined_name: "TEST",
    ..
})));

Fields

undefined_name: &'a str

The name of the undefined macro

undefined_span: Span<'a>

The Span of the undefined macro

DuplicateMacroParameter

Specifying a macro parameter that was already specified

let source = "
`define TEST(a, b, a) a + b
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::DuplicateMacroParameter{
    define_name: "TEST",
    param_name: "a",
    ..
})));

Fields

define_name: &'a str

The name of the macro for which duplicate parameters were specified

param_name: &'a str

The name of the parameter that was specified multiple times

dup_span: Span<'a>

The Span of the duplicate specification

prev_span: Span<'a>

The Span of the previous/original specification

NoDefaultAfterDefault

Attempting to have a macro parameter with no default value after one that does

let source = "
`define TEST(a = 1, b) a + b
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::NoDefaultAfterDefault{
    default_param: "a",
    non_default_param: "b",
    ..
})));

Fields

default_param: &'a str

The name of the previously-specified default parameter

default_param_span: Span<'a>

The Span of the previously-specified default parameter

non_default_param: &'a str

The name of the non-default parameter

non_default_param_span: Span<'a>

The Span of the non-default parameter

NoMacroArguments

Specifying no arguments for a macro function that takes arguments

let source = "
`define TEST(a, b) a + b
`TEST
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::NoMacroArguments{
    macro_name: "TEST",
    ..
})));

Fields

macro_name: &'a str

The name of the macro

define_span: Span<'a>

The Span of the macro definition (with arguments)

use_span: Span<'a>

The Span where the macro was used with no arguments

TooManyMacroArguments

Specifying too many arguments for a macro function

let source = "
`define TEST(a, b) a + b
`TEST(1, 2, 3)
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::TooManyMacroArguments{
    macro_name: "TEST",
    expected: 2,
    found: 3,
    ..
})));

Fields

macro_name: &'a str

The name of the macro

define_span: Span<'a>

The Span of the macro definition

use_span: Span<'a>

The Span where the macro was used with too many arguments

expected: usize

How many arguments were expected

found: usize

How many arguments were found

MissingMacroArgument

Missing an argument in a macro function use

let source = "
`define TEST(a, b) a + b
`TEST(1)
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::MissingMacroArgument{
    param_name: "b",
    ..
})));

Fields

define_span: Span<'a>

The Span of the macro definition

use_span: Span<'a>

The Span where the macro was used with a missing argument

param_name: &'a str

The name of the missing parameter

InvalidIdentifierFormation

An invalid preprocessor identifier specification

let source = "
`define TEST(a, b) a``_with_``b
`TEST(\"one\", \"two\")
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::InvalidIdentifierFormation{
    param_name: "a",
    ..
})));

Fields

param_name: &'a str

The name of the parameter used in a preprocessor identifier

arg_span: Span<'a>

The Span of the invalid argument

InvalidRelativeTimescales

A precision that is less precise than the unit in a `timescale directive

let source = "
`timescale 100 fs / 1 s
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::InvalidRelativeTimescales{ .. })));

Fields

timescale_span: Span<'a>

The Span of the `timescale directive

IncompleteMacroWithToken

An incomplete macro due to mismatching grouping tokens ([], (), or {})

let source = "
`define TEST(a, b) a + b
`TEST(a = 1, b = 2])
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::IncompleteMacroWithToken{
    error_token: Token::EBracket,
    ..
})));

Fields

error_token: Token<'a>

The error-causing Token (either Token::EParen, Token::EBracket, or Token::EBrace)

error_span: Span<'a>

The error-causing Span

Include

An error reading a file specified by an `include macro

let source = "
`include \"other.v\"
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::Include{
    include_path: "other.v",
    ..
})));

Fields

include_path: &'a str

The path for the `include directive

include_path_span: Span<'a>

The Span of the include path

read_err: ErrorKind

The io::ErrorKind raised when attempting to read the file

IncludeDepth

The maximum include depth was hit, likely as a result of a self-referential `include sequence

let source = "
`include \"test.v\"
";
state.retain_file(
    "test.v".to_string(),
    source.to_string(),
    &cache,
);
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::IncludeDepth{ .. })));

Fields

include_span: Span<'a>

The Span of the `include directive that exceeded the limit

VerboseError

A VerboseError detailing the expected and found tokens, for a case not covered above

This is most commonly used when we can provide the user with a bit more context

let source = "
`line
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
// Expects a line number
assert!(preprocess_result.is_err());
assert!(matches!(state.errors.first(), Some(PreprocessorError::VerboseError{
    err: VerboseError{
        found: Some(Token::Newline),
        ..
    }
})));

Fields

err: VerboseError<'a>

The VerboseError for the preprocessor error

NotPreviouslyDefinedMacro

Attempted to `undef a macro that had no previous definition

let source = "
`undef TEST
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_ok());
assert!(matches!(state.errors.first(), Some(PreprocessorError::NotPreviouslyDefinedMacro{
    macro_name: "TEST",
    ..
})))

Fields

macro_name: &'a str

The name that wasn’t previously defined

macro_span: Span<'a>

The Span where the not-previously-defined name was specified

RedefinedMacro

A redefinition of a text macro that was previously defined

let source = "
`define TEST definition_one
`define TEST definition_two
";
let input = lex(source, "test.v").tokens();
let preprocess_result = preprocess(
    input,
    &mut state,
    &cache,
);
assert!(preprocess_result.is_ok());
assert!(matches!(state.errors.first(), Some(PreprocessorError::RedefinedMacro{
    macro_name: "TEST",
    ..
})))

Fields

macro_name: &'a str

The name of the macro being redefined

redef_span: Span<'a>

The Span of the redefinition

prev_def_span: Span<'a>

The Span where the macro was previously defined

NewlineInDefine(Span<'a>)

INTERNAL: A newline encountered in a `define directive

EndOfFunctionArgument(SpannedToken<'a>)

INTERNAL: The end of a function argument was encountered

Implementations

impl<'a> PreprocessorError<'a>

pub fn is_warning(&self) -> bool

Whether the given PreprocessorError is just a warning

Warnings reflect an irregularity in the source code, but are still well-defined and allow preprocessing to continue

Trait Implementations

impl<'a> Clone for PreprocessorError<'a>

fn clone(&self) -> PreprocessorError<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for PreprocessorError<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'s> From<&PreprocessorError<'s>> for Report

fn from(s: &PreprocessorError<'s>) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for PreprocessorError<'a>

fn eq(&self, other: &PreprocessorError<'a>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for PreprocessorError<'a>