# Code Generators - Quick Start Guide

This library includes **six production-ready code generators** that translate
ActorSimulation DSL into different languages and frameworks.

The snippets below install `actor_simulation_codegen`, which brings the
simulation DSL and the clock with it.

## Single-File Script Examples

Following
[Fly.io's single-file Elixir pattern](https://fly.io/phoenix-files/single-file-elixir-scripts/),
you can generate complete projects with just `Mix.install`!

### OMNeT++ (Network Simulation)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:sender,
      send_pattern: {:periodic, 100, :msg},
      targets: [:receiver])
  |> ActorSimulation.add_actor(:receiver)

{:ok, files} = ActorSimulation.Codegen.OMNeTPP.generate(simulation,
  network_name: "SimpleNetwork")

ActorSimulation.Codegen.OMNeTPP.write_to_directory(files, "omnetpp_out/")
```

### CAF (C++ Actor Framework)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:worker,
      send_pattern: {:rate, 50, :task},
      targets: [:processor])
  |> ActorSimulation.add_actor(:processor)

{:ok, files} = ActorSimulation.Codegen.CAF.generate(simulation,
  project_name: "MyActors",
  enable_callbacks: true)  # Callback interfaces!

ActorSimulation.Codegen.CAF.write_to_directory(files, "caf_out/")
```

### Pony (Capabilities-Secure)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:sender,
      send_pattern: {:burst, 10, 1000, :batch},
      targets: [:receiver])
  |> ActorSimulation.add_actor(:receiver)

{:ok, files} = ActorSimulation.Codegen.Pony.generate(simulation,
  project_name: "my_actors",
  enable_callbacks: true)

ActorSimulation.Codegen.Pony.write_to_directory(files, "pony_out/")
```

### Phony (Go Actors)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:worker,
      send_pattern: {:periodic, 100, :tick},
      targets: [:processor])
  |> ActorSimulation.add_actor(:processor)

{:ok, files} = ActorSimulation.Codegen.Phony.generate(simulation,
  project_name: "my_actors",
  enable_callbacks: true)

ActorSimulation.Codegen.Phony.write_to_directory(files, "phony_out/")
```

### Ractor (Rust Actors)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:producer,
      send_pattern: {:rate, 100, :data},
      targets: [:consumer])
  |> ActorSimulation.add_actor(:consumer)

{:ok, files} = ActorSimulation.Codegen.Ractor.generate(simulation,
  project_name: "my_actors",
  enable_callbacks: true)

ActorSimulation.Codegen.Ractor.write_to_directory(files, "ractor_out/")
```

### VLINGO XOOM (Java Actors)

```elixir
#!/usr/bin/env elixir
Mix.install([{:actor_simulation_codegen, "~> 1.1"}])

simulation = ActorSimulation.new()
  |> ActorSimulation.add_actor(:publisher,
      send_pattern: {:periodic, 100, :event},
      targets: [:subscriber])
  |> ActorSimulation.add_actor(:subscriber)

{:ok, files} = ActorSimulation.Codegen.Vlingo.generate(simulation,
  project_name: "my-actors",
  group_id: "com.example",
  enable_callbacks: true)

ActorSimulation.Codegen.Vlingo.write_to_directory(files, "vlingo_out/")
```

## Complete Examples

See the repository's `examples/` directory for complete single-file scripts:

- [`single_file_omnetpp.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_omnetpp.exs) -
  OMNeT++ network simulation
- [`single_file_caf.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_caf.exs) -
  C++ Actor Framework
- [`single_file_pony.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_pony.exs) -
  Pony capabilities-secure actors
- [`single_file_phony.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_phony.exs) -
  Go actors with Phony
- [`single_file_ractor.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_ractor.exs) -
  Rust actors with Ractor
- [`single_file_vlingo.exs`](https://github.com/d-led/gen_server_virtual_time/blob/main/examples/single_file_vlingo.exs) -
  Java actors with VLINGO XOOM

## Comparison

| Generator   | Purpose            | Output           | Key Feature                                |
| ----------- | ------------------ | ---------------- | ------------------------------------------ |
| **OMNeT++** | Network simulation | NED + C++        | GUI tools, INET framework                  |
| **CAF**     | Production actors  | C++ + Catch2     | Callback interfaces                        |
| **Pony**    | Safe concurrency   | Type-safe actors | Data-race freedom                          |
| **Phony**   | Go actors          | Go + tests       | Zero-allocation messaging                  |
| **Ractor**  | Rust actors        | Rust + Cargo     | Gen_server-inspired, OTP-style supervision |
| **VLINGO**  | Java actors        | Java + Maven     | Protocol actors, type-safe                 |

## Development Workflow

1. **Prototype** in Elixir (fast iteration)
2. **Test** with virtual time (deterministic)
3. **Visualize** with sequence diagrams
4. **Generate** to your target language
5. **Deploy** to production

## Why Single-File Scripts?

Benefits of using `Mix.install` for code generation:

✅ **Portable** - One file, no setup required  
✅ **Reproducible** - Same input = same output  
✅ **Shareable** - GitHub gist, email, anywhere  
✅ **Isolated** - No impact on your main projects  
✅ **Fast** - Generate code in seconds

Perfect for:

- Bug reports with minimal examples
- Quick prototyping
- CI/CD pipelines
- Teaching and demos

## Learn More

- [OMNeT++ Generator](omnetpp_generator.md)
- [CAF Generator](caf_generator.md)
- [Pony Generator](pony_generator.md)
- [Phony Generator](phony_generator.md)
- [Ractor Generator](ractor_generator.md)
- [VLINGO Generator](vlingo_generator.md)

## Next Steps

1. Try a single-file example
2. Choose your target framework
3. Generate production code
4. Customize via callbacks
5. Deploy with confidence!