Skip to content

Latest commit

 

History

History
468 lines (349 loc) · 13.1 KB

INDEX.md

File metadata and controls

468 lines (349 loc) · 13.1 KB

Gen Z Lang - Complete Documentation Index

Version: 0.1.0 Last Updated: December 2024

Purpose

This documentation suite provides everything an AI system needs to understand and build complex software in Gen Z Lang. Each document serves a specific purpose.

Documentation Structure

1. LANGUAGE_SPEC.md - Complete Language Specification

For: Understanding the language formally

Contents:

  • Lexical structure (tokens, keywords, operators)
  • Complete grammar in EBNF
  • Type system and semantics
  • Execution model
  • Standard library reference
  • Error handling specification
  • Best practices

Use this when:

  • Learning Gen Z Lang from scratch
  • Need formal grammar rules
  • Clarifying operator precedence
  • Understanding type system behavior
  • Looking up standard library functions
  • Writing language documentation

Key Sections:

  • §2: Lexical Structure (tokens, comments, literals)
  • §3: Syntax and Grammar (formal grammar)
  • §4: Type System (int, float, string, bool, function)
  • §5: Semantics (variables, control flow, functions)
  • §6: Standard Library (built-in functions)
  • §12: Complete Example Programs

2. ADVANCED_GUIDE.md - Advanced Programming Patterns

For: Building complex software systems

Contents:

  • Design patterns (Factory, Strategy, Observer, State, Builder, Decorator)
  • Data structures (Array, Stack, Queue, Linked List, Hash Table)
  • Algorithms (Sorting, Searching, Graph, Dynamic Programming, Greedy)
  • Application architectures (MVC, Event-Driven, Pipeline, Layered)
  • Complex examples (Calculator, Todo App, RPG Game)
  • Optimization techniques
  • Testing strategies
  • Debugging techniques

Use this when:

  • Implementing design patterns
  • Building data structures
  • Implementing algorithms
  • Designing application architecture
  • Need code examples for complex systems
  • Optimizing performance
  • Writing tests

Key Sections:

  • §1: Design Patterns (6 patterns with implementations)
  • §2: Data Structures (5 structures simulated with closures)
  • §3: Algorithms (Sorting, searching, graph, DP, greedy)
  • §4: Application Architectures (4 architecture patterns)
  • §5: Complex Software Examples (3 complete applications)
  • §6: Optimization Techniques
  • §7-8: Testing and Debugging

3. INTERNALS.md - Language Internals and Architecture

For: Extending or modifying Gen Z Lang

Contents:

  • Architecture overview (lexer → parser → interpreter)
  • Lexer implementation details
  • Parser implementation (recursive descent)
  • AST design and node hierarchy
  • Interpreter execution model
  • Environment and scoping mechanism
  • Error handling internals
  • Extension guides (adding keywords, operators, types, constructs)
  • Performance considerations
  • Future enhancement roadmap

Use this when:

  • Understanding how Gen Z Lang works internally
  • Adding new language features
  • Modifying the interpreter
  • Optimizing performance
  • Implementing new operators or keywords
  • Contributing to the language
  • Building tools (debugger, profiler, LSP)

Key Sections:

  • §1: Architecture Overview (compilation pipeline)
  • §2: Lexer Implementation (indentation tracking)
  • §3: Parser Implementation (recursive descent)
  • §4: AST Design (node hierarchy)
  • §5: Interpreter Implementation (tree-walking)
  • §6: Environment and Scoping (closures)
  • §8: Extending the Language (step-by-step guides)
  • §10: Future Enhancements (roadmap)

4. API_REFERENCE.md - Quick Reference Guide

For: Quick lookup while coding

Contents:

  • Quick syntax reference (cheat sheet)
  • Complete built-in function reference
  • Complete grammar (concise)
  • Operator precedence table
  • Common patterns (10+ patterns)
  • Error handling patterns
  • Data structure patterns
  • Algorithm templates
  • Testing patterns
  • Performance tips
  • Common gotchas
  • Complete keyword list

Use this when:

  • Need quick syntax reminder
  • Looking up built-in function signature
  • Checking operator precedence
  • Need code pattern template
  • Writing tests
  • Debugging common mistakes
  • Quick reference during development

Key Sections:

  • Quick Syntax Reference (one-page cheat sheet)
  • Built-in Functions Reference (complete API docs)
  • Common Patterns (10 copy-paste patterns)
  • Algorithm Templates (binary search, sort, etc.)
  • Common Gotchas (mistakes to avoid)
  • Complete Keyword List (alphabetical)

Quick Navigation Guide

"I want to..."

Learn Gen Z Lang

→ Start with LANGUAGE_SPEC.md §1-5 → Try examples in LANGUAGE_SPEC.md §12 → Reference API_REFERENCE.md while coding

Build a complex application

→ Read ADVANCED_GUIDE.md §4 (Application Architectures) → Look at ADVANCED_GUIDE.md §5 (Complex Software Examples) → Use patterns from ADVANCED_GUIDE.md §1 (Design Patterns)

Implement a specific algorithm

→ Check ADVANCED_GUIDE.md §3 (Algorithms) → Use templates from API_REFERENCE.md (Algorithm Templates)

Understand how Gen Z Lang works

→ Read INTERNALS.md §1 (Architecture Overview) → Study INTERNALS.md §2-5 (Implementation details)

Add a new language feature

→ Read INTERNALS.md §8 (Extending the Language) → Follow step-by-step guides for your feature type

Look up syntax quickly

→ Use API_REFERENCE.md (Quick Syntax Reference) → Check API_REFERENCE.md (Common Patterns)

Debug a problem

→ Check API_REFERENCE.md (Common Gotchas) → Use ADVANCED_GUIDE.md §8 (Debugging Techniques) → Look at error patterns in LANGUAGE_SPEC.md §8

Optimize performance

→ Read ADVANCED_GUIDE.md §6 (Optimization Techniques) → Check API_REFERENCE.md (Performance Tips) → Study INTERNALS.md §9 (Performance Considerations)

Write tests

→ Use ADVANCED_GUIDE.md §7 (Testing Strategies) → Copy patterns from API_REFERENCE.md (Testing Patterns)

Feature Coverage Matrix

Feature LANGUAGE_SPEC ADVANCED_GUIDE INTERNALS API_REFERENCE
Syntax ✓ Complete Example usage Grammar impl ✓ Quick ref
Semantics ✓ Detailed Advanced usage Execution model Patterns
Built-ins ✓ Reference Usage examples Extension guide ✓ API docs
Patterns Basic only ✓ Complete - ✓ Templates
Architecture Execution model ✓ App patterns ✓ Implementation -
Extensions - - ✓ Step-by-step -
Examples ✓ Complete programs ✓ Complex apps Code snippets ✓ Snippets
Algorithms Basic only ✓ Detailed - ✓ Templates
Performance - ✓ Optimization ✓ Internals ✓ Tips
Testing - ✓ Strategies - ✓ Patterns

Document Priorities by Use Case

For AI Building Complex Software

Priority 1 (Must Read):

  1. LANGUAGE_SPEC.md §1-6 - Core language understanding
  2. API_REFERENCE.md - Quick reference for syntax
  3. ADVANCED_GUIDE.md §1-4 - Patterns and architectures

Priority 2 (Should Read): 4. ADVANCED_GUIDE.md §5 - Complex example applications 5. LANGUAGE_SPEC.md §12 - Complete example programs 6. API_REFERENCE.md - Common patterns and templates

Priority 3 (Nice to Have): 7. ADVANCED_GUIDE.md §6-8 - Optimization, testing, debugging 8. INTERNALS.md §1-5 - Understanding internals

For AI Extending Gen Z Lang

Priority 1 (Must Read):

  1. INTERNALS.md §1-7 - Complete architecture and implementation
  2. INTERNALS.md §8 - Extension guides
  3. LANGUAGE_SPEC.md §2-3 - Grammar and syntax

Priority 2 (Should Read): 4. INTERNALS.md §9-10 - Performance and future enhancements 5. LANGUAGE_SPEC.md §4-5 - Type system and semantics

Priority 3 (Nice to Have): 6. ADVANCED_GUIDE.md - Understanding complex usage patterns

For Quick Reference While Coding

Primary Document:

  • API_REFERENCE.md (entire document)

Backup References:

  • LANGUAGE_SPEC.md §6 (Standard Library)
  • LANGUAGE_SPEC.md Appendix A-B (Keyword reference)

Code Examples Index

Simple Examples

Hello World:

  • LANGUAGE_SPEC.md §12.1
  • API_REFERENCE.md (Quick Syntax)

Calculator:

  • LANGUAGE_SPEC.md §12.1
  • ADVANCED_GUIDE.md §5.1 (Advanced version)

FizzBuzz:

  • LANGUAGE_SPEC.md §12.1
  • Examples directory: examples/fizzbuzz.genz

Functions:

  • LANGUAGE_SPEC.md §12.1
  • Examples directory: examples/functions.genz

Complex Examples

MVC Application:

  • ADVANCED_GUIDE.md §4.1

Event-Driven System:

  • ADVANCED_GUIDE.md §4.2

Data Processing Pipeline:

  • ADVANCED_GUIDE.md §4.3

Three-Tier Architecture:

  • ADVANCED_GUIDE.md §4.4

Calculator with History:

  • ADVANCED_GUIDE.md §5.1

Todo List Application:

  • ADVANCED_GUIDE.md §5.2

RPG Game:

  • ADVANCED_GUIDE.md §5.3

Design Pattern Examples

Factory Pattern:

  • ADVANCED_GUIDE.md §1.1

Strategy Pattern:

  • ADVANCED_GUIDE.md §1.2

Observer Pattern:

  • ADVANCED_GUIDE.md §1.3

State Pattern:

  • ADVANCED_GUIDE.md §1.4

Builder Pattern:

  • ADVANCED_GUIDE.md §1.5

Decorator Pattern:

  • ADVANCED_GUIDE.md §1.6

Data Structure Examples

Array/List:

  • ADVANCED_GUIDE.md §2.1

Stack:

  • ADVANCED_GUIDE.md §2.2

Queue:

  • ADVANCED_GUIDE.md §2.3

Linked List:

  • ADVANCED_GUIDE.md §2.4

Hash Table:

  • ADVANCED_GUIDE.md §2.5

Algorithm Examples

Sorting:

  • ADVANCED_GUIDE.md §3.1 (Bubble, Quick, Merge)
  • API_REFERENCE.md (Bubble Sort template)

Searching:

  • ADVANCED_GUIDE.md §3.2 (Linear, Binary)
  • API_REFERENCE.md (Binary Search template)

Graph Algorithms:

  • ADVANCED_GUIDE.md §3.3 (DFS, BFS)

Dynamic Programming:

  • ADVANCED_GUIDE.md §3.4 (Fibonacci, LCS)

Greedy Algorithms:

  • ADVANCED_GUIDE.md §3.5

Terminology Reference

Gen Z Lang Terms → Standard Programming Terms

Gen Z Lang Standard Term Document
rizz Variable declaration LANGUAGE_SPEC §2.4
yeet Print/output LANGUAGE_SPEC §2.4
fr fr Emphasized output LANGUAGE_SPEC §2.4
vibe check Input LANGUAGE_SPEC §2.4
vibe? If statement LANGUAGE_SPEC §2.4
no vibe? Else if LANGUAGE_SPEC §2.4
dead Else LANGUAGE_SPEC §2.4
keep slaying while While loop LANGUAGE_SPEC §2.4
grind from For loop LANGUAGE_SPEC §2.4
main character Function definition LANGUAGE_SPEC §2.4
send it Return LANGUAGE_SPEC §2.4
no cap Equals (==) LANGUAGE_SPEC §2.4
cap Not equals (!=) LANGUAGE_SPEC §2.4
lowkey Less than prefix LANGUAGE_SPEC §2.4
highkey Greater than prefix LANGUAGE_SPEC §2.4
bussin True LANGUAGE_SPEC §2.4
mid False LANGUAGE_SPEC §2.4
dip Break LANGUAGE_SPEC §2.4
skip it Continue LANGUAGE_SPEC §2.4
nah NOT LANGUAGE_SPEC §2.4
ngl Comment LANGUAGE_SPEC §2.3
glow_up Convert to int LANGUAGE_SPEC §6.1
vibe_shift Convert to string LANGUAGE_SPEC §6.1
energy Convert to float LANGUAGE_SPEC §6.1

Version History

v0.1.0 (Current)

  • Initial release
  • Complete language specification
  • Advanced programming guide
  • Internals documentation
  • API reference
  • All core features implemented

Getting Started Checklist

For an AI system beginning with Gen Z Lang:

  • Read LANGUAGE_SPEC.md §1 (Introduction)
  • Read LANGUAGE_SPEC.md §2 (Lexical Structure)
  • Read LANGUAGE_SPEC.md §3 (Syntax and Grammar)
  • Review API_REFERENCE.md (Quick Syntax Reference)
  • Try examples from LANGUAGE_SPEC.md §12
  • Read LANGUAGE_SPEC.md §4-5 (Type System and Semantics)
  • Browse ADVANCED_GUIDE.md §1 (Design Patterns)
  • Read LANGUAGE_SPEC.md §6 (Standard Library)
  • Keep API_REFERENCE.md open for quick reference

Estimated Reading Time:

  • Quick Start (above checklist): 2-3 hours
  • Complete Documentation: 6-8 hours
  • Mastery with practice: 15-20 hours

Support and Resources

Example Code

  • examples/ directory in repository
  • LANGUAGE_SPEC.md §12 (complete programs)
  • ADVANCED_GUIDE.md §5 (complex applications)

Language Tools

  • CLI: genz program.genz
  • Interpreter: genzlang/ Python package

Contributing

See INTERNALS.md §8 for extension guidelines

Document Maintenance

This documentation is maintained alongside the Gen Z Lang implementation. When the language changes:

  1. LANGUAGE_SPEC.md updated first (authoritative)
  2. INTERNALS.md updated for implementation changes
  3. ADVANCED_GUIDE.md updated for new patterns
  4. API_REFERENCE.md updated last (quick reference)

Summary

Gen Z Lang provides complete documentation across four documents:

  1. LANGUAGE_SPEC.md - The formal specification (authoritative)
  2. ADVANCED_GUIDE.md - Patterns and complex examples (practical)
  3. INTERNALS.md - Implementation and extensions (technical)
  4. API_REFERENCE.md - Quick reference (cheat sheet)

For most AI systems building software: Start with LANGUAGE_SPEC.md, reference API_REFERENCE.md while coding, and consult ADVANCED_GUIDE.md for complex patterns.

No cap, these docs are bussin! 🔥