Paste blocks: injecting custom code into generated files

Table of Contents

1. Summary

Codegen overwrites every generated file on each run. Paste blocks are the mechanism for injecting hand-written C++ into those files in a way that survives regeneration. Each injection point in a template is identified by a UUID marker (<<paste:UUID>>); any Babel block in the entity org model that carries a matching :implements UUID header argument contributes its body to that marker. The pattern covers declarations (.hpp), implementations (.cpp), and extra .cpp includes.

2. Detail

2.1. How it works

During code generation core.py collects all Babel blocks in the entity org model that carry an :implements <UUID> header argument. After rendering the Mustache template it replaces each <<paste:UUID>> marker with the concatenated bodies of all matching blocks.

The Babel block :name tag is for human navigation only. The :implements tag is what codegen acts on.

2.2. Repository injection points

The following paste UUIDs are defined for the repository profile. Their canonical IDs live in org entity meta model.

UUID Where injected Template
DCA78C69-E508-48D9-9972-A9B8094D91FB Inside the repository class, before the closing } ores.cpp.repository.repository_header
F2EB1914-5E94-42CA-9C77-46BDB364BF9E Near the end of _repository.cpp, before } of namespace ores.cpp.repository.repository_impl
6141050C-0ED4-4680-B387-7DDDA3A69806 Top of _repository.cpp, after the generated includes ores.cpp.repository.repository_impl

2.3. Recipe: adding a custom repository method

Given an entity org model, add a heading under ** Repository with a unique :ID:, then attach three Babel blocks:

#+begin_src org

2.3.1. read_latest_all_tenants

Reads the latest records across all tenants (no tenant_id filter). 

std::vector<domain::feed_binding> read_latest_all_tenants(context ctx);

#include <string>

std::vector<domain::feed_binding>
feed_binding_repository::read_latest_all_tenants(context ctx) {
    ...
}

#+end_src

After editing the org model run: 

./compass.sh codegen entity generate <entity>

The generated .hpp will contain the declaration and the generated .cpp will contain the implementation — both survive all future regen runs.

2.4. Considerations

  • The impl_includes block can be omitted when no extra includes are needed; codegen silently skips absent markers.
  • Multiple paste blocks with the same :implements UUID are concatenated in document order.
  • read_latest_all_tenants is a good candidate for promotion to a generated optional controlled by a flag in the entity org model (e.g. #+has_cross_tenant_read: true), since the pattern is identical across entities. Tracked as a future codegen improvement.

3. See also

Emacs 29.3 (Org mode 9.6.15)