Running Examples

Relevant source files

• examples/config.rs
• examples/funds.rs
• examples/lookup_cik.rs
• src/config/app_config.rs

This page demonstrates how to run the example programs included in the repository. Each example illustrates specific functionality of the sec-fetcher system, from basic configuration validation to fetching company data from the SEC EDGAR API. These examples serve as practical starting points for understanding how to integrate the library into your own applications.

For detailed information about configuring the application before running these examples, see Configuration System. For understanding the underlying network layer and data fetching mechanisms, see Network Layer & SecClient and Data Fetching Functions.

Example Programs Overview

The repository includes four example programs located in the examples/ directory. Each demonstrates different aspects of the system:

Sources: examples/config.rs:1-18 examples/funds.rs:1-19 examples/lookup_cik.rs:1-75

Example Program Architecture

Diagram: Example Programs and System Integration

Sources: examples/config.rs:1-18 examples/funds.rs:1-19 examples/lookup_cik.rs:1-75

config.rs - Configuration Validation

Purpose : Load and display the current application configuration to verify that configuration files are properly formatted and credentials are correctly set.

How to Run :

Expected Output : The example displays the merged configuration in JSON format, showing values from the configuration file merged with defaults.

Code Flow :

graph TB
    Start["main()
entry point\nexamples/config.rs:4"]
Load["ConfigManager::load()\nLoad config from file\nexamples/config.rs:13"]
GetConfig["config_manager.get_config()\nRetrieve AppConfig reference\nexamples/config.rs:15"]
Pretty["config.pretty_print()\nSerialize to JSON\nexamples/config.rs:16"]
Print["print! macro\nDisplay formatted config\nexamples/config.rs:16"]
End["Program exit"]
Start --> Load
 
   Load --> GetConfig
 
   GetConfig --> Pretty
 
   Pretty --> Print
 
   Print --> End

Key Functions Used :

What This Demonstrates :

• Basic configuration loading workflow
• Configuration file resolution and merging
• Validation of configuration structure

Sources: examples/config.rs:1-18 src/config/app_config.rs:1-159

funds.rs - Investment Company Dataset

Purpose : Fetch the complete investment company series and class dataset from the SEC EDGAR API, demonstrating network client initialization and basic data fetching.

How to Run :

Expected Output : A list of investment company records, each containing series information, fund names, CIKs, and classification details. The output format is the Debug representation of the Ticker structs.

Code Flow :

graph TB
    Start["#[tokio::main] async fn main()\nexamples/funds.rs:6-7"]
LoadCfg["ConfigManager::load()\nexamples/funds.rs:8"]
CreateClient["SecClient::from_config_manager()\nInitialize HTTP client\nexamples/funds.rs:9"]
FetchData["fetch_investment_company_series_and_class_dataset()\nNetwork request to SEC API\nexamples/funds.rs:11"]
LoopStart["for fund in funds\nIterate results\nexamples/funds.rs:13"]
PrintFund["print! macro\nDisplay fund Debug output\nexamples/funds.rs:14"]
End["Return Ok(())\nexamples/funds.rs:17"]
Start --> LoadCfg
 
   LoadCfg --> CreateClient
 
   CreateClient --> FetchData
 
   FetchData --> LoopStart
 
   LoopStart --> PrintFund
 
   PrintFund -->|More funds| LoopStart
 
   LoopStart -->|Done| End

Key Functions and Structures :

What This Demonstrates :

• Async/await pattern usage with tokio
• SecClient initialization from configuration
• Network function invocation
• Iteration over fetched data structures

Sources: examples/funds.rs:1-19

lookup_cik.rs - CIK Lookup and Submission Retrieval

Purpose : Demonstrate CIK (Central Index Key) lookup by ticker symbol and retrieval of company submissions, with special handling for NPORT-P filings.

How to Run :

Replace AAPL with any valid ticker symbol.

Expected Output :

• The CIK number for the ticker
• URL to the SEC submissions JSON
• Most recent NPORT-P submission (if the company files NPORT-P forms)
• Or a list of other submission types (e.g., 10-K)
• EDGAR archive URLs for each submission

Execution Flow with Code Entities :

Command-Line Argument Handling :

The example requires exactly one argument (the ticker symbol). The argument parsing logic is implemented at examples/lookup_cik.rs:10-14:

args.len() check → if not 2, print usage and exit
ticker_symbol = args[1]

Key Code Entities :

What This Demonstrates :

• Command-line argument parsing using std::env::args()
• Error handling with Result and Option types
• Conditional logic based on filing types
• Method chaining for data transformation
• URL generation from structured data

Sources: examples/lookup_cik.rs:1-75

Prerequisites and Common Patterns

Configuration Requirement : All examples (except config.rs) require a valid configuration file with at least an email address set. See Configuration System for setup instructions.

Common Code Pattern Across Examples :

All examples follow this pattern:

1. Load configuration using ConfigManager::load()
2. Initialize SecClient from the configuration
3. Call network functions to fetch data
4. Process and display results

Error Handling : Examples use the ? operator extensively to propagate errors and return Result<(), Box<dyn Error>> from main(). This allows errors to bubble up with descriptive messages.

Async Runtime : Examples that perform network operations use #[tokio::main] to enable the async runtime, allowing await syntax for asynchronous operations.

Sources: examples/config.rs:1-18 examples/funds.rs:1-19 examples/lookup_cik.rs:1-75

Running Examples in Development Mode

When running examples, the application may detect development mode based on environment variables or the presence of certain files. Development mode affects:

• Cache behavior : May use more aggressive caching strategies
• Logging verbosity : May produce more detailed output
• Rate limiting : May use relaxed throttling policies for testing

Refer to Utility Functions for details on development mode detection.

Next Steps

After running these examples:

• Explore the Network Layer & SecClient to understand HTTP client configuration
• Learn about Data Fetching Functions for all available network operations
• Review Data Models & Enumerations to understand returned data structures
• See Main Application Flow for production usage patterns

Sources: examples/config.rs:1-18 examples/funds.rs:1-19 examples/lookup_cik.rs:1-75