Struct Module

pub struct Module { /* private fields */ }

WebAssembly module

Implementations

impl Module

pub fn new(sections: Vec<Section>) -> Self

New module with sections

pub fn into_sections(self) -> Vec<Section>

Destructure the module, yielding sections

pub fn version(&self) -> u32

Version of module.

pub fn sections(&self) -> &[Section]

Sections list. Each known section is optional and may appear at most once.

Examples found in repository

examples/info.rs (line 15)

fn main() {
    let args = env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        println!("Usage: {} somefile.wasm", args[0]);
        return;
    }

    let module = sophon_wasm::deserialize_file(&args[1]).expect("Failed to load module");

    println!("Module sections: {}", module.sections().len());

    for section in module.sections() {
        match *section {
            Section::Import(ref import_section) => {
                println!("  Imports: {}", import_section.entries().len());
                import_section.entries().iter().map(|e| println!("    {}.{}", e.module(), e.field())).count();
            },
            Section::Export(ref exports_section) => {
                println!("  Exports: {}", exports_section.entries().len());
                exports_section.entries().iter().map(|e| println!("    {}", e.field())).count();
            },            
            Section::Function(ref function_section) => {
                println!("  Functions: {}", function_section.entries().len());
            },
            Section::Type(ref type_section) => {
                println!("  Types: {}", type_section.types().len());
            },
            Section::Global(ref globals_section) => {
                println!("  Globals: {}", globals_section.entries().len());                
            },
            Section::Data(ref data_section) if data_section.entries().len() > 0 => {
                let data = &data_section.entries()[0];
                println!("  Data size: {}", data.value().len()); 
            },
            _ => {},
        }
    }
}

pub fn sections_mut(&mut self) -> &mut Vec<Section>

Sections list (mutable) Each known section is optional and may appear at most once.

Examples found in repository

examples/inject.rs (line 37)

fn main() {
    let args = env::args().collect::<Vec<_>>();
    if args.len() != 3 {
        println!("Usage: {} input_file.wasm output_file.wasm", args[0]);
        return;
    }

    let mut module = sophon_wasm::deserialize_file(&args[1]).unwrap();

    for section in module.sections_mut() {
        match section {
            &mut elements::Section::Code(ref mut code_section) => {
                for ref mut func_body in code_section.bodies_mut() {
                    inject_nop(func_body.code_mut());
                }
            },
            _ => { }
        }
    }

    let mut build = builder::from_module(module);
    let import_sig = build.push_signature(
        builder::signature()
            .param().i32()
            .param().i32()
            .return_type().i32()
            .build_sig()
    );
    let build = build.import()
        .module("env")
        .field("log")
        .external().func(import_sig)
        .build();

    sophon_wasm::serialize_to_file(&args[2], build.build()).unwrap();
}

pub fn code_section(&self) -> Option<&CodeSection>

Code section, if any.

pub fn type_section(&self) -> Option<&TypeSection>

Types section, if any.

Examples found in repository

examples/exports.rs (line 16)

fn type_by_index(module: &Module, index: usize) -> FunctionType {

    // Demand that function and type section exist. Otherwise, fail with a
    // corresponding error.
    let function_section = module.function_section().expect("No function section found");
    let type_section = module.type_section().expect("No type section found");

    // This counts the number of _function_ imports listed by the module, excluding
    // the globals, since indexing for actual functions for `call` and `export` purposes
    // includes both imported and own functions. So we actualy need the imported function count
    // to resolve actual index of the given function in own functions list.
    let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

    // Substract the value queried in the previous step from the provided index
    // to get own function index from which we can query type next.
    let function_index_in_section = index - import_section_len;

    // Query the own function given we have it's index
    let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

    // Finally, return function type (signature)
    match type_section.types()[func_type_ref] {
        Type::Function(ref func_type) => func_type.clone(),
    }
}

examples/invoke.rs (line 30)

fn main() {
    let args: Vec<_> = args().collect();
    if args.len() < 3 {
        println!("Usage: {} <wasm file> <exported func> [<arg>...]", args[0]);
        return;
    }
    let func_name = &args[2];
    let (_, program_args) = args.split_at(3);

    // Intrepreter initialization.
    let program = sophon_wasm::ProgramInstance::new();

    let module = sophon_wasm::deserialize_file(&args[1]).expect("File to be deserialized");

    // Extracts call arguments from command-line arguments
    let execution_params = {
        // Export section has an entry with a func_name with an index inside a module
        let export_section = module.export_section().expect("No export section found");
        // It's a section with function declarations (which are references to the type section entries)
        let function_section = module.function_section().expect("No function section found");
        // Type section stores function types which are referenced by function_section entries
        let type_section = module.type_section().expect("No type section found");

        // Given function name used to find export section entry which contains
        // an `internal` field which points to the index in the function index space
        let found_entry = export_section.entries().iter()
            .find(|entry| func_name == entry.field()).expect(&format!("No export with name {} found", func_name));

        // Function index in the function index space (internally-defined + imported)
        let function_index: usize = match found_entry.internal() {
            &Internal::Function(index) => index as usize,
            _ => panic!("Founded export is not a function"),
        };

        // We need to count import section entries (functions only!) to subtract it from function_index
        // and obtain the index within the function section
        let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

        // Calculates a function index within module's function section
        let function_index_in_section = function_index - import_section_len;

        // Getting a type reference from a function section entry
        let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

        // Use the reference to get an actual function type
        let function_type: &FunctionType = match &type_section.types()[func_type_ref] {
            &Type::Function(ref func_type) => func_type,
        };

        // Parses arguments and constructs runtime values in correspondence of their types
        let args: Vec<RuntimeValue> = function_type.params().iter().enumerate().map(|(i, value)| match value {
            &ValueType::I32 => RuntimeValue::I32(program_args[i].parse::<i32>().expect(&format!("Can't parse arg #{} as i32", program_args[i]))),
            &ValueType::I64 => RuntimeValue::I64(program_args[i].parse::<i64>().expect(&format!("Can't parse arg #{} as i64", program_args[i]))),
            &ValueType::F32 => RuntimeValue::F32(program_args[i].parse::<f32>().expect(&format!("Can't parse arg #{} as f32", program_args[i]))),
            &ValueType::F64 => RuntimeValue::F64(program_args[i].parse::<f64>().expect(&format!("Can't parse arg #{} as f64", program_args[i]))),
        }).collect();

        interpreter::ExecutionParams::from(args)
    };

    // Intialize deserialized module. It adds module into It expects 3 parameters:
    // - a name for the module
    // - a module declaration
    // - "main" module doesn't import native module(s) this is why we don't need to provide external native modules here
    // This test shows how to implement native module https://github.com/NikVolf/sophon-wasm/blob/master/src/interpreter/tests/basics.rs#L197
    let module = program.add_module("main", module, None).expect("Failed to initialize module");

    println!("Result: {:?}", module.execute_export(func_name, execution_params).expect(""));
}

pub fn import_section(&self) -> Option<&ImportSection>

Imports section, if any.

Examples found in repository

examples/exports.rs (line 22)

fn type_by_index(module: &Module, index: usize) -> FunctionType {

    // Demand that function and type section exist. Otherwise, fail with a
    // corresponding error.
    let function_section = module.function_section().expect("No function section found");
    let type_section = module.type_section().expect("No type section found");

    // This counts the number of _function_ imports listed by the module, excluding
    // the globals, since indexing for actual functions for `call` and `export` purposes
    // includes both imported and own functions. So we actualy need the imported function count
    // to resolve actual index of the given function in own functions list.
    let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

    // Substract the value queried in the previous step from the provided index
    // to get own function index from which we can query type next.
    let function_index_in_section = index - import_section_len;

    // Query the own function given we have it's index
    let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

    // Finally, return function type (signature)
    match type_section.types()[func_type_ref] {
        Type::Function(ref func_type) => func_type.clone(),
    }
}

examples/invoke.rs (line 45)

fn main() {
    let args: Vec<_> = args().collect();
    if args.len() < 3 {
        println!("Usage: {} <wasm file> <exported func> [<arg>...]", args[0]);
        return;
    }
    let func_name = &args[2];
    let (_, program_args) = args.split_at(3);

    // Intrepreter initialization.
    let program = sophon_wasm::ProgramInstance::new();

    let module = sophon_wasm::deserialize_file(&args[1]).expect("File to be deserialized");

    // Extracts call arguments from command-line arguments
    let execution_params = {
        // Export section has an entry with a func_name with an index inside a module
        let export_section = module.export_section().expect("No export section found");
        // It's a section with function declarations (which are references to the type section entries)
        let function_section = module.function_section().expect("No function section found");
        // Type section stores function types which are referenced by function_section entries
        let type_section = module.type_section().expect("No type section found");

        // Given function name used to find export section entry which contains
        // an `internal` field which points to the index in the function index space
        let found_entry = export_section.entries().iter()
            .find(|entry| func_name == entry.field()).expect(&format!("No export with name {} found", func_name));

        // Function index in the function index space (internally-defined + imported)
        let function_index: usize = match found_entry.internal() {
            &Internal::Function(index) => index as usize,
            _ => panic!("Founded export is not a function"),
        };

        // We need to count import section entries (functions only!) to subtract it from function_index
        // and obtain the index within the function section
        let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

        // Calculates a function index within module's function section
        let function_index_in_section = function_index - import_section_len;

        // Getting a type reference from a function section entry
        let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

        // Use the reference to get an actual function type
        let function_type: &FunctionType = match &type_section.types()[func_type_ref] {
            &Type::Function(ref func_type) => func_type,
        };

        // Parses arguments and constructs runtime values in correspondence of their types
        let args: Vec<RuntimeValue> = function_type.params().iter().enumerate().map(|(i, value)| match value {
            &ValueType::I32 => RuntimeValue::I32(program_args[i].parse::<i32>().expect(&format!("Can't parse arg #{} as i32", program_args[i]))),
            &ValueType::I64 => RuntimeValue::I64(program_args[i].parse::<i64>().expect(&format!("Can't parse arg #{} as i64", program_args[i]))),
            &ValueType::F32 => RuntimeValue::F32(program_args[i].parse::<f32>().expect(&format!("Can't parse arg #{} as f32", program_args[i]))),
            &ValueType::F64 => RuntimeValue::F64(program_args[i].parse::<f64>().expect(&format!("Can't parse arg #{} as f64", program_args[i]))),
        }).collect();

        interpreter::ExecutionParams::from(args)
    };

    // Intialize deserialized module. It adds module into It expects 3 parameters:
    // - a name for the module
    // - a module declaration
    // - "main" module doesn't import native module(s) this is why we don't need to provide external native modules here
    // This test shows how to implement native module https://github.com/NikVolf/sophon-wasm/blob/master/src/interpreter/tests/basics.rs#L197
    let module = program.add_module("main", module, None).expect("Failed to initialize module");

    println!("Result: {:?}", module.execute_export(func_name, execution_params).expect(""));
}

pub fn global_section(&self) -> Option<&GlobalSection>

Globals section, if any.

pub fn export_section(&self) -> Option<&ExportSection>

Exports section, if any.

Examples found in repository

examples/exports.rs (line 62)

fn main() {

    // Example executable takes one argument which must
    // refernce the existing file with a valid wasm module
    let args: Vec<_> = args().collect();
    if args.len() < 2 {
        println!("Prints export function names with and their types");
        println!("Usage: {} <wasm file>", args[0]);
        return;
    }

    // Here we load module using dedicated for this purpose
    // `deserialize_file` function (which works only with modules)
    let module = sophon_wasm::deserialize_file(&args[1]).expect("File to be deserialized");

    // Query the export section from the loaded module. Note that not every
    // wasm module obliged to contain export section. So in case there is no
    // any export section, we panic with the corresponding error.
    let export_section = module.export_section().expect("No export section found");

    // Process all exports, leaving only those which reference the internal function
    // of the wasm module
    let exports: Vec<String> = export_section.entries().iter()
        .filter_map(|entry|
            // This is match on export variant, which can be function, global,table or memory
            // We are interested only in functions for an example
            match *entry.internal() {
                // Return function export name (return by field() function and it's index)
                Internal::Function(index) => Some((entry.field(), index as usize)),
                _ => None
            })
        // Another map to resolve function signature index given it's internal index and return
        // the printable string of the export
        .map(|(field, index)| format!("{:}: {:?}", field, type_by_index(&module, index).params())).collect();

    // Print the result
    for export in exports {
        println!("{:}", export);
    }
}

examples/invoke.rs (line 26)

fn main() {
    let args: Vec<_> = args().collect();
    if args.len() < 3 {
        println!("Usage: {} <wasm file> <exported func> [<arg>...]", args[0]);
        return;
    }
    let func_name = &args[2];
    let (_, program_args) = args.split_at(3);

    // Intrepreter initialization.
    let program = sophon_wasm::ProgramInstance::new();

    let module = sophon_wasm::deserialize_file(&args[1]).expect("File to be deserialized");

    // Extracts call arguments from command-line arguments
    let execution_params = {
        // Export section has an entry with a func_name with an index inside a module
        let export_section = module.export_section().expect("No export section found");
        // It's a section with function declarations (which are references to the type section entries)
        let function_section = module.function_section().expect("No function section found");
        // Type section stores function types which are referenced by function_section entries
        let type_section = module.type_section().expect("No type section found");

        // Given function name used to find export section entry which contains
        // an `internal` field which points to the index in the function index space
        let found_entry = export_section.entries().iter()
            .find(|entry| func_name == entry.field()).expect(&format!("No export with name {} found", func_name));

        // Function index in the function index space (internally-defined + imported)
        let function_index: usize = match found_entry.internal() {
            &Internal::Function(index) => index as usize,
            _ => panic!("Founded export is not a function"),
        };

        // We need to count import section entries (functions only!) to subtract it from function_index
        // and obtain the index within the function section
        let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

        // Calculates a function index within module's function section
        let function_index_in_section = function_index - import_section_len;

        // Getting a type reference from a function section entry
        let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

        // Use the reference to get an actual function type
        let function_type: &FunctionType = match &type_section.types()[func_type_ref] {
            &Type::Function(ref func_type) => func_type,
        };

        // Parses arguments and constructs runtime values in correspondence of their types
        let args: Vec<RuntimeValue> = function_type.params().iter().enumerate().map(|(i, value)| match value {
            &ValueType::I32 => RuntimeValue::I32(program_args[i].parse::<i32>().expect(&format!("Can't parse arg #{} as i32", program_args[i]))),
            &ValueType::I64 => RuntimeValue::I64(program_args[i].parse::<i64>().expect(&format!("Can't parse arg #{} as i64", program_args[i]))),
            &ValueType::F32 => RuntimeValue::F32(program_args[i].parse::<f32>().expect(&format!("Can't parse arg #{} as f32", program_args[i]))),
            &ValueType::F64 => RuntimeValue::F64(program_args[i].parse::<f64>().expect(&format!("Can't parse arg #{} as f64", program_args[i]))),
        }).collect();

        interpreter::ExecutionParams::from(args)
    };

    // Intialize deserialized module. It adds module into It expects 3 parameters:
    // - a name for the module
    // - a module declaration
    // - "main" module doesn't import native module(s) this is why we don't need to provide external native modules here
    // This test shows how to implement native module https://github.com/NikVolf/sophon-wasm/blob/master/src/interpreter/tests/basics.rs#L197
    let module = program.add_module("main", module, None).expect("Failed to initialize module");

    println!("Result: {:?}", module.execute_export(func_name, execution_params).expect(""));
}

pub fn table_section(&self) -> Option<&TableSection>

Table section, if any.

pub fn data_section(&self) -> Option<&DataSection>

Data section, if any.

Examples found in repository

examples/data.rs (line 25)

fn main() {

    // Example executable takes one argument which must
    // refernce the existing file with a valid wasm module
    let args = env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        println!("Usage: {} somefile.wasm", args[0]);
        return;
    }

    // Here we load module using dedicated for this purpose
    // `deserialize_file` function (which works only with modules)
    let module = sophon_wasm::deserialize_file(&args[1]).expect("Failed to load module");

    // We query module for data section. Note that not every valid
    // wasm module must contain a data section. So in case the provided
    // module does not contain data section, we panic with an error
    let data_section = module.data_section().expect("no data section in module");

    // Printing the total count of data segments
    println!("Data segments: {}", data_section.entries().len());

    let mut index = 0;
    for entry in data_section.entries() {
        // Printing the details info of each data segment
        // see `elements::DataSegment` for more properties
        // you can query
        println!("  Entry #{}", index);

        // This shows the initialization member of data segment
        // (expression which must resolve in the linear memory location).
        println!("    init: {}", entry.offset().code()[0]);

        // This shows the total length of the data segment in bytes.
        println!("    size: {}", entry.value().len());

        index += 1;
    }
}

pub fn elements_section(&self) -> Option<&ElementSection>

Element section, if any.

pub fn memory_section(&self) -> Option<&MemorySection>

Memory section, if any.

pub fn function_section(&self) -> Option<&FunctionSection>

Functions signatures section, if any.

Examples found in repository

examples/exports.rs (line 15)

fn type_by_index(module: &Module, index: usize) -> FunctionType {

    // Demand that function and type section exist. Otherwise, fail with a
    // corresponding error.
    let function_section = module.function_section().expect("No function section found");
    let type_section = module.type_section().expect("No type section found");

    // This counts the number of _function_ imports listed by the module, excluding
    // the globals, since indexing for actual functions for `call` and `export` purposes
    // includes both imported and own functions. So we actualy need the imported function count
    // to resolve actual index of the given function in own functions list.
    let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

    // Substract the value queried in the previous step from the provided index
    // to get own function index from which we can query type next.
    let function_index_in_section = index - import_section_len;

    // Query the own function given we have it's index
    let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

    // Finally, return function type (signature)
    match type_section.types()[func_type_ref] {
        Type::Function(ref func_type) => func_type.clone(),
    }
}

examples/invoke.rs (line 28)

fn main() {
    let args: Vec<_> = args().collect();
    if args.len() < 3 {
        println!("Usage: {} <wasm file> <exported func> [<arg>...]", args[0]);
        return;
    }
    let func_name = &args[2];
    let (_, program_args) = args.split_at(3);

    // Intrepreter initialization.
    let program = sophon_wasm::ProgramInstance::new();

    let module = sophon_wasm::deserialize_file(&args[1]).expect("File to be deserialized");

    // Extracts call arguments from command-line arguments
    let execution_params = {
        // Export section has an entry with a func_name with an index inside a module
        let export_section = module.export_section().expect("No export section found");
        // It's a section with function declarations (which are references to the type section entries)
        let function_section = module.function_section().expect("No function section found");
        // Type section stores function types which are referenced by function_section entries
        let type_section = module.type_section().expect("No type section found");

        // Given function name used to find export section entry which contains
        // an `internal` field which points to the index in the function index space
        let found_entry = export_section.entries().iter()
            .find(|entry| func_name == entry.field()).expect(&format!("No export with name {} found", func_name));

        // Function index in the function index space (internally-defined + imported)
        let function_index: usize = match found_entry.internal() {
            &Internal::Function(index) => index as usize,
            _ => panic!("Founded export is not a function"),
        };

        // We need to count import section entries (functions only!) to subtract it from function_index
        // and obtain the index within the function section
        let import_section_len: usize = match module.import_section() {
            Some(import) =>
                import.entries().iter().filter(|entry| match entry.external() {
                    &External::Function(_) => true,
                    _ => false,
                    }).count(),
            None => 0,
        };

        // Calculates a function index within module's function section
        let function_index_in_section = function_index - import_section_len;

        // Getting a type reference from a function section entry
        let func_type_ref: usize = function_section.entries()[function_index_in_section].type_ref() as usize;

        // Use the reference to get an actual function type
        let function_type: &FunctionType = match &type_section.types()[func_type_ref] {
            &Type::Function(ref func_type) => func_type,
        };

        // Parses arguments and constructs runtime values in correspondence of their types
        let args: Vec<RuntimeValue> = function_type.params().iter().enumerate().map(|(i, value)| match value {
            &ValueType::I32 => RuntimeValue::I32(program_args[i].parse::<i32>().expect(&format!("Can't parse arg #{} as i32", program_args[i]))),
            &ValueType::I64 => RuntimeValue::I64(program_args[i].parse::<i64>().expect(&format!("Can't parse arg #{} as i64", program_args[i]))),
            &ValueType::F32 => RuntimeValue::F32(program_args[i].parse::<f32>().expect(&format!("Can't parse arg #{} as f32", program_args[i]))),
            &ValueType::F64 => RuntimeValue::F64(program_args[i].parse::<f64>().expect(&format!("Can't parse arg #{} as f64", program_args[i]))),
        }).collect();

        interpreter::ExecutionParams::from(args)
    };

    // Intialize deserialized module. It adds module into It expects 3 parameters:
    // - a name for the module
    // - a module declaration
    // - "main" module doesn't import native module(s) this is why we don't need to provide external native modules here
    // This test shows how to implement native module https://github.com/NikVolf/sophon-wasm/blob/master/src/interpreter/tests/basics.rs#L197
    let module = program.add_module("main", module, None).expect("Failed to initialize module");

    println!("Result: {:?}", module.execute_export(func_name, execution_params).expect(""));
}

pub fn start_section(&self) -> Option<u32>

Start section, if any.

Trait Implementations

impl Clone for Module

fn clone(&self) -> Module

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Module

fn default() -> Self

Returns the “default value” for a type.

impl Deserialize for Module

type Error = Error

Serialization error produced by deserialization routine.

fn deserialize<R: Read>(reader: &mut R) -> Result<Self, Self::Error>

Deserialize type from serial i/o

impl Serialize for Module

type Error = Error

Serialization error produced by serialization routine.

fn serialize<W: Write>(self, w: &mut W) -> Result<(), Self::Error>

Serialize type to serial i/o