Struct Compiler 

pub struct Compiler<'a> { /* private fields */ }

Compiles YARA source code producing a set of compiled Rules.

The two most important methods in this type are Compiler::add_source and Compiler::build. The former tells the compiler which YARA source code must be compiled, and can be called multiple times with different set of rules. The latter consumes the compiler and produces a set of compiled Rules.

Example

let mut compiler = yara_x::Compiler::new();

compiler
    .add_source(r#"
        rule always_true {
            condition: true
        }"#)?
    .add_source(r#"
        rule always_false {
            condition: false
        }"#)?;

let rules = compiler.build();

Implementations

impl<'a> Compiler<'a>

pub fn new() -> Self

Creates a new YARA compiler.

pub fn add_include_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self

Adds a directory to the list of directories where the compiler should look for included files.

When an include statement is found, the compiler looks for the included file in the directories added with this function, in the order they were added.

If this function is not called, the compiler will only look for included files in the current directory.

Use Compiler::enable_includes for controlling whether include statements are allowed or not.

Example

let mut compiler = Compiler::new();
compiler.add_include_dir("/path/to/rules")
        .add_include_dir("/another/path");

pub fn add_source<'src, S>(&mut self, src: S) -> Result<&mut Self, CompileError>

where S: Into<SourceCode<'src>>,

Adds some YARA source code to be compiled.

The src parameter accepts any type that implements Into<SourceCode>, such as &str, &[u8], or an instance of SourceCode itself. The source code may include one or more YARA rules.

You can call this function multiple times to add different sets of rules. If the provided source code contains syntax or semantic errors that prevent compilation, the function returns the first encountered error. All errors found during compilation are also recorded and can be retrieved using Compiler::errors.

Even if previous calls to this function resulted in compilation errors, you may continue adding additional rules. Only successfully compiled rules will be included in the final rule set.

pub fn define_global<T: TryInto<Variable>>( &mut self, ident: &str, value: T, ) -> Result<&mut Self, VariableError>

where VariableError: From<<T as TryInto<Variable>>::Error>,

Defines a global variable and sets its initial value.

Global variables must be defined before adding any YARA source code that references them via Compiler::add_source. Once defined, the variable’s initial value is preserved in the compiled Rules and will be used unless overridden.

When scanning, each scanner instance can modify the initial value of the variable using crate::Scanner::set_global.

T can be any type that implements TryInto<Variable>, including: i64, i32, i16, i8, u32, u16, u8, f64, f32, bool, &str, String and serde_json::Value.

When using a serde_json::Value there are certain limitations: keys in maps must be valid YARA identifiers (the first character must be _ or a letter, the remaining ones must be _, a letter or a digit), because these maps are translated into YARA structures. Also, all items in an array must have the same type.

assert!(Compiler::new()
    .define_global("some_int", 1)?
    .add_source("rule some_int_not_zero {condition: some_int != 0}")
    .is_ok());

pub fn new_namespace(&mut self, namespace: &str) -> &mut Self

Creates a new namespace.

Further calls to Compiler::add_source will put the rules under the newly created namespace. If the new namespace is named as the current one, no new namespace is created.

In the example below both rules foo and bar are put into the same namespace (the default namespace), therefore bar can use foo as part of its condition, and everything is ok.

assert!(Compiler::new()
    .add_source("rule foo {condition: true}")?
    .add_source("rule bar {condition: foo}")
    .is_ok());

In this other example the rule foo is put in the default namespace, but the rule bar is put under the bar namespace. This implies that foo is not visible to bar, and the second call to add_source fails.

assert!(Compiler::new()
    .add_source("rule foo {condition: true}")?
    .new_namespace("bar")
    .add_source("rule bar {condition: foo}")
    .is_err());

pub fn build(self) -> Rules

Builds the source code previously added to the compiler.

This function consumes the compiler and returns an instance of Rules.

pub fn add_linter<L: Linter + 'a>(&mut self, linter: L) -> &mut Self

Adds a linter to the compiler.

Linters perform additional checks to each YARA rule, generating warnings when a rule does not meet the linter’s requirements. See crate::linters for a list of available linters.

pub fn ignore_module<M: Into<String>>(&mut self, module: M) -> &mut Self

Tell the compiler that a YARA module is not supported.

Import statements for ignored modules will be ignored without errors, but a warning will be issued. Any rule that makes use of an ignored module will be also ignored, while the rest of the rules that don’t rely on that module will be correctly compiled.

pub fn ban_module<M: Into<String>, T: Into<String>, E: Into<String>>( &mut self, module: M, error_title: T, error_message: E, ) -> &mut Self

Tell the compiler that a YARA module can’t be used.

Import statements for the banned module will cause an error. The error message can be customized by using the given error title and message.

If this function is called multiple times with the same module name, the error title and message will be updated.

pub fn colorize_errors(&mut self, yes: bool) -> &mut Self

Specifies whether the compiler should produce colorful error messages.

Colorized error messages contain ANSI escape sequences that make them look nicer on compatible consoles.

The default setting is false.

pub fn errors_max_width(&mut self, width: usize) -> &mut Self

Sets the maximum number of columns in error messages.

The default value is 140.

pub fn switch_warning( &mut self, code: &str, enabled: bool, ) -> Result<&mut Self, InvalidWarningCode>

Enables or disables a specific type of warning.

Each warning type has a description code (i.e: slow_pattern, unsupported_module, etc.). This function allows to enable or disable a specific type of warning identified by the given code.

Returns an error if the given warning code doesn’t exist.

pub fn switch_all_warnings(&mut self, enabled: bool) -> &mut Self

Enables or disables all warnings.

pub fn relaxed_re_syntax(&mut self, yes: bool) -> &mut Self

Enables a more relaxed syntax check for regular expressions.

YARA-X enforces stricter regular expression syntax compared to YARA. For instance, YARA accepts invalid escape sequences and treats them as literal characters (e.g., \R is interpreted as a literal ‘R’). It also allows some special characters to appear unescaped, inferring their meaning from the context (e.g., { and } in /foo{}bar/ are literal, but in /foo{0,1}bar/ they form the repetition operator {0,1}).

This setting controls whether the compiler should mimic YARA’s behavior, allowing constructs that YARA-X doesn’t accept by default.

This should be called before any rule is added to the compiler.

Panics

If called after adding rules to the compiler.

pub fn error_on_slow_pattern(&mut self, yes: bool) -> &mut Self

When enabled, slow patterns produce an error instead of a warning.

This is disabled by default.

pub fn error_on_slow_loop(&mut self, yes: bool) -> &mut Self

When enabled, potentially slow loops produce an error instead of a warning.

This is disabled by default.

pub fn enable_includes(&mut self, yes: bool) -> &mut Self

Controls whether include statements are allowed.

By default, the compiler allows the use of include statements, which include the content of other files. When includes are disabled, any attempt to use an include statement will result in a compile error.

let mut compiler = Compiler::new();
compiler.enable_includes(false);  // Disable includes

pub fn errors(&self) -> &[CompileError]

Retrieves all errors generated by the compiler.

This method returns every error encountered during the compilation, across all invocations of Compiler::add_source.

pub fn warnings(&self) -> &[Warning]

Returns the warnings emitted by the compiler.

This method returns every warning issued during the compilation, across all invocations of Compiler::add_source.

pub fn emit_wasm_file<P>(self, path: P) -> Result<(), EmitWasmError>

where P: AsRef<Path>,

Emits a .wasm file with the WASM module generated by the compiler.

This file can be inspected and converted to WASM text format by using third-party tooling. This is useful for debugging issues with incorrectly emitted WASM code.

Trait Implementations

impl Debug for Compiler<'_>

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

Formats the value using the given formatter.

impl Default for Compiler<'_>

fn default() -> Self

Returns the “default value” for a type.