Expand description
Library for generating C code
This library provides an API for generating C source code. It allows structured generation of C code using Rust, ensuring proper formatting and structure while maintaining readability.
Notable capabilities include a recursive type model with a real declarator
algorithm (so pointers, arrays, and function pointers nest correctly),
precedence-aware expression printing that inserts only the parentheses a given
grouping requires, and translation-unit splitting into a matching header and
source pair via Module.
§Modules
function: Defines and formats C functions.preprocessor: Manages preprocessor directives like#include,#define, and#pragma.variable: Handles variable declarations.types: Defines C types and type qualifiers.storage: TODOstructs: Supports defining and managing C struct types.union: Provides utilities for defining and formatting C unions.typedef: Facilitates creatingtypedefaliases for types in C.loops: Constructs and formats C loop structures (for,while,do-while).conditional: Handles conditional statements likeif,switch.formatter: Provides utilities for formatting generated C code.scope: Defines scope management for C code generation.module: Splits a translation unit into a matching header (.h) and source (.c) pair.ident: Identifier hygiene — sanitizing names, C keyword checks, and fresh-name generation.attribute: GNU/C23 attributes (packed,noreturn,aligned, …) for items.static_assert:_Static_assert/static_assertcompile-time assertions.block: Manages blocks of code within functions and control structures.comment: Supports adding inline and documentation comments.expr: Handles C expressions and operations.enums: Supports enumeration (enum) type definitions.
§Example Usage
use tamago::{BaseType, Block, FunctionBuilder, ParameterBuilder, Type};
let func = FunctionBuilder::new_with_str("my_function", Type::new(BaseType::Int).build())
.param(
ParameterBuilder::new_with_str(
"param1",
Type::new(BaseType::Float).build(),
)
.build(),
)
.body(Block::new().build())
.build();
println!("{}", func);This will generate the following C function:
int my_function(float param1) {
}Structs§
- Anon
Aggregate - An inline anonymous aggregate used as the “type” of a
Field. - Attribute
- A single C attribute, such as
packed,aligned(8), orformat(printf, 1, 2). - Block
- Represents a scoped block of code in C, delimited by curly braces
{}. ABlockcontains a sequence of statements that are executed together within the same lexical scope. - Block
Builder - A builder for constructing
Blockinstances in a fluent, chainable manner. - Comment
- Represents a C-style comment in generated code. This struct supports both standard single-line comments and special heading-style comments that are surrounded by separator lines for visual emphasis.
- Comment
Builder - A builder for constructing
Commentinstances in a fluent, chainable manner. - DoWhile
- Represents a do-while loop in C.
- DoWhile
Builder - A builder for constructing a
DoWhileloop instance. - DocComment
- Represents a documentation comment in C code, using the
///style syntax. - DocComment
Builder - A builder for constructing
DocCommentinstances in a fluent, chainable manner. - Enum
- Represents a complete enum declaration in C programming language.
- Enum
Builder - A builder for constructing an
Enuminstance incrementally. - Error
Directive - Represents the
#errorpreprocessor directive in C. - Error
Directive Builder - A builder for constructing a
Parameterinstance with a fluent interface. - Field
- Represents a struct field in C.
- Field
Builder - A builder for constructing a
Fieldinstance. - For
- ForBuilder
- A builder for constructing a
Forloop instance. - Formatter
- Formatter for a scope.
- Func
Macro - Represents a function-like macro in C.
- Func
Macro Builder - A builder for constructing a
FuncMacrowith a fluent interface. - Function
- Represents a C function with all its components and attributes.
- Function
Builder - A builder for constructing a
Functioninstance with a fluent interface. - Gensym
- A generator of fresh, unique identifiers.
- If
- Represents an if statement in C programming language.
- IfBuilder
- A builder for constructing an
Ifstatement instance incrementally. - IfDef
Directive - Represents the C preprocessor
#ifdefand#ifndefdirectives. - IfDef
Directive Builder - A builder for constructing a complete
IfDefDirectiveinstance. - IfDirective
- Represents the C preprocessor
#ifdirective. - IfDirective
Builder - A builder for constructing a complete
IfDirectiveinstance. - Include
- Represents the
#includepreprocessor directive in C. - Include
Builder - A builder for constructing an
Includeinstance with a fluent interface. - Line
Directive - Represents the C preprocessor
#linedirective. - Module
- A C translation unit: a header (
.h) and a source (.c) generated together. - Module
Builder - A builder for
Modulewith helpers that route declarations and definitions to the header or the source automatically. - ObjMacro
- Represents an object-like macro in C.
- ObjMacro
Builder - A builder for constructing an
ObjMacrowith a fluent interface. - Parameter
- Represents a single parameter in a C function declaration or definition.
- Parameter
Builder - A builder for constructing a
Parameterinstance with a fluent interface. - Pragma
Directive - Represents a
#pragmapreprocessor directive in C. - Pragma
Directive Builder - A builder for constructing a
PragmaDirectivewith a fluent interface. - Render
Options - Options that control how code is rendered. Use with
render,render_to,render_to_io, orFormatter::with_options. - Scope
- Represents a global scope in C, serving as the root container for all C code elements.
- Scope
Builder - A builder for constructing a
Scopeinstance using the builder pattern. - Source
Loc - A source location used for
#linemapping: a file path and a 1-based line number in the original (pre-generation) source - Static
Assert - A
_Static_assert(cond, "message")compile-time assertion. - Struct
- Represents a struct in C.
- Struct
Builder - A builder for constructing a
Structinstance. - Switch
- Represents a switch statement in C programming language.
- Switch
Builder - A builder for constructing a
Switchstatement instance incrementally. - Type
Builder - A builder for constructing a
Typeinstance with a fluent interface. - TypeDef
- Represents a C-style
typedefdeclaration. - Type
DefBuilder - A builder for constructing a
TypeDefinstance. - Union
- Represents a C union with its fields and attributes.
- Union
Builder - A builder for constructing a
Unioninstance with a fluent interface. - Variable
- Represents a C variable with its properties and attributes.
- Variable
Builder - A builder for constructing a
Variableinstance with a fluent interface. - Variant
- Represents an individual enum variant (constant) within a C enum declaration.
- Variant
Builder - A builder for constructing a
Variantinstance incrementally. - Warning
Directive - Represents the C preprocessor
#warningdirective. - Warning
Directive Builder - A builder for constructing a
WarningDirectiveinstance. - While
- Represents a standard while loop in C.
- While
Builder - A builder for constructing a
Whileloop instance.
Enums§
- Aggregate
Kind - Whether an inline anonymous aggregate member is a
structor aunion. - Assign
Op - Encapsulates assignment operators used in C expressions.
- Attr
Style - The spelling style used when emitting attributes.
- Base
Type - Represents all base types used in C.
- BinOp
- Encapsulates binary operators used in C expressions.
- Brace
Style - Where the opening brace of a block is placed.
- Encoding
Prefix - The encoding prefix for a string or character literal.
- Expr
- Encapsulates all types of expressions in C.
- ForInit
- Represents a for loop in C, which consists of initialization, condition, step expressions, and a body block of statements.
- Global
Statement - Represents a global statement in C that can appear at the top level of a C file.
- Header
Guard - Controls how a module’s header protects itself against multiple inclusion
- Indent
Style - How each level of indentation is rendered.
- IntBase
- The radix used to render an
Expr::IntLit. - IntSuffix
- The suffix applied to an
Expr::IntLit, controlling its type. - Macro
- Represents a macro definition in C, either object-like or function-like.
- Scope
OrBlock - Represents a container that holds either a
Scopeor aBlock. - Statement
- Represents the various types of statements and preprocessor directives that can appear within a C code block.
- Storage
Class - A C storage-class specifier.
- Type
- A recursive description of a C type, built out of a base type wrapped in any number of pointer, array, and function derivations.
- Type
Qualifier - Represents type qualifiers in C.
- UnaryOp
- Encapsulates unary operators used in C expressions.
Constants§
- C_
KEYWORDS - The reserved keywords of C, covering C11 (including the
_-prefixed keywords) and the additions introduced by C23.
Traits§
Functions§
- declare
- Renders a full C declaration for
tynaming the declaratorinner. - declare_
with - Like
declare, but renders any option-sensitive sub-expressions (notably an array size such asalignof(T)) using the givenRenderOptionsinstead of the defaults. When aTypeis formatted through aFormatter, this is called with the formatter’s own options so nested spellings stay consistent. - format_
annotations - Renders raw macro/specifier tokens followed by the typed attribute group, or the empty string if both are empty
- format_
attrs - Renders a list of attributes in the given style, or the empty string if the list is empty.
- has_
annotations - Returns whether an annotation slot would render to anything — i.e. there is at
least one raw specifier token or one typed attribute. Handy for deciding
separating whitespace around
write_annotations. - is_
c_ keyword - Returns
trueifsis a reserved C keyword (seeC_KEYWORDS) - render
- Renders any
Formatvalue to aStringusing the givenRenderOptions. - render_
to - Streams a
Formatvalue into anyfmt::Writesink instead of building one bigStringfirst. This matters for large translation units, where the intermediateStringwould be sizable. - render_
to_ io - Streams a
Formatvalue directly into anio::Writesink (a file, a socket,stdout, …) without an intermediateString:) - sanitize_
ident - Rewrites an arbitrary string into a valid C identifier.
- sanitize_
ident_ strict - Like
sanitize_ident, but additionally guarantees the result is not in C’s reserved identifier space. - write_
annotations - Writes the combined annotation slot (raw specifier tokens followed by the
grouped typed attributes) into
fmtin the ambientAttrStyle, or nothing if both are empty. - write_
attrs - Writes a group of attributes into
fmtas a single__attribute__((...))/[[...]]group, in the formatter’s ambientAttrStyle, or nothing if the list is empty.