🚀 Quick Start

⚡ Complete Setup (2 minutes)

# 1️⃣ Install PHICODE runtime
pip install phicode

# 2️⃣ Install VS Code extension
code --install-extension Banes-Lab.phicode

# 3️⃣ Create and run your first PHICODE file
echo 'ƒ greet(name): ⟲ f"Hello, {name}!"' > hello.φ
echo 'π(greet("PHICODE"))' >> hello.φ
phicode hello.φ
# Output: Hello, PHICODE!

✅ Verify Everything Works

• Open Command Palette (Ctrl+Shift+P)
• Run PHICODE: Show Symbol Tutorial
• Create a .φ file and see syntax highlighting
• Use phicode filename.φ to execute directly

🎯 Complete Workflow: Edit in VS Code with full language support, then execute directly with the runtime — no intermediate conversion steps!

📖 Table of Contents

• 🎯 Core Features
• ⚙️ Installation & Setup
• 🔧 Configuration
• 📝 Usage Examples
• 🧠 Symbol Reference
• 🛠️ Development Features
• ♿ Accessibility
• 🤝 Contributing
• ❓ Support & FAQ
• 📊 Performance

🎯 Core Features

🔄 Complete PHICODE Ecosystem

• VS Code Extension: Advanced editing, conversion, and development tools
• Runtime Engine: Direct execution of .φ files via phicode command
• Import System: Seamless integration with Python projects
• Bidirectional Workflow: Convert between Python and PHICODE instantly

🧠 Intelligent Language Support

• Syntax Highlighting: Custom TextMate grammar for PHICODE symbols
• Auto-completion: Context-aware symbol suggestions with fuzzy matching
• IntelliSense: Hover documentation explaining each symbol's meaning
• Go-to-Definition: Navigate across PHICODE and Python files seamlessly

🎨 Enhanced Developer Experience

• Smart Formatting: Automatic code beautification with configurable rules
• Real-time Linting: Immediate feedback for syntax errors and best practices
• Refactoring Tools: Rename symbols across entire projects
• Code Actions: Quick fixes and bulk conversion utilities

🚀 Production-Ready Runtime

• Direct Execution: Run .φ files without conversion using phicode script.φ
• Module Imports: Import PHICODE modules directly in Python projects
• Performance Optimization: Thread-safe LRU cache with disk persistence
• PYC Integration: Bytecode caching for fast repeated execution

📚 Learning & Documentation

• Interactive Tutorial: Built-in symbol reference with live examples
• Progressive Disclosure: Beginner-friendly with advanced features accessible
• Multilingual Examples: Python equivalent shown alongside PHICODE
• Comprehensive Docs: Complete guide for all skill levels

⚙️ Installation & Setup

📋 System Requirements

🎯 Complete Installation Guide

Step 1: Install PHICODE Runtime Engine

# 🚀 Install the PHICODE runtime for executing .φ files
pip install phicode

# ✅ Verify runtime installation
phicode --version

Step 2: Install VS Code Extension

# Via VS Code Extensions view
1. Open Extensions (Ctrl+Shift+X)
2. Search "PHICODE"
3. Click "Install" on "Banes-Lab.phicode"

# Via Command Line
code --install-extension Banes-Lab.phicode

✅ Complete Setup Verification

# 1️⃣ Check VS Code extension
code --list-extensions | grep phicode
# Expected: Banes-Lab.phicode@1.0.1

# 2️⃣ Verify PHICODE runtime
phicode --help
# Should show runtime commands

# 3️⃣ Test complete workflow
echo 'π("Hello, PHICODE!")' > test.φ
phicode test.φ
# Expected output: Hello, PHICODE!

💡 Pro Tip: The VS Code extension handles editing and conversion, while the runtime engine executes your PHICODE files directly!

🔧 Configuration

⚙️ Extension Settings

Access via File → Preferences → Settings → Extensions → PHICODE

🎛️ Core Configuration

{
  "phicode.autoConvert": true,
  "phicode.symbolHints": true,
  "phicode.formatting.spaceAroundOperators": true,
  "phicode.formatting.blankLinesAroundClasses": 2,
  "phicode.formatting.blankLinesAroundFunctions": 1
}

🎨 Appearance Settings

{
  "[phicode]": {
    "editor.fontSize": 14,
    "editor.fontFamily": "'Fira Code', 'SF Mono', Monaco, Consolas",
    "editor.fontLigatures": true,
    "editor.insertSpaces": true,
    "editor.tabSize": 4,
    "editor.formatOnSave": true,
    "editor.formatOnType": true
  }
}

🔗 File Associations

PHICODE automatically associates with .ɸ files. To customize:

{
  "files.associations": {
    "*.phi": "phicode",
    "*.phicode": "phicode"
  }
}

⌨️ Keyboard Shortcuts

📝 Usage Examples

🚀 Complete PHICODE Workflow

1️⃣ Create Your First PHICODE File

# Create a new .φ file
touch fibonacci.φ

2️⃣ Write PHICODE Code

# fibonacci.φ - Calculate Fibonacci sequence
ƒ fibonacci(n):
    ¿ n <= 1:
        ⟲ n
    ⋄:
        ⟲ fibonacci(n-1) + fibonacci(n-2)

ƒ main():
    π("Fibonacci sequence:")
    ∀ i ∈ range(10):
        result = fibonacci(i)
        π(f"fib({i}) = {result}")

¿ __name__ ≡ "__main__":
    main()

3️⃣ Execute Directly with PHICODE Runtime

# Run PHICODE file directly - no conversion needed!
phicode fibonacci.φ

# Output:
# Fibonacci sequence:
# fib(0) = 0
# fib(1) = 1
# fib(2) = 1
# fib(3) = 2
# fib(4) = 3
# ...

4️⃣ Import PHICODE Modules in Python

# main.py - Import and use PHICODE modules
from phicode_engine.core.phicode_importer import install_phicode_importer

# Enable PHICODE imports
install_phicode_importer(".")

# Import your PHICODE module directly!
import fibonacci  # Automatically finds and loads fibonacci.φ

# Use PHICODE functions in regular Python
result = fibonacci.fibonacci(10)
print(f"Result from PHICODE: {result}")

🐍 Python to PHICODE Conversion Examples

Basic Functions & Classes

Before (Python):

def calculate_area(radius):
    if radius <= 0:
        raise ValueError("Radius must be positive")
    return 3.14159 * radius ** 2

class Circle:
    def __init__(self, radius):
        self.radius = radius
    
    def area(self):
        return calculate_area(self.radius)
    
    def __str__(self):
        return f"Circle(radius={self.radius})"

After (PHICODE):

ƒ calculate_area(radius):
    ¿ radius <= 0:
        ↑ ValueError("Radius must be positive")
    ⟲ 3.14159 * radius ** 2

ℂ Circle:
    ƒ __init__(self, radius):
        self.radius = radius
    
    ƒ area(self):
        ⟲ calculate_area(self.radius)
    
    ƒ __str__(self):
        ⟲ f"Circle(radius={self.radius})"

Advanced Control Flow & Exception Handling

Complex Exception Handling:

⟳ ƒ fetch_and_process_data(url):  # async def
    ∴:  # try
        ⌛ response = http_client.get(url)  # await
        data = response.json()
        
        ¿ data ≡ Ø:  # if data is None
            ↑ ValueError("No data received")
            
        ∀ item ∈ data:  # for item in data
            ¿ ¬ validate_item(item):  # if not validate_item(item)
                ⇉  # continue
            process_item(item)
            
    ⛒ HTTPError ↦ e:  # except HTTPError as e
        π(f"HTTP error occurred: {e}")
        ⟲ Ø
    ⛒ JSONDecodeError ↦ e:  # except JSONDecodeError as e
        π(f"JSON parsing failed: {e}")
        ⟲ Ø
    ⇗:  # finally
        ⌛ cleanup_resources()

Data Processing & Comprehensions

List/Dict Comprehensions:

# Data processing with mathematical elegance
ƒ analyze_dataset(raw_data):
    # Filter and transform data
    clean_data = [item ∀ item ∈ raw_data ¿ item ≠ Ø ∧ item > 0]
    
    # Statistical calculations
    mean_value = sum(clean_data) / len(clean_data)
    variance = sum((x - mean_value)**2 ∀ x ∈ clean_data) / len(clean_data)
    
    # Create results dictionary
    results = {
        'count': len(clean_data),
        'mean': mean_value,
        'variance': variance,
        'std_dev': variance**0.5,
        'outliers': [x ∀ x ∈ clean_data ¿ abs(x - mean_value) > 2 * variance**0.5]
    }
    
    ⟲ results

🔄 Module Import System

Creating PHICODE Packages

Project Structure:

my_project/
├── __init__.φ          # Package initialization
├── math_utils.φ        # Mathematical utilities
├── data_processing.φ   # Data processing functions
└── visualization.φ     # Plotting and visualization

Package Initialization (init.φ):

# __init__.φ - Package initialization
← .math_utils ⇒ fibonacci, prime_check
← .data_processing ⇒ clean_dataset, analyze_trends
← .visualization ⇒ plot_results, create_dashboard

π("PHICODE Math Package loaded successfully!")

Cross-Language Integration

Python Script Using PHICODE Modules:

# app.py - Main application in Python
from phicode_engine.core.phicode_importer import install_phicode_importer
import numpy as np
import matplotlib.pyplot as plt

# Enable PHICODE imports
install_phicode_importer("./phicode_modules")

# Import PHICODE modules
import my_project

def main():
    # Generate test data
    data = np.random.normal(100, 15, 1000).tolist()
    
    # Use PHICODE functions for analysis
    stats = my_project.analyze_dataset(data)
    
    # Display results
    print("Dataset Analysis Results:")
    for key, value in stats.items():
        print(f"  {key}: {value}")
    
    # Use PHICODE visualization
    my_project.plot_results(stats)
    plt.show()

if __name__ == "__main__":
    main()

🧮 Mathematical & Scientific Computing

Numerical Algorithms

# numerical_methods.φ - Advanced mathematical computations
⇒ math

ƒ newton_raphson(f, df, x0, tolerance=1e-7, max_iterations=100):
    """Newton-Raphson method for finding function roots"""
    x = x0
    ∀ i ∈ range(max_iterations):
        fx = f(x)
        ¿ abs(fx) < tolerance:
            ⟲ x
        
        dfx = df(x)
        ¿ abs(dfx) < 1e-15:  # Avoid division by zero
            ↑ ValueError("Derivative too close to zero")
        
        x = x - fx / dfx
    
    ↑ ValueError(f"Failed to converge after {max_iterations} iterations")

ƒ integrate_simpson(f, a, b, n=1000):
    """Simpson's rule for numerical integration"""
    ¿ n % 2 ≠ 0:
        n += 1  # Ensure even number of intervals
    
    h = (b - a) / n
    x = a
    sum_val = f(a)
    
    ∀ i ∈ range(1, n):
        x += h
        ¿ i % 2 ≡ 0:
            sum_val += 2 * f(x)
        ⋄:
            sum_val += 4 * f(x)
    
    sum_val += f(b)
    ⟲ (h / 3) * sum_val

# Example usage
¿ __name__ ≡ "__main__":
    # Find root of x² - 2 = 0 (should be √2)
    f = λ x: x**2 - 2
    df = λ x: 2*x
    
    root = newton_raphson(f, df, 1.0)
    π(f"√2 ≈ {root}")
    
    # Integrate x² from 0 to 1 (should be 1/3)
    integral = integrate_simpson(λ x: x**2, 0, 1)
    π(f"∫₀¹ x² dx ≈ {integral}")

🚀 Runtime Execution Options

Direct Execution

# Run PHICODE files directly
phicode script.φ                    # Execute script.φ
phicode module_name                  # Run module by name
phicode                             # Run main.φ from current directory (default)

# With Python arguments
phicode script.φ arg1 arg2 arg3     # Pass arguments to script
phicode main.φ --verbose --debug    # Arguments passed to main.φ

Default Execution Behavior

# When no arguments provided, automatically looks for main.φ
cd my_project/
phicode                             # Executes ./main.φ if it exists

# Equivalent to:
phicode main.φ

Project Structure for Default Execution

Recommended Project Layout:

my_phicode_project/
├── main.φ              # Entry point (executed by default)
├── utils.φ             # Utility functions
├── data_processing.φ   # Data processing module
├── models/
│   ├── __init__.φ      # Package initialization
│   ├── linear.φ        # Linear models
│   └── neural.φ        # Neural network models
└── tests/
    ├── test_main.φ     # Unit tests
    └── test_utils.φ    # Utility tests

Example main.φ:

# main.φ - Project entry point
← utils ⇒ setup_logging, parse_arguments
← data_processing ⇒ load_dataset, preprocess
← models ⇒ LinearRegressor, NeuralNetwork

ƒ main():
    """Main application entry point"""
    setup_logging()
    args = parse_arguments()
    
    π("🚀 Starting PHICODE application...")
    
    # Load and process data
    data = load_dataset(args.data_path)
    processed_data = preprocess(data)
    
    # Train model based on arguments
    ¿ args.model_type ≡ "linear":
        model = LinearRegressor()
    ⋄:
        model = NeuralNetwork()
    
    model.train(processed_data)
    π(f"✅ Model training completed: {model.accuracy:.2%}")

¿ __name__ ≡ "__main__":
    main()

Run your project:

# Navigate to project directory
cd my_phicode_project/

# Execute main.φ automatically
phicode

# Same as running:
phicode main.φ

# With arguments
phicode --model-type neural --data-path ./data/training.csv

🧠 Symbol Reference

🔢 Core Language Constructs

🔀 Control Flow

🎯 Flow Control

⚡ Exception Handling

🔗 Import & Context

📊 Constants & Operators

🔧 Advanced Constructs

🔍 Quick Symbol Lookup

📝 Interactive Learning: Use Ctrl+Shift+P → "PHICODE: Show Symbol Tutorial" for hands-on exploration with live examples.

🛠️ Development Features

🎨 Code Formatting

PHICODE includes a sophisticated formatter that maintains mathematical elegance:

Formatting Rules:

• Symbol Spacing: Consistent spacing around mathematical operators
• Hierarchical Indentation: Clear visual structure for nested blocks
• Line Length Management: Automatic wrapping for readability
• Comment Preservation: Maintains documentation integrity

Configuration Example:

{
  "phicode.formatting.spaceAroundOperators": true,
  "phicode.formatting.spaceAfterCommas": true,
  "phicode.formatting.blankLinesAroundClasses": 2,
  "phicode.formatting.blankLinesAroundFunctions": 1
}

🔍 Real-time Linting

Advanced Error Detection:

• Symbol Validation: Ensures proper PHICODE symbol usage
• Context Analysis: Validates symbols in appropriate contexts
• Performance Optimization: Debounced linting reduces CPU usage
• Educational Feedback: Helpful error messages for learning

Linting Features:

• ✅ Function Declaration Validation: Proper ƒ usage
• ✅ Import Statement Checking: Correct ⇒ and ← syntax
• ✅ Loop Context Verification: ⇲/⇉ only in loops
• ✅ Async Context Validation: ⌛ only in ⟳ functions

🧭 Navigation & IntelliSense

Go-to-Definition Features:

• Cross-file Navigation: Jump between PHICODE and Python files
• Symbol Indexing: Workspace-wide symbol tracking
• Method Resolution: Smart method and property lookup
• Import Following: Navigate to imported modules

Auto-completion Capabilities:

• Context-aware Suggestions: Different symbols for different scopes
• Fuzzy Matching: Type partial keywords for symbol suggestions
• Documentation Integration: Hover tooltips with Python equivalents
• Snippet Expansion: Complete code patterns with Tab completion

🔄 Refactoring Tools

Rename Provider:

// Rename a symbol across all project files
// Works bidirectionally: PHICODE ↔ Python
Rename: 'ƒ' → 'def' // Updates all Python files
Rename: 'def' → 'ƒ' // Updates all PHICODE files

Code Actions:

• Line-level Conversion: Quick fix individual symbols
• Document-wide Conversion: Convert entire files at once
• Batch Operations: Process multiple files simultaneously

♿ Accessibility

🌟 Universal Design Principles

PHICODE is designed with accessibility at its core:

🔍 Screen Reader Support

• Semantic Markup: Proper HTML structure in documentation
• Alternative Text: Descriptive labels for all visual elements
• Keyboard Navigation: Full functionality without mouse interaction
• Voice Commands: Compatible with voice recognition software

🎨 Visual Accessibility

• High Contrast Support: Adapts to system contrast preferences
• Customizable Fonts: Support for dyslexia-friendly typefaces
• Zoom Compatibility: Scales properly with browser/editor zoom
• Color Independence: Information conveyed beyond color alone

⌨️ Keyboard Navigation

🧠 Cognitive Accessibility

• Clear Language: Jargon-free documentation with definitions
• Consistent Terminology: Same terms used throughout interface
• Progressive Disclosure: Information revealed gradually
• Error Prevention: Validation and confirmation for destructive actions
• Memory Aids: Visual cues and breadcrumb navigation

📋 Accessibility Compliance

✅ WCAG 2.1 AA Compliant

• Perceivable: Content available to assistive technologies
• Operable: Interface usable with various input methods
• Understandable: Information and UI operation is clear
• Robust: Compatible with current and future assistive technologies

Testing & Validation

• Automated Testing: Continuous accessibility scanning
• Manual Testing: Regular testing with assistive technologies
• User Feedback: Community input from accessibility advocates
• Expert Review: Professional accessibility audit compliance

🤝 Accessibility Commitment: I strive to continuously improve accessibility. Report barriers via our accessibility feedback form.

🤝 Contributing

🌟 Ways to Contribute

Contributions welcome from developers of all experience levels:

🔧 Code Contributions

• Bug Fixes: Resolve issues and improve stability
• Feature Development: Implement new PHICODE capabilities
• Performance Optimization: Enhance extension speed and efficiency
• Testing: Expand test coverage and quality assurance

📚 Documentation

• Tutorial Content: Create learning materials and examples
• Translation: Localize documentation for global accessibility
• Video Guides: Develop multimedia learning resources
• Best Practices: Document coding standards and patterns

🎨 Design & UX

• Icon Design: Create beautiful, accessible iconography
• Theme Development: Design color schemes and visual styles
• User Experience: Improve interface design and workflows
• Accessibility: Enhance universal design features

🚀 Development Setup

Prerequisites

# Required tools
node --version    # ≥ 16.0.0
npm --version     # ≥ 8.0.0
code --version    # ≥ 1.74.0
git --version     # ≥ 2.25.0

Getting Started

# 1️⃣ Clone repository
git clone https://github.com/Varietyz/phi-vscode-extensions/tree/main/phicode-extension.git
cd phi-vscode-extensions

# 2️⃣ Install dependencies
npm install

# 3️⃣ Build extension
npm run compile

# 4️⃣ Launch development environment
code .
# Press F5 to start debugging session

Development Workflow

# 🔄 Watch mode for development
npm run watch

# 🧪 Run tests
npm test

# 📦 Package extension
npm run build

📋 Contribution Guidelines

Pull Request Process

1. Fork the repository and create a feature branch
2. Implement changes with comprehensive tests
3. Document new features and update existing documentation
4. Test across multiple platforms and VS Code versions
5. Submit pull request with detailed description

Code Standards

• TypeScript: Strict type checking enabled
• ESLint: Follow configured linting rules
• Prettier: Consistent code formatting
• Tests: Minimum 80% code coverage for new features

Commit Convention

# Format: type(scope): description
feat(completion): add fuzzy matching for symbol completion
fix(linter): resolve async context validation bug
docs(readme): update installation instructions
test(formatter): add edge case coverage

🏷️ Issue Templates

• 🐛 Bug Report: Systematic bug documentation
• ✨ Feature Request: New capability proposals
• ♿ Accessibility Issue: Barrier identification and resolution
• 📚 Documentation: Improvements and corrections
• ❓ Question: Community support and guidance

🎖️ Recognition

Contributors are recognized in:

• README Contributors Section: Public acknowledgment
• Release Notes: Feature attribution in changelogs
• Hall of Fame: Special recognition for significant contributions
• Swag Program: Exclusive PHICODE merchandise for active contributors

❓ Support & FAQ

🆘 Getting Help

Community Support

• 📋 GitHub Discussions: Community forum
• 💬 Discord Server: Real-time chat support
• 📧 Email Support: jay@banes-lab.com
• 📖 Documentation: Comprehensive guides

Estimated Response Times

• Critical Bugs: Within 24 hours
• General Issues: Within 72 hours
• Feature Requests: Within 1 week
• Documentation: Within 48 hours

❓ Frequently Asked Questions

# Individual file conversion
Right-click .py file → "Convert to PHICODE (.ɸ)"

# Batch conversion
Select multiple .py files → Right-click → "Convert to PHICODE"

{
  // Font settings for better symbol rendering
  "[phicode]": {
    "editor.fontFamily": "'Fira Code', 'JetBrains Mono', monospace",
    "editor.fontSize": 14,
    "editor.fontLigatures": true
  },
  
  // Color theme customization
  "workbench.colorCustomizations": {
    "editor.tokenColorCustomizations": {
      "[theme-name]": {
        "functions": "#ff6b6b",
        "keywords": "#4ecdc4"
      }
    }
  }
}

🚨 Troubleshooting

Common Issues & Solutions

Debug Information Collection

# Generate debug report
Ctrl+Shift+P → "PHICODE: Generate Debug Report"

# Check extension logs
Ctrl+Shift+P → "Developer: Reload Window With Extensions Disabled"

Reset to Defaults

# Reset all PHICODE settings
Ctrl+Shift+P → "Preferences: Open Settings (JSON)"
# Remove all "phicode.*" entries

📊 Performance

📊 Performance Metrics

🔧 Runtime Optimization Features

PHICODE Runtime Engine Performance

• Thread-safe LRU Cache: In-memory caching with disk persistence (default 512 entries)
• PYC Integration: Bytecode caching with hash-based validation for instant re-execution
• Smart Module Loading: Filesystem change detection reduces repeated file system access
• Import Optimization: Efficient .φ file resolution and loading

VS Code Extension Optimization

• Debounced Operations: 500ms debounce for linting prevents excessive CPU usage
• Lazy Loading: Features loaded on-demand for faster startup
• Resource Pooling: Efficient reuse of processing resources
• Memory Management: Automatic cleanup of unused symbol caches

📄 License & Legal

📜 License Information

This project is licensed under the MIT License - see the LICENSE file for details.

Key Points:

• ✅ Commercial Use: Use PHICODE in commercial projects
• ✅ Modification: Adapt and customize for your needs
• ✅ Distribution: Share and distribute freely
• ✅ Private Use: No restrictions on private usage
• ⚠️ No Warranty: Software provided "as-is"

🔒 Privacy & Data Protection

Data Collection

• No Code Collection: Your source code never leaves your machine

GDPR Compliance

• Data Minimization: Only necessary data collected
• Right to Deletion: Request data removal anytime
• Transparency: Clear documentation of all data practices
• Consent Management: Explicit opt-in for analytics

Security Measures

• Local Processing: All conversion happens locally
• No Cloud Dependencies: Core functionality works offline
• Secure Communications: Encrypted connections for updates
• Regular Security Audits: Continuous security assessment

🏛️ Third-party Licenses

📞 Contact & Community

💬 Official Channels

• 🐙 GitHub: VS Code Extension | Runtime Engine
• 📦 PyPI: PHICODE Runtime - pip install phicode
• 🛒 Marketplace: VS Code Extension
• 💬 Discord: https://discord.gg/phicode

👥 Core Development Team

• Jay Baleine - Creator (jay@banes-lab.com)
  • @varietyz

📧 Support Contacts

• General Support: jay@banes-lab.com
• Runtime Issues: jay@banes-lab.com
• VS Code Extension: Use GitHub Issues on the extension repository
• Business Inquiries: jay@banes-lab.com

📊 Project Statistics

Security:

🎯 Ready to transform your Python development?

⬇️ Install Extension • 🐍 Install Runtime • 📖 Read Docs • 🤝 Join Community

Complete PHICODE Ecosystem:

pip install phicode                    # Runtime engine
code --install-extension Banes-Lab.phicode  # VS Code tools

---

PHICODE brings mathematical language to executable code.

---

Made with ❤️ by Jay Baleine - Banes Lab

© 2025 Banes Lab • MIT License • Runtime • Extension