# Examples Guide

## Running Examples

Examples are organized by sync/async mode:

```bash
# Sync examples
cargo run --features sync --example connect
cargo run --features sync --example market_data
cargo run --features sync --example positions

# Async examples  
cargo run --features async --example async_connect
cargo run --features async --example async_market_data
cargo run --features async --example async_positions
```

## Example Categories

### Connection & Setup
- `connect` / `async_connect` - Basic connection to TWS/Gateway
- `connection_monitoring` / `async_connection_monitoring` - Monitor connection status

### Market Data
- `market_data` / `async_market_data` - Real-time quotes
- `historical_data` / `async_historical_data` - Historical bars
- `tick_by_tick_*` - Tick-by-tick data streams
- `realtime_bars` / `async_realtime_bars` - 5-second bars

### Account & Portfolio
- `positions` / `async_positions` - Current positions
- `account_summary` / `async_account_summary` - Account values
- `pnl` / `async_pnl` - Profit and loss tracking

### Orders & Execution
- `place_order` / `async_place_order` - Submit orders
- `order_management` / `async_order_management` - Modify/cancel orders
- `executions` / `async_executions` - Execution reports

### Options
- `option_chain` / `async_option_chain` - Option contracts
- `calculate_option_price` / `async_calculate_option_price` - Option pricing

### News & Events
- `news_bulletins` / `async_news_bulletins` - News headlines
- `wsh_metadata` / `async_wsh_metadata` - Wall Street Horizon events

## Writing Examples

### Basic Structure (Sync)
```rust
use ibapi::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect
    let client = Client::connect("127.0.0.1:4002", 100)?;
    println!("Connected to TWS version {}", client.server_version());
    
    // Perform operations
    let time = client.server_time()?;
    println!("Server time: {}", time);
    
    Ok(())
}
```

### Basic Structure (Async)
```rust
use ibapi::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect
    let client = Client::connect("127.0.0.1:4002", 100).await?;
    println!("Connected to TWS version {}", client.server_version());
    
    // Perform operations
    let time = client.server_time().await?;
    println!("Server time: {}", time);
    
    Ok(())
}
```

## Common Patterns in Examples

### Handling Subscriptions (Sync)
```rust
let subscription = client.market_data(&contract).subscribe()?;

for update in subscription.timeout_iter(Duration::from_secs(30)) {
    match update? {
        MarketData::Price(price) => {
            println!("Price: {}", price);
        },
        MarketData::Size(size) => {
            println!("Size: {}", size);
        },
        _ => {}
    }
}
```

### Handling Subscriptions (Async)
```rust
use futures::StreamExt;
use tokio::time::timeout;

let mut subscription = client.market_data(&contract).subscribe().await?;

while let Ok(Some(update)) = timeout(
    Duration::from_secs(30),
    subscription.next()
).await {
    match update? {
        MarketData::Price(price) => {
            println!("Price: {}", price);
        },
        MarketData::Size(size) => {
            println!("Size: {}", size);
        },
        _ => {}
    }
}
```

### Error Handling
```rust
fn main() {
    if let Err(e) = run() {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

fn run() -> Result<(), Box<dyn std::error::Error>> {
    // Main logic here
    Ok(())
}
```

### Contract Creation
```rust
use ibapi::contracts::Contract;

// Stock
let stock = Contract::stock("AAPL");

// Future
let future = Contract::futures("ES")
    .last_trade_date_or_contract_month("202312")
    .build();

// Option
let option = Contract::option("AAPL", "20240119", 150.0, "C");

// Forex
let forex = Contract::forex("EUR", "USD");
```

## Environment Setup for Examples

### Enable Logging
```bash
# Basic info
RUST_LOG=info cargo run --features sync --example market_data

# Debug messages
RUST_LOG=debug cargo run --features sync --example market_data

# Trace everything
RUST_LOG=trace cargo run --features sync --example market_data

# Module-specific
RUST_LOG=ibapi::transport=debug cargo run --features sync --example market_data
```

### Record Messages
```bash
# Save all TWS communication
IBAPI_RECORDING_DIR=/tmp/tws-messages cargo run --features sync --example market_data

# Files created:
# /tmp/tws-messages/requests_20240315_143022.txt
# /tmp/tws-messages/responses_20240315_143022.txt
```

## Adding New Examples

1. Create file in appropriate directory:
   - `examples/sync/` for synchronous
   - `examples/async/` for asynchronous

2. Add to `Cargo.toml`:
```toml
[[example]]
name = "your_example"
path = "examples/sync/your_example.rs"
required-features = ["sync"]

[[example]]
name = "async_your_example"
path = "examples/async/your_example.rs"
required-features = ["async"]
```

3. Follow naming convention:
   - Sync: `example_name.rs`
   - Async: `async_example_name.rs` (if there's a sync version)

4. Include helpful comments and error handling

5. Test both modes if applicable