rap

README

rap

Go library for decoding and encoding
Real Virtuality / DayZ RAP binary config format (.bin, binary .rvmat).

• RAP decode to rvcfg AST.
• RAP encode from rvcfg AST.
• Scalar subtype handling (string / float / long) with float normalization.
• Class-body offsets and nested array support.

Install

go get github.com/woozymasta/rap

Relationship with rvcfg

rap uses github.com/woozymasta/rvcfg as text frontend:

• preprocess + parse source text into AST
• encode AST to RAP binary
• decode RAP binary back to AST/text

Usage

Parse source and encode RAP:

parsed, err := rap.ParseSourceFileWithDefaults("config.cpp")
if err != nil {
  // handle
}

// or pass explicit options:
parsed, err := rap.ParseSourceFile("config.cpp", rap.SourceParseOptions{
  Preprocess: rvcfg.PreprocessOptions{
    IncludeDirs: []string{"./include"},
  },
  Parse: rvcfg.ParseOptions{
    CaptureScalarRaw: true,
  },
})
if err != nil {
  // handle
}

bin, err := rap.EncodeAST(parsed.Processed.Parse.File, rap.EncodeOptions{})

Encode RAP directly from in-memory source ([]byte):

bin, err := rap.EncodeBytesWithDefaults(
  "config.cpp",
  []byte(`class CfgPatches { class TestMod { units[] = {}; }; };`),
)
if err != nil {
  // handle
}

Decode RAP to AST:

file, err := rap.DecodeToAST(data, rap.DecodeOptions{})
if err != nil {
  // handle
}

_ = file.Statements

Decode RAP to text:

text, err := rap.DecodeToText(data, rap.DecodeOptions{}, rap.RenderOptions{
  Format: rvcfg.FormatOptions{
    MaxLineWidth: 120,
  },
})

Decode RAP from file path:

file, err := rap.DecodeFile("config.bin", rap.DecodeOptions{})
text, err := rap.DecodeFileToText("config.bin", rap.DecodeOptions{}, rap.RenderOptions{})

Decode options

rap.DecodeOptions{
  DisableFloatNormalization: false, // default: shortest stable float32 text
}

Format coverage

Implemented RAP entry types:

• 0 class with body offset
• 1 scalar assignment with float value
• 2 array assignment with int32 value
• 3 extern class
• 4 delete
• 5 array append (+=)
• 6 scalar assignment with int64 value

References

• https://community.bistudio.com/wiki/raP_File_Format_-_Elite
• https://community.bistudio.com/wiki/Config.cpp/bin_File_Format
• https://community.bistudio.com/wiki/TokenNameValueTypes

Documentation

Overview

Package rap implements RAP binary codec for DayZ/ArmA config-like data.

The package integrates with github.com/woozymasta/rvcfg for text source parsing (preprocess + parse) and owns binary encode/decode pipeline.

Typical flow:

• parse source text with ParseSourceFile
• encode parsed AST with EncodeAST
• decode RAP payload with DecodeToAST or DecodeToText
• or encode in-memory source directly with EncodeBytes
• or decode from file with DecodeFile / DecodeFileToText

Minimal flow example:

parsed, err := ParseSourceFileWithDefaults("config.cpp")
if err != nil {
	// handle
}

bin, err := EncodeAST(parsed.Processed.Parse.File, EncodeOptions{})
if err != nil {
	// handle
}

decoded, err := DecodeToAST(bin, DecodeOptions{})
if err != nil {
	// handle
}

_ = decoded

Index

• Variables
• func DecodeFile(path string, opts DecodeOptions) (rvcfg.File, error)
• func DecodeFileToText(path string, decodeOpts DecodeOptions, renderOpts RenderOptions) ([]byte, error)
• func DecodeToAST(data []byte, opts DecodeOptions) (rvcfg.File, error)
• func DecodeToText(data []byte, decodeOpts DecodeOptions, renderOpts RenderOptions) ([]byte, error)
• func EncodeAST(file rvcfg.File, opts EncodeOptions) ([]byte, error)
• func EncodeBytes(filename string, source []byte, parseOptions rvcfg.ParseOptions, ...) ([]byte, error)
• func EncodeBytesWithDefaults(filename string, source []byte) ([]byte, error)
• func RenderAST(file rvcfg.File) ([]byte, error)
• type DecodeOptions
• type EncodeOptions
• type EnumEntry
  • func DecodeToASTWithEnums(data []byte, opts DecodeOptions) (rvcfg.File, []EnumEntry, error)
• type RenderOptions
• type SourceParseOptions
  • func RecommendedSourceParseOptions() SourceParseOptions
• type SourceParseResult
  • func ParseSourceFile(path string, opts SourceParseOptions) (SourceParseResult, error)
  • func ParseSourceFileWithDefaults(path string) (SourceParseResult, error)

Variables

var (
	// ErrNotImplemented indicates codec path is declared but not implemented yet.
	ErrNotImplemented = errors.New("not implemented")

	// ErrInvalidRAP indicates malformed or unsupported RAP binary structure.
	ErrInvalidRAP = errors.New("invalid rap binary")

	// ErrUnsupportedScalar indicates scalar cannot be represented by v0 RAP scalar subtypes.
	ErrUnsupportedScalar = errors.New("unsupported scalar")

	// ErrReadRAPFile indicates failure while reading RAP payload from file path.
	ErrReadRAPFile = errors.New("read rap file failed")

	// ErrParseSource indicates failure while parsing source text before RAP encoding.
	ErrParseSource = errors.New("parse source failed")
)

Functions

func DecodeFile

func DecodeFile(path string, opts DecodeOptions) (rvcfg.File, error)

DecodeFile reads RAP payload from file path and decodes it to config AST.

func DecodeFileToText

func DecodeFileToText(path string, decodeOpts DecodeOptions, renderOpts RenderOptions) ([]byte, error)

DecodeFileToText reads RAP payload from file path and decodes it to text.

func DecodeToAST

func DecodeToAST(data []byte, opts DecodeOptions) (rvcfg.File, error)

DecodeToAST decodes RAP binary payload into config AST.

func DecodeToText

func DecodeToText(data []byte, decodeOpts DecodeOptions, renderOpts RenderOptions) ([]byte, error)

DecodeToText decodes RAP binary and renders canonical text.

func EncodeAST

func EncodeAST(file rvcfg.File, opts EncodeOptions) ([]byte, error)

EncodeAST encodes parsed config AST into RAP binary payload.

func EncodeBytes

func EncodeBytes(
	filename string,
	source []byte,
	parseOptions rvcfg.ParseOptions,
	encodeOptions EncodeOptions,
) ([]byte, error)

EncodeBytes parses raw source bytes (without preprocess stage) and encodes them to RAP binary payload.

func EncodeBytesWithDefaults

func EncodeBytesWithDefaults(filename string, source []byte) ([]byte, error)

EncodeBytesWithDefaults parses raw source bytes with recommended parse options and encodes them to RAP binary payload.

func RenderAST

func RenderAST(file rvcfg.File) ([]byte, error)

RenderAST renders AST into deterministic config-like text.

Types

type DecodeOptions

type DecodeOptions struct {
	// DisableFloatNormalization keeps decoded float scalars in verbose fixed form.
	// Default false normalizes to shortest round-trip float32 text.
	DisableFloatNormalization bool `json:"disable_float_normalization,omitempty" yaml:"disable_float_normalization,omitempty"`
}

DecodeOptions configures RAP binary decoder.

type EncodeOptions

type EncodeOptions struct {
	// Enums appends enum table entries after class bodies.
	Enums []EnumEntry `json:"enums,omitempty" yaml:"enums,omitempty"`
}

EncodeOptions configures RAP binary encoder.

type EnumEntry

type EnumEntry struct {
	// Name is enum symbol name.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// Value is signed integer payload.
	Value int32 `json:"value,omitempty" yaml:"value,omitempty"`
}

EnumEntry stores one RAP enum table item.

func DecodeToASTWithEnums

func DecodeToASTWithEnums(data []byte, opts DecodeOptions) (rvcfg.File, []EnumEntry, error)

DecodeToASTWithEnums decodes RAP payload and returns parsed enum table.

type RenderOptions

type RenderOptions struct {
	// Format configures final text normalization via rvcfg formatter.
	Format rvcfg.FormatOptions `json:"format,omitzero" yaml:"format,omitempty"`

	// EmitEnumBlock appends synthetic enum block reconstructed from RAP enum table.
	EmitEnumBlock bool `json:"emit_enum_block,omitempty" yaml:"emit_enum_block,omitempty"`
}

RenderOptions configures AST-to-text rendering bridge.

type SourceParseOptions

type SourceParseOptions struct {
	// Preprocess configures include/macro processing.
	Preprocess rvcfg.PreprocessOptions `json:"preprocess,omitzero" yaml:"preprocess,omitempty"`

	// Parse configures parser behavior for processed text.
	Parse rvcfg.ParseOptions `json:"parse,omitzero" yaml:"parse,omitempty"`
}

SourceParseOptions configures text source parse pipeline delegated to rvcfg.

func RecommendedSourceParseOptions

func RecommendedSourceParseOptions() SourceParseOptions

RecommendedSourceParseOptions returns RAP-oriented defaults for source parsing.

Defaults:

• Parse.CaptureScalarRaw = true
• Preprocess.EnableExecEvalIntrinsics = true

type SourceParseResult

type SourceParseResult struct {
	// Processed keeps preprocess+parse result from rvcfg.
	Processed rvcfg.ProcessAndParseResult `json:"processed,omitzero" yaml:"processed,omitempty"`
}

SourceParseResult stores source parse pipeline output.

func ParseSourceFile

func ParseSourceFile(path string, opts SourceParseOptions) (SourceParseResult, error)

ParseSourceFile runs rvcfg processed pipeline for config-like source input.

Recommended RAP-compatible options:

• Parse.CaptureScalarRaw = true
• Preprocess.EnableExecEvalIntrinsics = true

Recommended "full preprocess/macro" setup for game-like sources:

• Preprocess.IncludeDirs with include roots
• Preprocess.Defines for external symbols/flags
• Preprocess.EnableDynamicIntrinsics = true (only if source relies on DATE/TIME/COUNTER/RAND intrinsics)

func ParseSourceFileWithDefaults

func ParseSourceFileWithDefaults(path string) (SourceParseResult, error)

ParseSourceFileWithDefaults runs ParseSourceFile with RecommendedSourceParseOptions.