jeirmeister/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-07-28 20:00:24 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

[Networking] Doxygen (#7030)

Browse source 
* [Networking] Doxygen

* Lint cause my autolinter is broken lol

* Update.

* Update Doxyfile

Co-authored-by: tooomm <tooomm@users.noreply.github.com>

* Alphabetical ordering

Co-authored-by: tooomm <tooomm@users.noreply.github.com>

* Add new card art rule comment

* move filter program into doxygen folder

* [Networking] Doxygen


Took 49 seconds

* [Networking] Doxygen

Took 2 hours 0 minutes

Took 58 minutes

Took 8 seconds

Took 29 seconds

Took 4 minutes

Took 1 minute

Took 4 minutes

* [Networking] Fix Doxyfile

Took 2 hours 0 minutes

Took 58 minutes

Took 8 seconds

Took 29 seconds

Took 4 minutes

Took 1 minute

Took 6 minutes

* [Networking] Fix Doxyfile

Took 2 hours 0 minutes

Took 58 minutes

Took 8 seconds

Took 29 seconds

Took 4 minutes

Took 1 minute

Took 3 minutes

* [Networking] Fix Doxyfile again

Took 2 hours 0 minutes

Took 58 minutes

Took 8 seconds

Took 29 seconds

Took 4 minutes

Took 1 minute

Took 2 minutes

---------

Co-authored-by: Lukas Brübach <lukas.bruebach@bdosecurity.de>
Co-authored-by: tooomm <tooomm@users.noreply.github.com>
Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>
This commit is contained in:
BruebachL 2026-07-27 11:27:00 +02:00 • committed by GitHub
parent 12f0f59453
commit 61b9d7abf6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 2642 additions and 129 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/doxygen/extra-pages/developer_documentation/index.md
View file

@ -8,4 +8,6 @@
- @subpage querying_the_card_database
- @subpage loading_card_pictures
- @subpage displaying_cards
- @subpage displaying_cards
- @subpage developer_reference_network_overview

170
doc/doxygen/extra-pages/developer_documentation/network/client/game_event_handler.md Normal file
View file

@ -0,0 +1,170 @@
@page game_event_handler GameEventHandler
## Overview
`GameEventHandler` is the central coordinator for **game-wide commands and events**.
It acts as the bridge between the networking layer (protobuf messages received from
the server) and the local game model and UI.
Unlike `PlayerEventHandler`, which is responsible for player-scoped state and zones,
`GameEventHandler` handles:
- Global game flow (turns, phases, host changes)
- Player and spectator lifecycle events
- Chat and logging events
- Dispatching incoming events to the appropriate subsystem
- Sending locally initiated commands to the server
In short, it is the **top-level event dispatcher** for an active game.
---
## Responsibilities
`GameEventHandler` has four primary responsibilities:
### 1. Sending game-wide commands
UI actions that affect the game as a whole (e.g. advancing the turn, changing phases,
sending chat messages) are translated into protobuf commands and sent to the server
via this class.
Examples include:
- Advancing or reversing the turn order
- Conceding or unconceding
- Changing the active phase
- Leaving the game
- Sending chat messages
These commands are wrapped in `PendingCommand` instances so their lifecycle and
responses can be tracked.
---
### 2. Processing incoming game events
Incoming server messages arrive as a `GameEventContainer`.
`GameEventHandler` is responsible for:
- Emitting lifecycle signals before and after processing
- Dispatching each event to the correct handler
- Forwarding player-scoped events to `PlayerEventHandler` instances
- Handling spectator-only and game-global events directly
This design keeps networking concerns isolated from game logic and UI code.
---
### 3. Managing global game state transitions
Certain events affect the entire game state and require coordinated updates across
multiple subsystems. Examples include:
- Full game state synchronization
- Active player or phase changes
- Game host changes
- Game closure
- Turn reversal
`GameEventHandler` ensures these events are processed in a consistent order and
that all interested systems are notified via Qt signals.
---
### 4. Emitting UI and logging signals
Rather than directly manipulating UI widgets, `GameEventHandler` emits
high-level signals that are consumed by:
- Game widgets
- Player and spectator lists
- Message and event logs
- Status indicators (ready state, deck selection, connection state)
This keeps the handler independent of concrete UI implementations.
---
## Relationship to PlayerEventHandler
`GameEventHandler` and `PlayerEventHandler` work together but have distinct roles:
| GameEventHandler | PlayerEventHandler |
|------------------|--------------------|
| Global game state | Per-player state |
| Turn / phase flow | Zones and cards |
| Player join/leave | Player actions |
| Spectator events | Player-specific events |
| Chat dispatch | Card and zone updates |
When a server event is associated with a specific player, `GameEventHandler`
routes it to the corresponding `PlayerEventHandler`. Events without a player
context are handled directly.
---
## Event Processing Flow
A typical incoming event flow looks like this:
1. `AbstractClient` receives a `GameEventContainer`
2. `GameEventHandler::processGameEventContainer()` is called
3. `containerProcessingStarted()` is emitted
4. Each event is:
- Handled directly **or**
- Forwarded to a `PlayerEventHandler`
5. Logging and UI signals are emitted as needed
6. `containerProcessingDone()` is emitted
This structured flow makes it easy to:
- Suppress UI updates during replays
- Handle reconnections cleanly
- Detect flood protection or error states
---
## Command Lifecycle
Outgoing commands follow a similar structured path:
1. UI action triggers a `handle*()` method
2. A protobuf command is constructed
3. The command is wrapped in a `PendingCommand`
4. `sendGameCommand()` sends it to the server
5. `commandFinished()` receives the response
6. Errors or flood conditions are handled centrally
This approach avoids duplicated error handling across UI code.
---
## Design Goals
`GameEventHandler` is designed to be:
- **Centralized** – one entry point for all game-wide events
- **UI-agnostic** – communicates via signals, not widgets
- **Predictable** – well-defined event ordering and lifecycle
- **Composable** – works in concert with `PlayerEventHandler`
- **Testable** – logic is separated from rendering
---
## Related Classes
- @ref GameEventHandler
- @ref PlayerEventHandler
- `GameEventContainer`
- `PendingCommand`
- `AbstractClient`
- `AbstractGame`
---
## See Also
- @ref GameLogic
- @ref PlayerEventHandler
- @ref GameState

11
doc/doxygen/extra-pages/developer_documentation/network/client/index.md Normal file
View file

@ -0,0 +1,11 @@
@page developer_reference_network_client Client Networking (Overview)
The clients response to various network protocol events and associated handling are described here.
For information about game scoped events, see:
- @subpage game_event_handler
Certain game scoped events may be forwarded to player based handlers. For more information, see:
- @subpage player_event_handler

199
doc/doxygen/extra-pages/developer_documentation/network/client/player_event_handler.md Normal file
View file

@ -0,0 +1,199 @@
@page player_event_handler PlayerEventHandler
## Overview
`PlayerEventHandler` is responsible for applying **player-scoped game events**
to a single `Player` instance. These events modify the player’s board state,
zones, cards, counters, arrows, and associated UI and logging output.
Each `PlayerEventHandler` instance is bound **1:1 to a Player** and is invoked
exclusively by @ref GameEventHandler after basic routing and validation of
incoming server events.
This class represents the lowest-level authoritative application of game state
changes on the client.
---
## Scope and Authority
`PlayerEventHandler` operates under the following guarantees:
- All incoming events are **authoritative** and already validated by the server
- Events refer to valid players, zones, and card identifiers
- Ordering is guaranteed by the server and preserved by `GameEventHandler`
As a result, the handler does **not** perform rule validation or permission
checks. Its responsibility is to *apply* state, not *decide* legality.
---
## Responsibilities
### 1. Applying player-specific state changes
The primary responsibility of `PlayerEventHandler` is to mutate player-owned
state, including:
- Cards (`CardItem`)
- Zones (`CardZoneLogic`)
- Counters (card-level and player-level)
- Attachments and arrows
- Zone configuration flags (reveal / peek behavior)
Many handlers update both **logical state** and **visual/UI state** in tandem.
---
### 2. Coordinating complex card movement
Some events—most notably card movement—require coordinated updates across
multiple systems. For example, `eventMoveCard()`:
- Removes the card from the source zone
- Updates ownership, visibility, and identity
- Handles attachments and arrow cleanup
- Emits undo-draw or move logs
- Inserts the card into the destination zone
- Updates menus, hover state, and graphics
This makes `PlayerEventHandler` intentionally stateful and tightly coupled to
the board implementation.
---
### 3. Emitting logging signals
Rather than writing directly to logs or widgets, `PlayerEventHandler` emits
structured Qt signals describing *what happened*, including:
- Chat messages
- Card movement
- Shuffles and randomization
- Reveals and peeks
- Counter and attribute changes
These signals are consumed by logging systems and UI components, keeping
presentation concerns out of the handler.
Logging signals may be emitted **before or after mutation**, depending on
whether later changes would invalidate log data (e.g. card identity).
---
### 4. Handling cross-player interactions
Although bound to a single player, some events necessarily affect other
players’ state, including:
- Moving cards between players
- Attaching cards to another player’s permanents
- Creating arrows targeting other players or cards
In these cases, `PlayerEventHandler` performs the minimal required mutation
while respecting ownership boundaries enforced elsewhere.
---
## Event Dispatch Model
`PlayerEventHandler` exposes a single public entry point:
- `processGameEvent()`
This method:
1. Receives a generic `GameEvent`
2. Switches on `GameEventType`
3. Extracts the appropriate protobuf extension
4. Forwards the event to a typed handler
This keeps the event routing centralized and makes it easy to audit coverage
when new game events are introduced.
Unhandled events are logged as warnings.
---
## Event Categories
For clarity, event handlers are grouped conceptually into:
- **Chat and randomization**
- Chat messages
- Shuffles
- Dice rolls
- **Arrows and targeting**
- Create / delete arrows
- **Card and token creation**
- Token generation
- Counter creation
- **Card attributes and counters**
- Tapped state
- Power/toughness
- Annotations
- Card- and player-level counters
- **Zone-level operations**
- Card movement
- Zone dumps
- Card destruction
- Attachments
- **Draw and reveal**
- Drawing cards
- Reveals, peeks, and reveal windows
- **Zone configuration**
- Always-reveal and always-look-at-top-card flags
This grouping mirrors the structure of the header file and reflects the
conceptual responsibilities of the class.
---
## Relationship to GameEventHandler
`PlayerEventHandler` is never instantiated or invoked directly by UI code.
Instead:
1. `GameEventHandler` receives a `GameEventContainer`
2. Player-scoped events are routed to the appropriate `PlayerEventHandler`
3. Global or spectator events are handled elsewhere
This separation keeps game-wide logic decoupled from player board state and
makes reconnection and replay handling simpler.
---
## Design Intent
`PlayerEventHandler` is designed to be:
- **Authoritative** – applies server state exactly as received
- **Stateful** – maintains consistency across cards, zones, and UI
- **Explicit** – one handler per event type
- **UI-aware** – updates views and menus as part of state mutation
- **Auditable** – easy to trace what code handles which event
---
## Related Classes
- @ref PlayerEventHandler
- @ref GameEventHandler
- `Player`
- `CardItem`
- `CardZoneLogic`
- `GameEvent`
- `GameEventContext`
---
## See Also
- @ref GameLogicPlayers
- @ref GameLogic

170
doc/doxygen/extra-pages/developer_documentation/network/game_event_handler.md Normal file
View file

@ -0,0 +1,170 @@
@page game_event_handler GameEventHandler
## Overview
`GameEventHandler` is the central coordinator for **game-wide commands and events**.
It acts as the bridge between the networking layer (protobuf messages received from
the server) and the local game model and UI.
Unlike `PlayerEventHandler`, which is responsible for player-scoped state and zones,
`GameEventHandler` handles:
- Global game flow (turns, phases, host changes)
- Player and spectator lifecycle events
- Chat and logging events
- Dispatching incoming events to the appropriate subsystem
- Sending locally initiated commands to the server
In short, it is the **top-level event dispatcher** for an active game.
---
## Responsibilities
`GameEventHandler` has four primary responsibilities:
### 1. Sending game-wide commands
UI actions that affect the game as a whole (e.g. advancing the turn, changing phases,
sending chat messages) are translated into protobuf commands and sent to the server
via this class.
Examples include:
- Advancing or reversing the turn order
- Conceding or unconceding
- Changing the active phase
- Leaving the game
- Sending chat messages
These commands are wrapped in `PendingCommand` instances so their lifecycle and
responses can be tracked.
---
### 2. Processing incoming game events
Incoming server messages arrive as a `GameEventContainer`.
`GameEventHandler` is responsible for:
- Emitting lifecycle signals before and after processing
- Dispatching each event to the correct handler
- Forwarding player-scoped events to `PlayerEventHandler` instances
- Handling spectator-only and game-global events directly
This design keeps networking concerns isolated from game logic and UI code.
---
### 3. Managing global game state transitions
Certain events affect the entire game state and require coordinated updates across
multiple subsystems. Examples include:
- Full game state synchronization
- Active player or phase changes
- Game host changes
- Game closure
- Turn reversal
`GameEventHandler` ensures these events are processed in a consistent order and
that all interested systems are notified via Qt signals.
---
### 4. Emitting UI and logging signals
Rather than directly manipulating UI widgets, `GameEventHandler` emits
high-level signals that are consumed by:
- Game widgets
- Player and spectator lists
- Message and event logs
- Status indicators (ready state, deck selection, connection state)
This keeps the handler independent of concrete UI implementations.
---
## Relationship to PlayerEventHandler
`GameEventHandler` and `PlayerEventHandler` work together but have distinct roles:
| GameEventHandler | PlayerEventHandler |
|------------------|--------------------|
| Global game state | Per-player state |
| Turn / phase flow | Zones and cards |
| Player join/leave | Player actions |
| Spectator events | Player-specific events |
| Chat dispatch | Card and zone updates |
When a server event is associated with a specific player, `GameEventHandler`
routes it to the corresponding `PlayerEventHandler`. Events without a player
context are handled directly.
---
## Event Processing Flow
A typical incoming event flow looks like this:
1. `AbstractClient` receives a `GameEventContainer`
2. `GameEventHandler::processGameEventContainer()` is called
3. `containerProcessingStarted()` is emitted
4. Each event is:
- Handled directly **or**
- Forwarded to a `PlayerEventHandler`
5. Logging and UI signals are emitted as needed
6. `containerProcessingDone()` is emitted
This structured flow makes it easy to:
- Suppress UI updates during replays
- Handle reconnections cleanly
- Detect flood protection or error states
---
## Command Lifecycle
Outgoing commands follow a similar structured path:
1. UI action triggers a `handle*()` method
2. A protobuf command is constructed
3. The command is wrapped in a `PendingCommand`
4. `sendGameCommand()` sends it to the server
5. `commandFinished()` receives the response
6. Errors or flood conditions are handled centrally
This approach avoids duplicated error handling across UI code.
---
## Design Goals
`GameEventHandler` is designed to be:
- **Centralized** – one entry point for all game-wide events
- **UI-agnostic** – communicates via signals, not widgets
- **Predictable** – well-defined event ordering and lifecycle
- **Composable** – works in concert with `PlayerEventHandler`
- **Testable** – logic is separated from rendering
---
## Related Classes
- @ref GameEventHandler
- @ref PlayerEventHandler
- `GameEventContainer`
- `PendingCommand`
- `AbstractClient`
- `AbstractGame`
---
## See Also
- @ref GameLogic
- @ref PlayerEventHandler
- @ref GameState

7
doc/doxygen/extra-pages/developer_documentation/network/index.md Normal file
View file

@ -0,0 +1,7 @@
@page developer_reference_network_overview Network (Overview)
This page provides information about the networking performed by the client and server.
For information about the protocol, see @subpage developer_reference_protocol
For information about the clients response to and handling of protocol messages, see @subpage developer_reference_network_client

199
doc/doxygen/extra-pages/developer_documentation/network/player_event_handler.md Normal file
View file

@ -0,0 +1,199 @@
@page player_event_handler PlayerEventHandler
## Overview
`PlayerEventHandler` is responsible for applying **player-scoped game events**
to a single `Player` instance. These events modify the player’s board state,
zones, cards, counters, arrows, and associated UI and logging output.
Each `PlayerEventHandler` instance is bound **1:1 to a Player** and is invoked
exclusively by @ref GameEventHandler after basic routing and validation of
incoming server events.
This class represents the lowest-level authoritative application of game state
changes on the client.
---
## Scope and Authority
`PlayerEventHandler` operates under the following guarantees:
- All incoming events are **authoritative** and already validated by the server
- Events refer to valid players, zones, and card identifiers
- Ordering is guaranteed by the server and preserved by `GameEventHandler`
As a result, the handler does **not** perform rule validation or permission
checks. Its responsibility is to *apply* state, not *decide* legality.
---
## Responsibilities
### 1. Applying player-specific state changes
The primary responsibility of `PlayerEventHandler` is to mutate player-owned
state, including:
- Cards (`CardItem`)
- Zones (`CardZoneLogic`)
- Counters (card-level and player-level)
- Attachments and arrows
- Zone configuration flags (reveal / peek behavior)
Many handlers update both **logical state** and **visual/UI state** in tandem.
---
### 2. Coordinating complex card movement
Some events—most notably card movement—require coordinated updates across
multiple systems. For example, `eventMoveCard()`:
- Removes the card from the source zone
- Updates ownership, visibility, and identity
- Handles attachments and arrow cleanup
- Emits undo-draw or move logs
- Inserts the card into the destination zone
- Updates menus, hover state, and graphics
This makes `PlayerEventHandler` intentionally stateful and tightly coupled to
the board implementation.
---
### 3. Emitting logging signals
Rather than writing directly to logs or widgets, `PlayerEventHandler` emits
structured Qt signals describing *what happened*, including:
- Chat messages
- Card movement
- Shuffles and randomization
- Reveals and peeks
- Counter and attribute changes
These signals are consumed by logging systems and UI components, keeping
presentation concerns out of the handler.
Logging signals may be emitted **before or after mutation**, depending on
whether later changes would invalidate log data (e.g. card identity).
---
### 4. Handling cross-player interactions
Although bound to a single player, some events necessarily affect other
players’ state, including:
- Moving cards between players
- Attaching cards to another player’s permanents
- Creating arrows targeting other players or cards
In these cases, `PlayerEventHandler` performs the minimal required mutation
while respecting ownership boundaries enforced elsewhere.
---
## Event Dispatch Model
`PlayerEventHandler` exposes a single public entry point:
- `processGameEvent()`
This method:
1. Receives a generic `GameEvent`
2. Switches on `GameEventType`
3. Extracts the appropriate protobuf extension
4. Forwards the event to a typed handler
This keeps the event routing centralized and makes it easy to audit coverage
when new game events are introduced.
Unhandled events are logged as warnings.
---
## Event Categories
For clarity, event handlers are grouped conceptually into:
- **Chat and randomization**
- Chat messages
- Shuffles
- Dice rolls
- **Arrows and targeting**
- Create / delete arrows
- **Card and token creation**
- Token generation
- Counter creation
- **Card attributes and counters**
- Tapped state
- Power/toughness
- Annotations
- Card- and player-level counters
- **Zone-level operations**
- Card movement
- Zone dumps
- Card destruction
- Attachments
- **Draw and reveal**
- Drawing cards
- Reveals, peeks, and reveal windows
- **Zone configuration**
- Always-reveal and always-look-at-top-card flags
This grouping mirrors the structure of the header file and reflects the
conceptual responsibilities of the class.
---
## Relationship to GameEventHandler
`PlayerEventHandler` is never instantiated or invoked directly by UI code.
Instead:
1. `GameEventHandler` receives a `GameEventContainer`
2. Player-scoped events are routed to the appropriate `PlayerEventHandler`
3. Global or spectator events are handled elsewhere
This separation keeps game-wide logic decoupled from player board state and
makes reconnection and replay handling simpler.
---
## Design Intent
`PlayerEventHandler` is designed to be:
- **Authoritative** – applies server state exactly as received
- **Stateful** – maintains consistency across cards, zones, and UI
- **Explicit** – one handler per event type
- **UI-aware** – updates views and menus as part of state mutation
- **Auditable** – easy to trace what code handles which event
---
## Related Classes
- @ref PlayerEventHandler
- @ref GameEventHandler
- `Player`
- `CardItem`
- `CardZoneLogic`
- `GameEvent`
- `GameEventContext`
---
## See Also
- @ref GameLogicPlayers
- @ref GameLogic

15
doc/doxygen/extra-pages/developer_documentation/network/protocol/index.md Normal file
View file

@ -0,0 +1,15 @@
@page developer_reference_protocol Protocol (Overview)
For an overview of the protocol used by the Cockatrice client and server, see:
- @subpage developer_reference_protocol_overview
- @subpage protocol_game_command
For client → server communication, see:
- @subpage protocol_command_container
For server → client communication, see:
- @subpage protocol_server_message
- @subpage protocol_response

114
doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_command_container.md Normal file
View file

@ -0,0 +1,114 @@
@page protocol_command_container CommandContainer (Protocol Concept)
@section cc_overview Overview
CommandContainer is the client-to-server message envelope used for all
client requests in the Cockatrice protocol.
Every client-initiated action is transmitted as a CommandContainer.
The server never sends CommandContainer messages.
This is a protocol-level abstraction and should not be confused with the
generated protobuf accessors or wire-level encoding.
@section cc_lifecycle Lifetime and Ownership
- CommandContainers are created by clients and consumed by the server.
- Each container represents one logical request.
- Containers are processed atomically and in order of arrival.
A container may generate:
- Exactly one RESPONSE message, and
- Zero or more EVENT messages.
@section cc_cmd_id Command Identification
The @c cmd_id field is a client-assigned identifier used to correlate
responses with requests.
Rules:
- @c cmd_id is optional but strongly recommended
- The server echoes @c cmd_id only in RESPONSE messages
- EVENT messages are never associated with a @c cmd_id
The server does not enforce uniqueness of @c cmd_id values.
@section cc_context Command Context
Certain command domains require additional context:
- Room commands require @c room_id
- Game commands require @c game_id
Context fields are ignored for command domains that do not require them.
If a required context field is missing or invalid, the server responds with
@c RespContextError.
@section cc_invariants Invariants
The following rules are enforced by the server:
- Exactly one command domain must be populated
- Commands may be batched only within the same domain
- Context fields must match the active command domain
Violations of these rules result in @c RespInvalidCommand.
@section cc_domains Command Domains
CommandContainer supports the following mutually exclusive command domains:
- Session commands
- Authentication
- User discovery
- Private messaging
- Room commands
- Chat
- Game creation
- Room membership management
- Game commands
- In-game actions
- State mutations
- Moderator commands
- User moderation
- Room moderation
- Admin commands
- Server administration
@section cc_batching Command Batching
A CommandContainer may contain multiple commands of the same domain.
Batching guarantees:
- Commands are processed in the order they appear in the container
- All commands in the batch share the same context
Partial failure behavior is implementation-defined and may vary by domain.
@section cc_dispatch Dispatch
CommandContainers are dispatched by
Server_ProtocolHandler::processCommandContainer().
Dispatch is performed by inspecting which command domain is populated.
Only the first populated domain is considered.
@section cc_errors Error Handling
Common error responses include:
- @c RespLoginNeeded – client is not authenticated
- @c RespInvalidCommand – malformed container or invalid domain usage
- @c RespContextError – missing or invalid room/game context
@section cc_related Related Concepts
- @ref protocol_server_message "ServerMessage"
- @ref protocol_client_states "Client State Machine"
@see Server_ProtocolHandler::processCommandContainer

529
doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_game_command.md Normal file
View file

@ -0,0 +1,529 @@
@page protocol_game_command GameCommand (Protocol Concept)
# Game Commands Reference
This document describes game-level commands (`GameCommandType`) and how they are
handled across the server and client.
Flow overview:
Client
→ GameCommand
→ Server command handler (`Server_Player`, `Server_AbstractParticipant`, or `Server_Game`)
→ GameEvent(s)
→ PlayerEventHandler::event*
## Command Mapping
### `GAME_SAY` (1002)
**Purpose:** Send a chat message during a game.
**Server:**
- `Server_AbstractParticipant::cmdGameSay`
- Validates spectator chat permissions
- Applies chat flood protection
- Emits `Event_GameSay`
- Logs the message to the server database
**Client:**
- `PlayerEventHandler::eventGameSay`
- Adds the chat message to the game log
---
### `SHUFFLE` (1003)
**Purpose:** Shuffle a card zone (usually library).
**Server:**
- `Server_Player::cmdShuffle`
- Only allows shuffling the deck zone
- Rejects if the game has not started or the player has conceded
- Supports partial-range shuffles (`start` / `end`)
- Emits `Event_Shuffle`
- Re-reveals the top card if the deck is being tracked
**Client:**
- `PlayerEventHandler::eventShuffle`
- Closes affected library views
- Clears any revealed top card if necessary
- Updates deck graphics
- Logs the shuffle
---
### `ROLL_DIE` (1005)
**Purpose:** Roll one or more dice.
**Server:**
- Computes random die results
- Emits `Event_RollDie`
**Client:**
- `PlayerEventHandler::eventRollDie`
- Displays the sorted roll results in the game log
---
### `DRAW_CARDS` (1006)
**Purpose:** Draw cards from deck.
**Server:**
- `Server_Player::cmdDrawCards`
- Rejects if the game has not started or the player has conceded
- Moves cards from deck to hand
- Sends full card information privately to the drawing player
- Sends only the draw count to all other players
- Tracks drawn cards for undo
- Updates revealed-top-card state when necessary
- Emits `Event_DrawCards`
**Client:**
- `PlayerEventHandler::eventDrawCards`
- Moves cards from library to hand
- Reveals card identities only when included in the event
- Updates both zones
- Logs the draw
---
### `UNDO_DRAW` (1007)
**Purpose:** Undo a previous draw.
**Server:**
- `Server_Player::cmdUndoDraw`
- Rejects if the game has not started or the player has conceded
- Uses the tracked draw history (`lastDrawList`)
- Moves the most recently drawable card from hand back to the top of the deck
- Emits `Event_GameLogNotice` if undo is no longer possible
**Client:**
- Processed as a normal `MOVE_CARD`
- Detects `Context_UndoDraw`
- Logs the undo draw instead of a normal move
---
### `FLIP_CARD` (1008)
**Purpose:** Flip a card face up or face down.
**Server:**
- Updates the card's face-down state
- Reveals identity when turning face up
- Emits `Event_FlipCard`
**Client:**
- `PlayerEventHandler::eventFlipCard`
- Updates the card identity when revealed
- Changes face-up / face-down state
- Updates card menus
- Logs the flip
---
### `ATTACH_CARD` (1009)
**Purpose:** Attach one card to another.
**Server:**
- Updates attachment relationships
- Emits `Event_AttachCard`
**Client:**
- `PlayerEventHandler::eventAttachCard`
- Updates parent/child attachment links
- Reorganizes affected zones
- Logs attach or detach operations
- Refreshes card actions
---
### `CREATE_TOKEN` (1010)
**Purpose:** Create a token card.
**Server:**
- Creates a new token card
- Emits `Event_CreateToken`
**Client:**
- `PlayerEventHandler::eventCreateToken`
- Creates the token object
- Applies token properties (PT, color, annotation, face-down state)
- Adds it to the requested zone
- Logs token creation
---
### `CREATE_ARROW` (1011)
**Purpose:** Create a visual arrow.
**Server:**
- Creates a visual arrow
- Emits `Event_CreateArrow`
**Client:**
- `PlayerEventHandler::eventCreateArrow`
- Creates the arrow graphics
- Resolves endpoint card names
- Logs arrow creation
---
### `DELETE_ARROW` (1012)
**Purpose:** Remove a visual arrow.
**Server:**
- Removes an existing arrow
- Emits `Event_DeleteArrow`
**Client:**
- `PlayerEventHandler::eventDeleteArrow`
- Removes the arrow graphics
---
### `SET_CARD_ATTR` (1013)
**Purpose:** Set a card attribute.
**Server:**
- Updates one or more card attributes
- Emits `Event_SetCardAttr`
**Client:**
- `PlayerEventHandler::eventSetCardAttr`
- Updates tapped state, color, annotation, power/toughness, face-down state, attacking state, and related visuals
- Logs attribute changes where appropriate
---
### `SET_CARD_COUNTER` (1014)
**Purpose:** Set a card counter.
**Server:**
- Updates the specified card counter
- Emits `Event_SetCardCounter`
**Client:**
- `PlayerEventHandler::eventSetCardCounter`
- Updates the displayed counter value
- Refreshes card actions
- Logs the counter change
---
### `INC_CARD_COUNTER` (1015)
**Purpose:** Increment a card counter.
**Server:**
- Normalizes to a set-counter operation
- Emits `Event_SetCardCounter`
**Client:**
- Processed identically to `SET_CARD_COUNTER`
---
### `READY_START` (1016)
**Purpose:** Mark player as ready.
**Server:**
- Marks the player as ready
- Starts the game once all required players are ready
**Client:**
- Reflected through updated game state events
---
### `CONCEDE` (1017)
**Purpose:** Concede the game.
**Server:**
- Marks the player as conceded
- Returns borrowed cards where appropriate
- Ends the game if only one player remains
**Client:**
- Reflected through updated game state events
---
### `INC_COUNTER` (1018)
**Purpose:** Increment a player counter.
**Server:**
- `Server_Player::cmdIncCounter`
- Rejects if the game has not started or the player has conceded
- Updates the counter value
- Emits `Event_SetCounter` only if the value changed
**Client:**
- `PlayerEventHandler::eventSetCounter`
- Updates the displayed player counter
- Logs the change
---
### `CREATE_COUNTER` (1019)
**Purpose:** Create a player counter.
**Server:**
- `Server_Player::cmdCreateCounter`
- Rejects if the game has not started or the player has conceded
- Allocates a new counter ID
- Creates the counter
- Emits `Event_CreateCounter`
**Client:**
- `PlayerEventHandler::eventCreateCounter`
- Creates the local player counter
---
### `SET_COUNTER` (1020)
**Purpose:** Set a player counter value.
**Server:**
- `Server_Player::cmdSetCounter`
- Rejects if the game has not started or the player has conceded
- Updates the counter value
- Emits `Event_SetCounter` only if the value changed
**Client:**
- `PlayerEventHandler::eventSetCounter`
- Updates the counter value
- Logs the change
---
### `DEL_COUNTER` (1021)
**Purpose:** Delete a player counter.
**Server:**
- `Server_Player::cmdDelCounter`
- Rejects if the game has not started or the player has conceded
- Deletes the counter
- Emits `Event_DelCounter`
**Client:**
- `PlayerEventHandler::eventDelCounter`
- Removes the counter
---
### `NEXT_TURN` (1022)
**Purpose:** Advance to the next turn.
**Server:**
- `Server_Player::cmdNextTurn`
- Rejects if the game has not started
- Conceded players cannot advance turns unless acting as a judge
- Calls `Server_Game::nextTurn()`
**Client:**
- Reflected through subsequent active-player and active-phase events
---
### `SET_ACTIVE_PHASE` (1023)
**Purpose:** Set active phase.
**Server:**
- `Server_Player::cmdSetActivePhase`
- Rejects if the game has not started
- Judges may change the phase at any time
- Normal players may only change the phase during their own active turn
- Calls `Server_Game::setActivePhase()`
**Client:**
- Reflected through updated phase events
---
### `DUMP_ZONE` (1024)
**Purpose:** Dump zone contents.
**Server:**
- Generates a zone summary
- Emits `Event_DumpZone`
**Client:**
- `PlayerEventHandler::eventDumpZone`
- Logs the zone contents summary
---
### `REVEAL_CARDS` (1026)
**Purpose:** Reveal specific cards.
**Server:**
- Reveals cards to one or more players
- Emits `Event_RevealCards`
**Client:**
- `PlayerEventHandler::eventRevealCards`
- Reveals cards in-place or in a reveal window
- Supports temporary peeks
- Updates revealed top cards
- Logs the reveal
---
### `MOVE_CARD` (1027)
**Purpose:** Move a card between zones.
**Server:**
- Moves cards between zones
- Updates ownership and attachments as needed
- Emits `Event_MoveCard`
**Client:**
- `PlayerEventHandler::eventMoveCard`
- Moves the card between zones
- Updates ownership, attachments, IDs and revealed information
- Handles undo-draw context
- Refreshes menus and zone layouts
- Logs the move
---
### `SET_SIDEBOARD_PLAN` (1028)
**Purpose:** Set sideboard configuration.
**Server:**
- `Server_Player::cmdSetSideboardPlan`
- Allowed only before readying for the game
- Requires a loaded deck
- Requires sideboarding to be unlocked
- Stores the current sideboard plan
**Client:**
- No game event is generated
---
### `DECK_SELECT` (1029)
**Purpose:** Select a deck.
**Server:**
- `Server_Player::cmdDeckSelect`
- Allowed only before the game starts
- Loads a deck from either the database or serialized deck data
- Locks sideboarding
- Updates player properties
- Emits `Event_PlayerPropertiesChanged`
- Attaches `Context_DeckSelect`
- Returns the selected deck in the command response
**Client:**
- Reflected through updated player properties and command response
---
### `SET_SIDEBOARD_LOCK` (1030)
**Purpose:** Lock or unlock sideboarding.
**Server:**
- `Server_Player::cmdSetSideboardLock`
- Allowed only before readying
- Toggles sideboard locking
- Clears pending sideboard plans when locking
- Emits `Event_PlayerPropertiesChanged`
- Attaches `Context_SetSideboardLock`
**Client:**
- Reflected through updated player properties
---
### `CHANGE_ZONE_PROPERTIES` (1031)
**Purpose:** Change zone properties.
**Server:**
- `Server_Player::cmdChangeZoneProperties`
- Delegates to the abstract implementation
- Updates top-card revelation if required
- Emits `Event_ChangeZoneProperties`
**Client:**
- `PlayerEventHandler::eventChangeZoneProperties`
- Updates always-reveal-top-card and always-look-at-top-card settings
- Logs property changes
---
### `UNCONCEDE` (1032)
**Purpose:** Undo a concede.
**Server:**
- Restores the player's active status
**Client:**
- Reflected through updated game state events
---
### `JUDGE` (1033)
**Purpose:** Execute commands on behalf of another player.
**Server:**
- `Server_AbstractParticipant::cmdJudge`
- Requires judge privileges
- Executes embedded commands as the selected player
- Marks resulting events as judge-forced
**Client:**
- Transparent; resulting events are processed normally
---
### `REVERSE_TURN` (1034)
**Purpose:** Reverse turn order.
**Server:**
- `Server_Player::cmdReverseTurn`
- Conceded non-judge players cannot use the command
- Delegates to `Server_AbstractParticipant::cmdReverseTurn`
- Toggles turn order
- Emits `Event_ReverseTurn`
**Client:**
- Reflected by subsequent active-player progression
---
## Notes
- Game commands are handled by `Server_Player`, `Server_AbstractParticipant`, or `Server_Game`, depending on the command.
- Only commands that emit `GameEvent`s produce corresponding `PlayerEventHandler` callbacks.
- Some commands modify server state without generating a dedicated client event.
- Judge commands are transport wrappers that execute other game commands on behalf of another player.

76
doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_overview.md Normal file
View file

@ -0,0 +1,76 @@
@page developer_reference_protocol_overview Protocol (Overview)
# Cockatrice Server Protocol – Overview
## Purpose
This document describes the Cockatrice client/server protocol as implemented
by the Cockatrice server. It is intended for developers implementing clients
or modifying the server.
The protocol is **stateful**, **event-driven**, and **asynchronous**.
---
## High-Level Properties
- Encoding: Google Protocol Buffers
- Transport: TCP or WebSocket (transport-agnostic at protocol level)
- Directionality:
- Clients send `CommandContainer`
- Server sends `ServerMessage`
- Responses and events are interleaved
- Clients must handle unsolicited events at any time
---
## Message Envelopes
### Client → Server: CommandContainer
A `CommandContainer` represents one logical client request.
Protocol invariants:
- Exactly one command domain may be used per container
- Multiple commands of the same domain may be batched
- Context is provided via `room_id` or `game_id` when required
Command domains:
- Session commands
- Room commands
- Game commands
- Moderator commands
- Admin commands
---
### Server → Client: ServerMessage
A `ServerMessage` represents either:
- A response to a command (`RESPONSE`)
- An unsolicited event (`*_EVENT`)
Protocol invariants:
- Events may be delivered before or after responses
- Responses reference the original command via `cmd_id`
- Events are never correlated to a command
---
## Asynchronous Model
Clients MUST NOT assume request/response ordering.
Example valid sequence:
1. Client sends JOIN_ROOM
2. Server sends room chat history events
3. Server sends room join notifications
4. Server sends JOIN_ROOM response
---
## Versioning
The server reports a protocol version during connection initialization.
Clients MUST verify compatibility before sending commands.

27
doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_response.md Normal file
View file

@ -0,0 +1,27 @@
@page protocol_response Response (Protocol Concept)
## Overview
`Response` is the server-to-client message sent immediately after a command, using the same `cmd_id` to link to the originating command.
It provides a `Response::ResponseCode` and optionally a `Response::ResponseType` to guide client handling.
## Fields
- **cmd_id** (`uint64`, required) — Command ID this response corresponds to
- **response_code** (`Response::ResponseCode`, optional) — Outcome of the command
## Response Codes
All possible outcome codes are defined in Response::ResponseCode
These describe the result of the command, e.g., success, failure, or special conditions like bans or registration requirements.
## Response Types
Responses are routed according to Response::ResponseType
Each `ResponseType` corresponds to a high-level category, like `JOIN_ROOM` or `DECK_UPLOAD`.
## Extensions
- Protobuf extensions from 100 to max are reserved for future use

171
doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_server_message.md Normal file
View file

@ -0,0 +1,171 @@
@page protocol_server_message ServerMessage (Protocol Concept)
## Overview
`ServerMessage` is the server-to-client message envelope used for all
communication originating from the Cockatrice server.
The server never sends `CommandContainer` messages, and clients never send
`ServerMessage` messages.
A `ServerMessage` represents either:
- A direct response to a client command, or
- An unsolicited event emitted by the server
This document describes `ServerMessage` as a protocol-level concept.
It should not be confused with generated protobuf accessors or wire-level
encoding details.
---
## Lifetime and Delivery
`ServerMessage` instances are emitted by the server and delivered
asynchronously to clients.
Delivery guarantees:
- Messages are delivered in the order sent by the server
- Messages may be delivered at any time
- Events may be delivered before or after responses
Clients **must** be prepared to handle `ServerMessage` objects at all times,
regardless of pending requests.
---
## Message Type
Each `ServerMessage` contains **exactly one payload**, identified by the
`message_type` field.
The following message types are supported:
- `RESPONSE`
- `SESSION_EVENT`
- `ROOM_EVENT`
- `GAME_EVENT_CONTAINER`
A message containing multiple payloads or an unknown type is considered
malformed.
---
## RESPONSE
`RESPONSE` messages are direct replies to client-issued `CommandContainer`
messages.
Characteristics:
- Contain a `Response` payload
- Echo the client-assigned `cmd_id`
- Indicate success or failure of the request
A single `CommandContainer` results in **at most one** `RESPONSE`.
`RESPONSE` messages may be preceded or followed by event messages.
---
## Events
Event messages are unsolicited notifications emitted by the server.
Event message types include:
- `SESSION_EVENT`
- `ROOM_EVENT`
- `GAME_EVENT_CONTAINER`
Event messages:
- Are not correlated to a specific client command
- Do not include a `cmd_id`
- May be delivered at any time
Clients **must** process events independently of responses.
---
## Event Scopes
### Session Events
Session events are global to the client session and may include:
- Server notifications
- Private messages
- User status updates
---
### Room Events
Room events are scoped to a specific room and are delivered only to clients
currently present in that room.
---
### Game Events
Game events are scoped to a specific game and are delivered only to
participating clients.
Game events are grouped within a `GameEventContainer` to allow batching.
---
## Event Batching
Some `ServerMessage` types may contain multiple logical events.
- `GameEventContainer` may batch multiple game events
- Other event types represent a single logical event
Clients must process all contained events **in order**.
---
## Error Semantics
Errors are communicated **exclusively** via `RESPONSE` messages.
Event messages are never used to signal command failure.
Common error responses include:
- `RespInvalidCommand`
- `RespLoginNeeded`
- `RespContextError`
- `RespChatFlood`
---
## Related Concepts
- CommandContainer
- Client State Machine
- Response
---
## Reference Proto Definition
```proto
message ServerMessage {
enum MessageType {
RESPONSE = 0;
SESSION_EVENT = 1;
GAME_EVENT_CONTAINER = 2;
ROOM_EVENT = 3;
}
optional MessageType message_type = 1;
optional Response response = 2;
optional SessionEvent session_event = 3;
optional GameEventContainer game_event_container = 4;
optional RoomEvent room_event = 5;
}
```

285
doc/doxygen/filters/proto2cpp.py Normal file
View file

@ -0,0 +1,285 @@
#!/usr/bin/env python
##
# Doxygen filter for Google Protocol Buffers .proto files.
# This script converts .proto files into C++ style ones
# and prints the output to standard output.
#
# version 0.8-beta OSI
#
# How to enable this filter in Doxygen:
# 1. Generate Doxygen configuration file with command 'doxygen -g <filename>'
# e.g. doxygen -g doxyfile
# 2. In the Doxygen configuration file, find FILE_PATTERNS and add *.proto
# FILE_PATTERNS = *.proto
# 3. In the Doxygen configuration file, find EXTENSION_MAPPING and add proto=C++
# EXTENSION_MAPPING = proto=C++
# 4. In the Doxygen configuration file, find INPUT_FILTER and add this script
# INPUT_FILTER = "python proto2cpp.py"
# 5. Run Doxygen with the modified configuration
# doxygen doxyfile
#
#
# Version 0.8 2018 Bugfix regarding long comments, remove typo
# Version 0.7 2018 Bugfix and extensions have been made by Open Simulation Interface (OSI) Carsten Kuebler https://github.com/OpenSimulationInterface,
# Copyright (C) 2016 Regents of the University of California https://github.com/vgteam/vg
# Copyright (C) 2012-2015 Timo Marjoniemi https://sourceforge.net/p/proto2cpp/wiki/Home/
# All rights reserved.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
#
##
import fnmatch
import inspect
import os
import re
import sys
## Class for converting Google Protocol Buffers .proto files into C++ style output to enable Doxygen usage.
##
## The C++ style output is printed into standard output.<br />
## There are three different logging levels for the class:
## <ul><li>#logNone: do not log anything</li>
## <li>#logErrors: log errors only</li>
## <li>#logAll: log everything</li></ul>
## Logging level is determined by \c #logLevel.<br />
## Error logs are written to file determined by \c #errorLogFile.<br />
## Debug logs are written to file determined by \c #logFile.
#
class proto2cpp:
## Logging level: do not log anything.
logNone = 0
## Logging level: log errors only.
logErrors = 1
## Logging level: log everything.
logAll = 2
## Constructor
#
def __init__(self):
## Debug log file name.
self.logFile = "proto2cpp.log"
## Error log file name.
self.errorLogFile = "proto2cpp.error.log"
## Logging level.
self.logLevel = self.logNone
## Handles a file.
##
## If @p fileName has .proto suffix, it is processed through parseFile().
## Otherwise it is printed to stdout as is except for file \c proto2cpp.py without
## path since it's the script given to python for processing.
##
## @param fileName Name of the file to be handled.
#
def handleFile(self, fileName):
if fnmatch.fnmatch(filename, '*.proto'):
self.log('\nXXXXXXXXXX\nXX ' + filename + '\nXXXXXXXXXX\n\n')
# Open the file. Use try to detect whether or not we have an actual file.
if (sys.version_info >= (3, 0)):
try:
with open(filename, 'r', encoding='utf8') as inputFile:
self.parseFile(inputFile)
pass
except IOError as e:
self.logError('the file ' + filename + ' could not be opened for reading')
else:
# Python 2 code in this block
try:
with open(filename, 'r') as inputFile:
self.parseFile(inputFile)
pass
except IOError as e:
self.logError('the file ' + filename + ' could not be opened for reading')
elif not fnmatch.fnmatch(filename, os.path.basename(inspect.getfile(inspect.currentframe()))):
self.log('\nXXXXXXXXXX\nXX ' + filename + '\nXXXXXXXXXX\n\n')
if (sys.version_info > (3, 0)):
try:
with open(filename, 'r', encoding='utf8') as theFile:
output = ''
for theLine in theFile:
output += theLine
print(output)
self.log(output)
pass
except IOError as e:
self.logError('the file ' + filename + ' could not be opened for reading')
else:
# Python 2 code in this block
try:
with open(filename, 'r') as theFile:
output = ''
for theLine in theFile:
output += theLine
print(output)
self.log(output)
pass
except IOError as e:
self.logError('the file ' + filename + ' could not be opened for reading')
else:
self.log('\nXXXXXXXXXX\nXX ' + filename + ' --skipped--\nXXXXXXXXXX\n\n')
## Parser function.
##
## The function takes a .proto file object as input
## parameter and modifies the contents into C++ style.
## The modified data is printed into standard output.
##
## @param inputFile Input file object
#
def parseFile(self, inputFile):
# Go through the input file line by line.
isEnum = False
isPackage = False
isMultilineComment = False
# This variable is here as a workaround for not getting extra line breaks (each line
# ends with a line separator and print() method will add another one).
# We will be adding lines into this var and then print the var out at the end.
theOutput = ''
for line in inputFile:
# Search for comment ("//") and add one more slash character ("/") to the comment
# block to make Doxygen detect it.
matchComment = re.search("//", line)
# Search for semicolon and if one is found before comment, add a third slash character
# ("/") and a smaller than ("<") character to the comment to make Doxygen detect it.
matchSemicolon = re.search(";", line)
if matchSemicolon is not None and (matchComment is not None and matchSemicolon.start() < matchComment.start()):
comment = "///<" + line[matchComment.end():]
# Replace '.' in nested message references with '::'
# don't work for multi-nested references and generates problems with URLs and acronyms
#comment = re.sub(r'\s(\w+)\.(\w+)\s', r' \1::\2 ', comment)
line = line[:matchComment.start()]
elif matchComment is not None:
if isMultilineComment:
comment = " * " + line[matchComment.end():]
else:
comment = "/** " + line[matchComment.end():]
isMultilineComment = True
# replace '.' in nested message references with '::'
# don't work for multi-nested references and generates problems with URLs and acronyms
#comment = re.sub(r'\s(\w+)\.(\w+)\s', r' \1::\2 ', comment)
line = line[:matchComment.start()]
else:
comment = ""
# End multiline comment, if there is no comment or if there are some chars before the comment.
if (matchComment is None or len(line.strip())>0) and isMultilineComment:
theOutput += " */\n"
isMultilineComment = False
# line = line.replace(".", "::") but not in quoted strings (Necessary for import statement)
line = re.sub(r'\.(?=(?:[^"]*"[^"]*")*[^"]*$)',r'::',line)
# Search for " option ...;", remove it
line = re.sub(r'\boption\b[^;]+;', r'', line)
# Search for " package ", make a namespace
matchPackage = re.search(r"\bpackage\b", line)
if matchPackage is not None:
isPackage = True
# Convert to C++-style separator and block instead of statement
line = "namespace" + line[:matchPackage.start()] + line[matchPackage.end():].replace(";", " {")
# Search for " repeated " fields and make them ...
#matchRepeated = re.search(r"\brepeated\b", line)
#if matchRepeated is not None:
# # Convert
# line = re.sub(r'\brepeated\s+(\S+)', r' repeated \1', line)
# Search for "enum", start changing all semicolons (";") to commas (",").
matchEnum = re.search(r"\benum\b", line)
if matchEnum is not None:
isEnum = True
# Search semicolon if we have detected an enum, and replace semicolon with comma.
if isEnum is True and matchSemicolon is not None:
line = line.replace(";", ",")
# Search for a closing brace.
matchClosingBrace = re.search("}", line)
if isEnum is True and matchClosingBrace is not None:
line = line[:matchClosingBrace.start()] + "};" + line[matchClosingBrace.end():]
isEnum = False
elif isEnum is False and matchClosingBrace is not None:
# Message (to be struct) ends => add semicolon so that it'll
# be a proper C(++) struct and Doxygen will handle it correctly.
line = line[:matchClosingBrace.start()] + "};" + line[matchClosingBrace.end():]
# Replacements change start of comment...
matchMsg = re.search(r"\bmessage\b", line)
if matchMsg is not None:
line = line[:matchMsg.start()] + "struct" + line[matchMsg.end():]
# Replacements change start of comment...
matchExt = re.search(r"\bextend\b", line)
if matchExt is not None:
a_extend = line[matchExt.end():]
matchName = re.search(r"\b\w[\S:]*\b", a_extend)
if matchName is not None:
name = a_extend[matchName.start():matchName.end()]
name = re.sub(r'\w+::',r'',name)
a_extend = a_extend[:matchName.start()] + name + ": public " + a_extend[matchName.start():]
else:
a_extend = "_Dummy: public " + a_extend;
line = line[:matchExt.start()] + "struct " + a_extend
theOutput += (line.strip() + ' ' + comment.strip()).strip() + '\n'
if isPackage:
# Close the package namespace
theOutput += "}"
isPackage = False
# Now that we've got all lines in the string let's split the lines and print out
# one by one.
# This is a workaround to get rid of extra empty line at the end which print() method adds.
lines = theOutput.splitlines()
for line in lines:
if len(line) > 0:
print(line) # Add linebreak to generate documentation correct.
self.log(line + '\n')
## Writes @p string to log file.
##
## #logLevel must be #logAll or otherwise the logging is skipped.
##
## @param string String to be written to log file.
#
def log(self, string):
if self.logLevel >= self.logAll:
with open(self.logFile, 'a') as theFile:
theFile.write(string)
## Writes @p string to error log file.
##
## #logLevel must be #logError or #logAll or otherwise the logging is skipped.
##
## @param string String to be written to error log file.
#
def logError(self, string):
if self.logLevel >= self.logError:
with open(self.errorLogFile, 'a') as theFile:
theFile.write(string)
converter = proto2cpp()
# Doxygen will give us the file names
for filename in sys.argv[1:]:
converter.handleFile(filename)
# end of file