1. LFE MACHINE MANUAL
  2. Title Page
  3. Copyright
  4. About the Cover
  7. Dedication
  8. Preface
  9. Forward
  10. Acknowledgments
  13. Part I - Getting Started
    ❱
    1. Introduction
    2. About LFE
    3. Prerequisites
    4. Conventions
    5. Development Setup
    6. 'Hello, World!'
      ❱
      1. Classic, REPL
      2. Classic, main
      3. LFE/OTP
    8. Walk-through: An LFE Guessing Game
      ❱
      1. Planning the Game
      2. Code Explore
        ❱
        1. Getting User Input
        2. Checking the Input
      4. Integrating into an Application
        ❱
        1. handle_cast
        2. Game API
        3. Finishing Touches
        4. Playing the Game
      6. Review
    10. The LFE REPL
      ❱
      1. Core Features
      2. Starting LFE
      3. readline Support
      4. (help)
        ❱
        1. REPL Functions
        2. REPL Commands
        3. Special Variables
      6. Command Interface
      7. Job Control
      8. Files
        ❱
        1. Evaluation
        2. Compilation
        3. Inclusion
        4. Loading
  15. Part II - Code as Data
    ❱
    1. Variables
      ❱
      1. Bindings
      2. Pattern-matching Preview
      3. Globals Revisted
    3. Primitive Types
      ❱
      1. Integers
      2. Floats
      3. Atoms (Symbols)
      4. Booleans
      5. Characters
    5. Cons Cells
      ❱
      1. Lisp Cons Cells
      2. Erlang Cons Cells
      3. LFE Cons Cells
    7. Lists and Strings
      ❱
      1. Lists
      2. Strings
    9. Bytes, Binaries, & Bytestrings
      ❱
      1. What Binaries Are
        ❱
        1. The Nature of the Beast
        2. Memory Representation
        3. Visual Representation
        4. The Binary/Bitstring Distinction
        5. Why Not Just Use Lists?
        6. Immutability
      3. Basic Binary Syntax
        ❱
        1. Constructing Simple Binaries
        2. Binary Strings
        3. Mixing Integers and Strings
        4. Nested Binaries
        5. Variables in Binary Construction
        6. Efficiency
        7. The List-to-Binary Bridge
        8. Summary
      5. Binary BIFs
        ❱
        1. list-to-binary: The Great Flattener
        2. binary-to-list: The Decomposer
        3. split-binary: The Precision Slicer
        4. term-to-binary: The Universal Serializer
        5. binary-to-term: The Reanimator
        6. byte-size: The Measurer
        7. bit-size: The Precise Measurer
        8. Summary
      7. Bit Syntax Fundamentals
        ❱
        1. The General Form
        2. Segments: The Atomic Unit
        3. Size Specifications
        4. Default Sizes
        5. Type Annotations
        6. Combining Size and Type
        7. Variables in Segments
        8. Philosophical Implications
      9. Type Specifiers
        ❱
        1. The Type Itself
        2. Sign
        3. Endianness
        4. The Unit Specifier
        5. Combining Specifiers
        6. Special Cases and Edge Conditions
        7. Summary
      11. Size and Unit Specifications
        ❱
        1. Default Sizes
        2. Explicit Size Specifications
        3. The Unit Specification
        4. The Constraint of Divisibility by Eight
        5. Practical Example: Fixed-Width Records
        6. The Pattern Matching Constraint
        7. A Note on UTF Strings
        8. Summary
      13. Endianness
        ❱
        1. The Parable of Big-Endian and Little-Endian
        2. The Endianness Specifiers in LFE
        3. When Endianness Matters
        4. The Native Option: Runtime Flexibility
        5. Pattern Matching with Endianness
        6. Cross-Platform Binary Protocols
        7. A Historical Note
        8. Practical Examples
        9. Summary
      15. Pattern Matching Binaries
        ❱
        1. The Fundamental Symmetry
        2. Basic Pattern Matching Examples
        3. The Rest of the Binary
        4. Don't Care Variables
        5. Pattern Matching in Function Clauses
        6. Bit-Level Pattern Matching
        7. The Dual Nature of Size Variables
        8. Complex Real-World Example: Decoding a TLV Structure
        9. Pattern Matching with Guards
        10. Common Pitfalls and How to Avoid Them
        11. Summary
      17. Binary Comprehensions
        ❱
        1. The Basic Syntax
        2. Binary to List: The Simplest Case
        3. List to Binary: The Reverse Journey
        4. Transforming Values
        5. Binary to Binary: The Power Move
        6. Bit-Level Manipulation
        7. Practical Example: RGB Color Manipulation
        8. Multiple Generators: The Cartesian Product
        9. Bit String Manipulation
        10. Complex Example: Run-Length Encoding
        11. Advanced Pattern: Sliding Window
        12. Performance Considerations
        13. Summary
      19. Bitstrings
        ❱
        1. What Bitstrings Are
        2. Creating Bitstrings
        3. Size Queries
        4. Pattern Matching Bitstrings
        5. Appending Bitstrings
        6. Practical Example: Morse Code
        7. Variable-Length Encoding Example
        8. The Alignment Problem
        9. Extracting Bits from Bytes
        10. Why Bitstrings Matter
        11. Performance Characteristics
        12. Summary
      21. Bitwise Operators
        ❱
        1. Bitwise AND
        2. Bitwise OR
        3. Bitwise XOR
        4. Bitwise NOT
        5. Bit Shift Left
        6. Bit Shift Right
        7. Practical Use: Extraction and Division
        8. Combining Operators: Real-World Example
        9. Performance Characteristics
        10. When to Use Bitwise Operators
        11. A Note on Negative Numbers
        12. Summary
      23. Serialization
        ❱
        1. The Basics
        2. Why Serialize
        3. A More Sophisticated Example: The Deep Space Signal
        4. The Secret Sauce: What Gets Preserved
        5. Practical Considerations: Size and Compression
        6. Storage Patterns: Files and Mnesia
        7. Versioning and Evolution: The Heat Death Problem
        8. The Distributed Angle: Cross-Node Communication
        9. Security Considerations: Trust No Binary
        10. Summary
      25. Real-World Applications
        ❱
        1. Example 1: Dissecting IPv4 Datagrams
        2. Example 2: Building a Custom Binary Protocol
        3. Example 3: Log File Format with Binary Efficiency
        4. Performance Considerations: The Need for Speed
        5. Debugging Binary Code: When Patterns Don't Match
        6. Summary
      27. Conclusion
    11. Tuples
    12. Property Lists
    13. Maps
    14. Arrays
    15. Dicts
    16. Graphs
    17. Queues
    18. Records
    19. Pattern Matching
    20. Generic Sequence Functions
  17. Part III - Data as Code
    ❱
    1. Expressions
    2. Functions
    3. Closures
    4. Evaluation
    5. Expressions
    6. Processes
    7. Messages and Their Passing
    8. Objects and Flavors
    9. I/O
    10. Accessing Files
    11. Modules
    12. Packages
    13. Scripting with LFE
    14. Creating LFE Projects
      ❱
      1. Using rebar3
      2. Project Layout Conventions
  19. Part IV - Advanced Topics
    ❱
    1. Errors and Debugging
    2. Writing Unit Tests
    3. The Common Test Framework
    4. The Propr Test Framework
    5. The Compiler
    6. Macros
    7. Distributed LFE
    8. Ports and Port Drivers
    9. Servers
    10. Clients
  21. Part V - OTP
    ❱
    1. Behaviours
    2. Applications
    3. Releases
    4. Tables and Databases
    5. Example OTP Project
  23. Part VI - Tooling
    ❱
    1. rebar3_lfe
      ❱
      1. Quick Start
        ❱
        1. Introduction
        2. Going Plaid
        3. Creating a New Project
        4. LFE Code
          ❱
          1. The REPL
          2. Sample Code
          3. Message-Passing
        6. Behind the Scenes
        7. Where Next?
      3. Plugin Reference
        ❱
        1. Introduction
          ❱
          1. Features
          2. Background
        3. Setup
          ❱
          1. Dependencies
          2. The Plugin
        5. Command Reference
          ❱
          1. Compiling
            ❱
            1. Package Support
          3. REPL
          4. Testing
            ❱
            1. eunit
            2. ltest
            3. ct
          6. Creating Projects
            ❱
            1. lib
            2. main
            3. escript
            4. app
            5. release
          8. Running Code
            ❱
            1. run
            2. run-escript
            3. run-release
          10. Cleanup
            ❱
            1. clean
            2. clean-build
            3. clean-cache
            4. clean-all
    3. rebar3 Internals
      ❱
      1. Diagrams
      2. Key Concepts
      3. Initialization & Configuration
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      5. Dependency Resolution & Locking
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      7. Dependency Acquisition
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      9. Application Discovery
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      11. Compilation Order Determination
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      13. Source File Compilation
        ❱
        1. Execution Flow
        2. Compiler Architecture
        3. Functions & API Calls
        4. State Modification
        5. Configuration
        6. File System Operations
        7. Error Conditions
        8. Edge Cases
        9. Cross References
        10. Example Scenarios
      15. Dependency Graph Management
        ❱
        1. Execution Flow
        2. DAG Structure
        3. Functions & API Calls
        4. State Modification
        5. Configuration
        6. File System Operations
        7. Error Conditions
        8. Edge Cases
        9. Cross References
        10. Example Scenarios
      17. Application File Generation
        ❱
        1. Execution Flow
        2. Functions & API Calls
        3. State Modification
        4. Configuration
        5. File System Operations
        6. Error Conditions
        7. Edge Cases
        8. Cross References
        9. Example Scenarios
      19. Hooks & Extensibility
        ❱
        1. Hook System
        2. Custom Compilers
        3. Plugins
        4. Configuration
        5. Cross References
      21. State Management
        ❱
        1. State Flow
        2. rebar_state Structure
        3. rebar_app_info Structure
        4. Functions & API Calls
        5. Cross References
      23. Paths & Directories
        ❱
        1. Directory Structure
        2. Path Resolution
        3. Code Paths
        4. Cross References
      25. Error Handling
        ❱
        1. Error Patterns
        2. Common Errors
        3. Recovery Strategies
        4. Cross References
      27. Configuration Reference
        ❱
        1. Compilation Options
        2. Directory Configuration
        3. Dependency Configuration
        4. Profile Configuration
        5. Hook Configuration
        6. Advanced Configuration
        7. Configuration Precedence
        8. Cross References
  25. Part VII - Guides
    ❱
    1. Style Guide
      ❱
      1. Introduction
      2. Formatting
        ❱
        1. File Headers
        2. Indentation
        3. Whitespace
        4. Line Length
        5. Spelling and Abbreviations
      4. Naming
        ❱
        1. Symbols
        2. Names in Modules
        3. Globals
        4. Predicates
        5. Intent
      6. Documentation
        ❱
        1. Docstrings
        2. Code Comments
        3. Attention Required
      8. Data Representation
        ❱
        1. Lists
        2. Tuples and Proplists
        3. Maps
        4. Records
      10. Errors
      11. Processes, Servers & Messages
        ❱
        1. Processes
        2. Servers
        3. Messages
      13. Software Components
        ❱
        1. Flow Control
        2. Functions
        3. Modules
        4. Libraries
        5. Projects
      15. Software Engineering
        ❱
        1. Principles
        2. Priorities
        3. Architecture
    3. Code of Conduct
    4. AI Resources for LFE
      ❱
      1. Consolidated Style Guide
      2. LFE Pocket Reference
      3. LFE function and macro inventory
      4. Erlang function inventory
  27. Part VIII - LFE for Contributors
    ❱
    1. LFE Architecture
      ❱
      1. What is LFE?
      2. High-Level Architecture
      3. Key Design Decisions
      4. Relationship to Erlang and Other Lisps
      5. Architectural Quality and Maturity
      6. Key Findings Summary
    3. Language Subsystems
      ❱
      1. Compilation Pipeline
        ❱
        1. Stage 1: Lexical Analysis (lfe_scan.erl)
        2. Stage 2: Syntactic Analysis (lfe_parse.erl)
        3. Stage 3: Macro Expansion (lfe_macro.erl)
        4. Stage 4: Semantic Analysis (lfe_lint.erl)
        5. Stage 5: Documentation Extraction (lfe_docs.erl)
        6. Stage 6: Code Generation (lfe_codegen.erl)
        7. Stage 7: AST Translation (lfe_translate.erl)
        8. Complete Transformation Example
      3. Runtime System
        ❱
        1. The Evaluator (lfe_eval.erl)
        2. Environment Management (lfe_env.erl)
        3. Shell/REPL Architecture (lfe_shell.erl)
      5. Macro System
        ❱
        1. Procedural Macros
        2. Pattern Macros (syntax-rules)
        3. Built-in Macros Catalog
        4. Macro Expansion Algorithm
        5. Record Macro Generation
        6. Match Specification DSL
    5. Module Reference
      ❱
      1. Compiler Modules
        ❱
        1. lfe_comp.erl - Compilation Orchestrator
        2. lfe_scan.erl - Lexical Scanner
        3. lfe_parse.erl - S-Expression Parser
        4. lfe_macro.erl - Macro Expansion Engine
        5. lfe_macro_export.erl - Export Macro Processor
        6. lfe_macro_include.erl - Include File Processor
        7. lfe_macro_record.erl - Record Macro Generator
        8. lfe_macro_struct.erl - Struct Macro Generator
        9. lfe_lint.erl - Semantic Analyzer
        10. lfe_translate.erl - Core Erlang Translator
        11. lfe_codegen.erl - Code Generator
        12. lfe_codelift.erl - Lambda Lifter
        13. lfe_abstract_code.erl - Debug Info Provider
      3. Runtime Modules
        ❱
        1. lfe_eval.erl - Expression Evaluator
        2. lfe_eval_bits.erl - Binary Evaluation
        3. lfe_init.erl - Runtime Initialization
        4. lfescript.erl - Script Runner
      5. I/O Modules
        ❱
        1. lfe_io.erl - I/O Interface
        2. lfe_io_write.erl - Compact Writer
        3. lfe_io_pretty.erl - Pretty Printer
        4. lfe_io_format.erl - Formatted Output
      7. Shell Modules
        ❱
        1. lfe_shell.erl - REPL Implementation
        2. lfe_edlin_expand.erl - Command Line Expansion
      9. Library Modules
        ❱
        1. cl.lfe - Common Lisp Compatibility
        2. clj.lfe - Clojure Compatibility
        3. scm.erl - Scheme Compatibility
        4. lfe_bits.erl - Bitstring Specification
        5. lfe_types.erl - Type System Support
        6. lfe_ms.erl - Match Specification DSL
        7. lfe_qlc.erl - Query List Comprehension
        8. lfe_gen.erl - Dynamic Code Generation
        9. lfe_struct.erl - Struct Runtime Support
      11. Support Utilities
        ❱
        1. lfe.erl - Public API Facade
        2. lfe_lib.erl - Utility Functions
        3. lfe_internal.erl - Type and Form Validation
        4. lfe_env.erl - Environment Management
        5. lfe_error.erl - Error Formatting
      13. Documentation Modules
        ❱
        1. lfe_docs.erl - Documentation Generation
        2. lfe_shell_docs.erl - Documentation Rendering
    7. Language Features Matrix
      ❱
      1. Core Special Forms
        ❱
        1. Data Construction
        2. Functions and Closures
        3. Control Flow
        4. Function Application
      3. Built-in Functions
        ❱
        1. List Operations
        2. Arithmetic and Comparison
        3. Boolean and Logical
        4. Type Predicates
        5. Tuple Operations
        6. Map Operations
        7. Binary Operations
        8. Process Operations
      5. Macros
        ❱
        1. Definition Macros
        2. Control Flow Macros
        3. Binding Macros
        4. List Comprehensions
        5. Function Shortcuts
        6. C-style Accessors
        7. Operator Aliases
      7. Pattern Matching
        ❱
        1. Pattern Types
        2. Pattern Examples
        3. Guards in Patterns
      9. Data Types
        ❱
        1. Primitive Types
        2. Compound Types
        3. Function Types
        4. Process Types
      11. Advanced Features
        ❱
        1. Metaprogramming
        2. Types and Specs
        3. Documentation
      13. Syntactic Sugar and Shorthands
    9. Erlang Integration
      ❱
      1. Module System Integration
      2. Calling Erlang from LFE
      3. Calling LFE from Erlang
      4. OTP Behaviors
      5. Process Model Integration
      6. Type System Integration
      7. Records and Structs
      8. Build System Integration
      9. Debug Info and Tool Integration
      10. Integration Patterns
      11. Performance Characteristics
      12. Integration Summary
    11. Compatibility Layers
      ❱
      1. Common Lisp Compatibility
      2. Clojure Compatibility
      3. Scheme Compatibility
      4. Compatibility Layer Comparison
      5. Design Patterns
      6. Performance Considerations
      7. Compatibility Summary
    13. Tooling
      ❱
      1. lfec - The Compiler
      2. lfe - The REPL
      3. lfescript - Script Runner
      4. Testing Tools
      5. Build Tool Integration
      6. Editor Support
      7. Debugging Tools
      8. Documentation Tools
      9. Profiling and Performance
      10. Tooling Summary
    15. Data Structure Catalog
      ❱
      1. Runtime Data Structures
      2. Compiler Data Structures
      3. Abstract Syntax Trees
      4. Environment Structures
      5. Documentation Structures
      6. Special Purpose Structures
      7. Memory Layout Considerations
      8. Data Structure Performance Summary
      9. Design Recommendations
      10. Cross-Reference with Source
      11. Key Takeaways
    17. Component Relationship Graphs
      ❱
      1. High-Level Architecture Layers
      2. Compiler Pipeline Dependencies
      3. Core Module Dependencies
      4. Module Categories by Coupling
      5. Compilation Order
      6. Core vs Periphery
      7. Dependency Metrics
      8. Refactoring Opportunities
      9. Architecture Quality Assessment
      10. Dependency Impact Analysis
      11. Dependency Visualization Summary
    19. Testing & Quality
      ❱
      1. Test Suite Organization
      2. Test Coverage Analysis
      3. Testing Strategies
      4. Test Execution
      5. Example Programs
      6. Quality Metrics
      7. Known Issues & Technical Debt
      8. Testing Best Practices
      9. Quality Assurance Process
      10. Testing Infrastructure Quality
      11. Comparison with Similar Projects
      12. Future Testing Enhancements
    21. Design Patterns & Idioms
      ❱
      1. Architectural Patterns
      2. Functional Programming Idioms
      3. Erlang-Specific Idioms
      4. Code Organization Patterns
      5. Performance Patterns
      6. Compiler Construction Patterns
      7. Testing Patterns
      8. Anti-Patterns to Avoid
      9. Pattern Summary
      10. Key Takeaways
    23. Performance Considerations
      ❱
      1. Compilation Performance
      2. Runtime Performance
      3. Memory Usage
      4. Performance Hotspots
      5. Optimization Opportunities
      6. Benchmarking
      7. Performance Best Practices
      8. Performance Comparison
      9. Future Performance Work
      10. Key Takeaways
    25. Future Directions
      ❱
      1. High Priority Enhancements
      2. Medium Priority Enhancements
      3. Low Priority / Opportunistic
      4. Ecosystem Enhancements
      5. Tooling Ecosystem
      6. Compatibility & Standards
      7. Implementation Priorities
      8. Community & Governance
      9. Risks & Mitigation
      10. Key Takeaways
    27. Resources
      ❱
      1. Glossary
      2. Complete Module Reference
      3. File Organization
      4. Key Data Structures Reference
      5. Common Patterns Quick Reference
      6. Build & Tooling Commands
      7. Performance Tuning Checklist
      8. Testing Checklist
      9. Code Review Checklist
      10. Analysis Methodology
      11. Additional Resources
  29. Part IX - Conclusion
  32. Feedback
  33. LFE Documentation
  36. Built with mdBook