tamago 0.2.0

A code generator library for C, with a builder-pattern API
Documentation
// Copyright (c) 2025 Nobuharu Shimazu
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.

//! 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`: TODO
//! - `structs`: Supports defining and managing C struct types.
//! - `union`: Provides utilities for defining and formatting C unions.
//! - `typedef`: Facilitates creating `typedef` aliases for types in C.
//! - `loops`: Constructs and formats C loop structures (`for`, `while`, `do-while`).
//! - `conditional`: Handles conditional statements like `if`, `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_assert` compile-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
//! ```rust
//! 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:
//! ```c
//! int my_function(float param1) {
//! }
//! ```
//!

mod attribute;
mod block;
mod comment;
mod conditional;
mod enums;
mod escape;
mod expr;
mod formatter;
mod function;
mod ident;
mod loops;
mod module;
mod preprocessor;
mod scope;
mod static_assert;
mod storage;
mod structs;
mod typedef;
mod types;
mod union;
mod variable;

pub use attribute::{
    Attribute, format_annotations, format_attrs, has_annotations, write_annotations, write_attrs,
};
pub use block::{Block, BlockBuilder, Statement};
pub use comment::{Comment, CommentBuilder, DocComment, DocCommentBuilder};
pub use conditional::{If, IfBuilder, Switch, SwitchBuilder};
pub use enums::{Enum, EnumBuilder, Variant, VariantBuilder};
pub use expr::{AssignOp, BinOp, EncodingPrefix, Expr, IntBase, IntSuffix, UnaryOp};
pub use formatter::{
    AttrStyle, BraceStyle, Format, Formatter, IndentStyle, RenderOptions, SourceLoc, render,
    render_to, render_to_io,
};
pub use function::{Function, FunctionBuilder, Parameter, ParameterBuilder};
pub use ident::{C_KEYWORDS, Gensym, is_c_keyword, sanitize_ident, sanitize_ident_strict};
pub use loops::{DoWhile, DoWhileBuilder, For, ForBuilder, ForInit, While, WhileBuilder};
pub use module::{HeaderGuard, Module, ModuleBuilder};
pub use preprocessor::{
    ErrorDirective, ErrorDirectiveBuilder, FuncMacro, FuncMacroBuilder, IfDefDirective,
    IfDefDirectiveBuilder, IfDirective, IfDirectiveBuilder, Include, IncludeBuilder, LineDirective,
    Macro, ObjMacro, ObjMacroBuilder, PragmaDirective, PragmaDirectiveBuilder, ScopeOrBlock,
    WarningDirective, WarningDirectiveBuilder,
};
pub use scope::{GlobalStatement, Scope, ScopeBuilder};
pub use static_assert::StaticAssert;
pub use storage::StorageClass;
pub use structs::{AggregateKind, AnonAggregate, Field, FieldBuilder, Struct, StructBuilder};
pub use typedef::{TypeDef, TypeDefBuilder};
pub use types::{BaseType, Type, TypeBuilder, TypeQualifier, declare, declare_with};
pub use union::{Union, UnionBuilder};
pub use variable::{Variable, VariableBuilder};