Getting started

Parse, validate, and serialize a class

#include <rpnx/cortado/class_file.hpp>
 
std::span< std::byte const > input = /* complete class-file bytes */;
rpnx::cortado::class_file model = rpnx::cortado::deserialize_class_file(input);
rpnx::cortado::validation_report const report = rpnx::cortado::validate_class_file(model);
if (!report.valid())
{
    // Inspect report.diagnostics before attempting strict serialization.
}
std::vector< std::byte > output = rpnx::cortado::serialize_class_file(model);

Use deserialize_class_file_prefix when a class file is embedded at the start of a larger byte range. It reports the exact number of consumed bytes. The ordinary deserialize_class_file entry point instead requires the input range to contain exactly one class file.

Generate a method

#include <rpnx/cortado/builders.hpp>
 
rpnx::cortado::class_file_builder type("example/Adder");
rpnx::cortado::code_builder code;
code.iload({0})
    .iload({1})
    .append< rpnx::cortado::opcode::iadd >()
    .append< rpnx::cortado::opcode::ireturn >();
 
type.add_method(
    "add",
    "(II)I",
    rpnx::cortado::method_access_flags::is_public |
        rpnx::cortado::method_access_flags::is_static,
    code);
 
rpnx::cortado::class_file model = type.build();

Branch targets must be labels created by the same code_builder. Bind every referenced label exactly once before calling finish indirectly through class_file_builder::add_method.

Work with JAR files

#include <rpnx/cortado/jar.hpp>
 
rpnx::cortado::jar_file archive;
archive.entries.push_back({.name = "example/Adder.class", .data = class_bytes});
std::vector< std::byte > jar_bytes = rpnx::cortado::serialize_jar(archive);

Entry data is always uncompressed in memory. jar_entry::compression selects how serialization stores it in the ZIP stream. Deserialization inflates and verifies each entry before returning the owning jar_file.

Error handling

• parse_error, a std::logic_error, means input bytes deterministically cannot be decoded under the selected mode and limits.
• validation_error, a std::logic_error, means a caller-supplied structured model cannot be emitted as a valid class file.
• assembly_error, a std::logic_error, means caller-supplied symbolic bytecode cannot be resolved or analyzed.
• unsupported_feature_error, a std::logic_error, means the requested format or analysis case is deliberately outside the supported builder boundary.

The diagnostic vector returned by validate_class_file is for expected model validation failures. Exceptions remain appropriate for entry points that cannot return their requested result.

Continue with the tutorials

The tutorial series develops the code-generation API in depth, including symbolic control flow, switch layout, exception tables, automatic verifier frames, exact instruction encodings, class transformation, and JAR packaging.