light_log

3 hari lalu

Light Log - A Defensive Programming Library for Pine Script

Overview

The Light Log library transforms Pine Script development by introducing structured logging and defensive programming patterns typically found in enterprise languages like C#. This library addresses a fundamental challenge in Pine Script: the lack of sophisticated error handling and debugging tools that developers expect when building complex trading systems.

At its core, Light Log provides three transformative capabilities that work together to create more reliable and maintainable code. First, it wraps all native Pine Script types in error-aware containers, allowing values to carry validation state alongside their data. Second, it offers a comprehensive logging system with severity levels and conditional rendering. Third, it includes defensive programming utilities that catch errors early and make code self-documenting.


The Philosophy of Errors as Values

Traditional Pine Script error handling relies on runtime errors that halt execution, making it difficult to build resilient systems that can gracefully handle edge cases. Light Log introduces a paradigm shift by treating errors as first-class values that flow through your program alongside regular data.

When you wrap a value using Light Log's type system, you're not just storing data – you're creating a container that can carry both the value and its validation state. For example, when you call myNumber.INT(), you receive an INT object that contains both the integer value and a Log object that can describe any issues with that value. This approach, inspired by functional programming languages, allows errors to propagate through calculations without causing immediate failures.

Consider how this changes error handling in practice. Instead of a calculation failing catastrophically when it encounters invalid input, it can produce a result object that contains both the computed value (which might be na) and a detailed log explaining what went wrong. Subsequent operations can check has_error() to decide whether to proceed or handle the error condition gracefully.


The Typed Wrapper System

Light Log provides typed wrappers for every native Pine Script type: INT, FLOAT, BOOL, STRING, COLOR, LINE, LABEL, BOX, TABLE, CHART_POINT, POLYLINE, and LINEFILL. These wrappers serve multiple purposes beyond simple value storage.

Each wrapper type contains two fields: the value field v holds the actual data, while the error field e contains a Log object that tracks the value's validation state. This dual nature enables powerful programming patterns. You can perform operations on wrapped values and accumulate error information along the way, creating an audit trail of how values were processed.

The wrapper system includes convenient methods for converting between wrapped and unwrapped values. The extension methods like INT(), FLOAT(), etc., make it easy to wrap existing values, while the from_INT(), from_FLOAT() methods extract the underlying values when needed. The has_error() method provides a consistent interface for checking whether any wrapped value has encountered issues during processing.


The Log Object: Your Debugging Companion

The Log object represents the heart of Light Log's debugging capabilities. Unlike simple string concatenation for error messages, the Log object provides a structured approach to building, modifying, and rendering diagnostic information.

Each Log object carries three essential pieces of information: an error type (info, warning, error, or runtime_error), a message string that can be built incrementally, and an active flag that controls conditional rendering. This structure enables sophisticated logging patterns where you can build up detailed diagnostic information throughout your script's execution and decide later whether and how to display it.

The Log object's methods support fluent chaining, allowing you to build complex messages in a readable way. The write() and write_line() methods append text to the log, while new_line() adds formatting. The clear() method resets the log for reuse, and the rendering methods (render_now(), render_condition(), and the general render()) control when and how messages appear.


Defensive Programming Made Easy

Light Log's argument validation functions transform how you write defensive code. Instead of cluttering your functions with verbose validation logic, you can use concise, self-documenting calls that make your intentions clear.

The argument_error() function provides strict validation that halts execution when conditions aren't met – perfect for catching programming errors early. For less critical issues, argument_log_warning() and argument_log_error() record problems without stopping execution, while argument_log_info() provides debug visibility into your function's behavior.

These functions follow a consistent pattern: they take a condition to check, the function name, the argument name, and a descriptive message. This consistency makes error messages predictable and helpful, automatically formatting them to show exactly where problems occurred.


Building Modular, Reusable Code

Light Log encourages a modular approach to Pine Script development by providing tools that make functions more self-contained and reliable. When functions validate their inputs and return wrapped values with error information, they become true black boxes that can be safely composed into larger systems.

The void_return() function addresses Pine Script's requirement that all code paths return a value, even in error handling branches. This utility function provides a clean way to satisfy the compiler while making it clear that a particular code path should never execute.

The static log pattern, initialized with init_static_log(), enables module-wide error tracking. You can create a persistent Log object that accumulates information across multiple function calls, building a comprehensive diagnostic report that helps you understand complex behaviors in your indicators and strategies.


Real-World Applications

In practice, Light Log shines when building sophisticated trading systems. Imagine developing a complex indicator that processes multiple data streams, performs statistical calculations, and generates trading signals. With Light Log, each processing stage can validate its inputs, perform calculations, and pass along both results and diagnostic information.

For example, a moving average calculation might check that the period is positive, that sufficient data exists, and that the input series contains valid values. Instead of failing silently or throwing runtime errors, it can return a FLOAT object that contains either the calculated average or a detailed explanation of why the calculation couldn't be performed.

Strategy developers benefit even more from Light Log's capabilities. Complex entry and exit logic often involves multiple conditions that must all be satisfied. With Light Log, each condition check can contribute to a comprehensive log that explains exactly why a trade was or wasn't taken, making strategy debugging and optimization much more straightforward.


Performance Considerations

While Light Log adds a layer of abstraction over raw Pine Script values, its design minimizes performance impact. The wrapper objects are lightweight, containing only two fields. The logging operations only consume resources when actually rendered, and the conditional rendering system ensures that production code can run with logging disabled for maximum performance.

The library follows Pine Script best practices for performance, using appropriate data structures and avoiding unnecessary operations. The var keyword in init_static_log() ensures that persistent logs don't create new objects on every bar, maintaining efficiency even in real-time calculations.


Getting Started

Adopting Light Log in your Pine Script projects is straightforward. Import the library, wrap your critical values, add validation to your functions, and use Log objects to track important events. Start small by adding logging to a single function, then expand as you see the benefits of better error visibility and code organization.

Remember that Light Log is designed to grow with your needs. You can use as much or as little of its functionality as makes sense for your project. Even simple uses, like adding argument validation to key functions, can significantly improve code reliability and debugging ease.

Transform your Pine Script development experience with Light Log – because professional trading systems deserve professional development tools.



Light Log Technical Deep Dive: Advanced Patterns and Architecture


Understanding Errors as Values

The concept of "errors as values" represents a fundamental shift in how we think about error handling in Pine Script. In traditional Pine Script development, errors are events – they happen at a specific moment in time and immediately interrupt program flow. Light Log transforms errors into data – they become information that flows through your program just like any other value.

This transformation has profound implications. When errors are values, they can be stored, passed between functions, accumulated, transformed, and inspected. They become part of your program's data flow rather than exceptions to it. This approach, popularized by languages like Rust with its Result type and Haskell with its Either monad, brings functional programming's elegance to Pine Script.

Consider a practical example. Traditional Pine Script might calculate a momentum indicator like this:

momentum = close - close[period]

If period is invalid or if there isn't enough historical data, this calculation might produce na or cause subtle bugs. With Light Log's approach:

calculate_momentum(src, period)=>
    result = src.FLOAT()
    
    if period <= 0
        result.e.write("Invalid period: must be positive", true, ErrorType.error)
        result.v := na
    else if bar_index < period
        result.e.write("Insufficient data: need " + str.tostring(period) + " bars", true, ErrorType.warning)
        result.v := na
    else
        result.v := src - src[period]
        result.e.write("Momentum calculated successfully", false, ErrorType.info)
    
    result

Now the function returns not just a value but a complete computational result that includes diagnostic information. Calling code can make intelligent decisions based on both the value and its associated metadata.


The Monad Pattern in Pine Script

While Pine Script lacks the type system features to implement true monads, Light Log brings monadic thinking to Pine Script development. The wrapped types (INT, FLOAT, etc.) act as computational contexts that carry both values and metadata through a series of transformations.

The key insight of monadic programming is that you can chain operations while automatically propagating context. In Light Log, this context is the error state. When you have a FLOAT that contains an error, operations on that FLOAT can check the error state and decide whether to proceed or propagate the error.

This pattern enables what functional programmers call "railway-oriented programming" – your code follows a success track when all is well but can switch to an error track when problems occur. Both tracks lead to the same destination (a result with error information), but they take different paths based on the validity of intermediate values.


Composable Error Handling

Light Log's design encourages composition – building complex functionality from simpler, well-tested components. Each component can validate its inputs, perform its calculation, and return a result with appropriate error information. Higher-level functions can then combine these results intelligently.

Consider building a complex trading signal from multiple indicators:

generate_signal(src, fast_period, slow_period, signal_period) =>
    log = init_static_log(ErrorType.info)
    
    // Calculate components with error tracking
    fast_ma = calculate_ma(src, fast_period)
    slow_ma = calculate_ma(src, slow_period)
    
    // Check for errors in components
    if fast_ma.has_error()
        log.write_line("Fast MA error: " + fast_ma.e.message, true)
    if slow_ma.has_error()
        log.write_line("Slow MA error: " + slow_ma.e.message, true)
    
    // Proceed with calculation if no errors
    signal = 0.0.FLOAT()
    if not (fast_ma.has_error() or slow_ma.has_error())
        macd_line = fast_ma.v - slow_ma.v
        signal_line = calculate_ma(macd_line, signal_period)
        
        if signal_line.has_error()
            log.write_line("Signal line error: " + signal_line.e.message, true)
            signal.e := log
        else
            signal.v := macd_line - signal_line.v
            log.write("Signal generated successfully")
    else
        signal.e := log
        signal.v := na
    
    signal

This composable approach makes complex calculations more reliable and easier to debug. Each component is responsible for its own validation and error reporting, and the composite function orchestrates these components while maintaining comprehensive error tracking.


The Static Log Pattern

The init_static_log() function introduces a powerful pattern for maintaining state across function calls. In Pine Script, the var keyword creates variables that persist across bars but are initialized only once. Light Log leverages this to create logging objects that can accumulate information throughout a script's execution.

This pattern is particularly valuable for debugging complex strategies where you need to understand behavior across multiple bars. You can create module-level logs that track important events:

// Module-level diagnostic log
diagnostics = init_static_log(ErrorType.info)

// Track strategy decisions across bars
check_entry_conditions() =>
    diagnostics.clear()  // Start fresh each bar
    
    diagnostics.write_line("Bar " + str.tostring(bar_index) + " analysis:")
    
    if close > sma(close, 20)
        diagnostics.write_line("Price above SMA20", false)
    else
        diagnostics.write_line("Price below SMA20 - no entry", true, ErrorType.warning)
    
    if volume > sma(volume, 20) * 1.5
        diagnostics.write_line("Volume surge detected", false)
    else
        diagnostics.write_line("Normal volume", false)
    
    // Render diagnostics based on verbosity setting
    if debug_mode
        diagnostics.render_now()

Advanced Validation Patterns

Light Log's argument validation functions enable sophisticated precondition checking that goes beyond simple null checks. You can implement complex validation logic while keeping your code readable:

validate_price_data(open_val, high_val, low_val, close_val) =>
    argument_error(na(open_val) or na(high_val) or na(low_val) or na(close_val), 
                   "validate_price_data", "OHLC values", "contain na values")
    
    argument_error(high_val < low_val, 
                   "validate_price_data", "high/low", "high is less than low")
    
    argument_error(close_val > high_val or close_val < low_val,
                   "validate_price_data", "close", "is outside high/low range")
    
    argument_log_warning(high_val == low_val,
                        "validate_price_data", "high/low", "are equal (no range)")

This validation function documents its requirements clearly and fails fast with helpful error messages when assumptions are violated. The mix of errors (which halt execution) and warnings (which allow continuation) provides fine-grained control over how strict your validation should be.


Performance Optimization Strategies

While Light Log adds abstraction, careful design minimizes overhead. Understanding Pine Script's execution model helps you use Light Log efficiently.

Pine Script executes once per bar, so operations that seem expensive in traditional programming might have negligible impact. However, when building real-time systems, every optimization matters. Light Log provides several patterns for efficient use:

Lazy Evaluation: Log messages are only built when they'll be rendered. Use conditional logging to avoid string concatenation in production:

if debug_mode
    log.write_line("Calculated value: " + str.tostring(complex_calculation))

Selective Wrapping: Not every value needs error tracking. Wrap values at API boundaries and critical calculation points, but use raw values for simple operations:

// Wrap at boundaries
input_price = close.FLOAT()
validated_period = validate_period(input_period).INT()

// Use raw values internally
sum = 0.0
for i = 0 to validated_period.v - 1
    sum += close

Error Propagation: When errors occur early, avoid expensive calculations:

process_data(input) =>
    validated = validate_input(input)
    if validated.has_error()
        validated  // Return early with error
    else
        // Expensive processing only if valid
        perform_complex_calculation(validated)

Integration Patterns

Light Log integrates smoothly with existing Pine Script code. You can adopt it incrementally, starting with critical functions and expanding coverage as needed.

Boundary Validation: Add Light Log at the boundaries of your system – where user input enters and where final outputs are produced. This catches most errors while minimizing changes to existing code.

Progressive Enhancement: Start by adding argument validation to existing functions. Then wrap return values. Finally, add comprehensive logging. Each step improves reliability without requiring a complete rewrite.

Testing and Debugging: Use Light Log's conditional rendering to create debug modes for your scripts. Production users see clean output while developers get detailed diagnostics:

// User input for debug mode
debug = input.bool(false, "Enable debug logging")

// Conditional diagnostic output
if debug
    diagnostics.render_now()
else
    diagnostics.render_condition()  // Only shows errors/warnings

Future-Proofing Your Code

Light Log's patterns prepare your code for Pine Script's evolution. As Pine Script adds more sophisticated features, code that uses structured error handling and defensive programming will adapt more easily than code that relies on implicit assumptions.

The type wrapper system, in particular, positions your code to take advantage of potential future features or more sophisticated type inference. By thinking in terms of wrapped values and error propagation today, you're building code that will remain maintainable and extensible tomorrow.

Light Log doesn't just make your Pine Script better today – it prepares it for the trading systems you'll need to build tomorrow.



Library "light_log"
A lightweight logging and defensive programming library for Pine Script.
Designed for modular and extensible scripts, this utility provides structured runtime validation,
conditional logging, and reusable `Log` objects for centralized error propagation.
It also introduces a typed wrapping system for all native Pine values (e.g., `INT`, `FLOAT`, `LABEL`),
allowing values to carry errors alongside data. This enables functional-style flows with built-in
validation tracking, error detection (`has_error()`), and fluent chaining.
Inspired by structured logging patterns found in systems like C#, it reduces boilerplate,
enforces argument safety, and encourages clean, maintainable code architecture.

method INT(self, error_type)
  Wraps an `int` value into an `INT` struct with an optional log severity.
  Namespace types: series int, simple int, input int, const int
  Parameters:
    self (int): The raw `int` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: An `INT` object containing the value and a default Log instance.

method FLOAT(self, error_type)
  Wraps a `float` value into a `FLOAT` struct with an optional log severity.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): The raw `float` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `FLOAT` object containing the value and a default Log instance.

method BOOL(self, error_type)
  Wraps a `bool` value into a `BOOL` struct with an optional log severity.
  Namespace types: series bool, simple bool, input bool, const bool
  Parameters:
    self (bool): The raw `bool` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `BOOL` object containing the value and a default Log instance.

method STRING(self, error_type)
  Wraps a `string` value into a `STRING` struct with an optional log severity.
  Namespace types: series string, simple string, input string, const string
  Parameters:
    self (string): The raw `string` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `STRING` object containing the value and a default Log instance.

method COLOR(self, error_type)
  Wraps a `color` value into a `COLOR` struct with an optional log severity.
  Namespace types: series color, simple color, input color, const color
  Parameters:
    self (color): The raw `color` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `COLOR` object containing the value and a default Log instance.

method LINE(self, error_type)
  Wraps a `line` object into a `LINE` struct with an optional log severity.
  Namespace types: series line
  Parameters:
    self (line): The raw `line` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `LINE` object containing the value and a default Log instance.

method LABEL(self, error_type)
  Wraps a `label` object into a `LABEL` struct with an optional log severity.
  Namespace types: series label
  Parameters:
    self (label): The raw `label` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `LABEL` object containing the value and a default Log instance.

method BOX(self, error_type)
  Wraps a `box` object into a `BOX` struct with an optional log severity.
  Namespace types: series box
  Parameters:
    self (box): The raw `box` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `BOX` object containing the value and a default Log instance.

method TABLE(self, error_type)
  Wraps a `table` object into a `TABLE` struct with an optional log severity.
  Namespace types: series table
  Parameters:
    self (table): The raw `table` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `TABLE` object containing the value and a default Log instance.

method CHART_POINT(self, error_type)
  Wraps a `chart.point` value into a `CHART_POINT` struct with an optional log severity.
  Namespace types: chart.point
  Parameters:
    self (chart.point): The raw `chart.point` value to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `CHART_POINT` object containing the value and a default Log instance.

method POLYLINE(self, error_type)
  Wraps a `polyline` object into a `POLYLINE` struct with an optional log severity.
  Namespace types: series polyline, series polyline, series polyline, series polyline
  Parameters:
    self (polyline): The raw `polyline` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `POLYLINE` object containing the value and a default Log instance.

method LINEFILL(self, error_type)
  Wraps a `linefill` object into a `LINEFILL` struct with an optional log severity.
  Namespace types: series linefill
  Parameters:
    self (linefill): The raw `linefill` object to wrap.
    error_type (series ErrorType): Optional severity level to associate with the log. Default is `ErrorType.error`.
  Returns: A `LINEFILL` object containing the value and a default Log instance.

method from_INT(self)
  Extracts the integer value from an INT wrapper.
  Namespace types: INT
  Parameters:
    self (INT): The wrapped INT instance.
  Returns: The underlying `int` value.

method from_FLOAT(self)
  Extracts the float value from a FLOAT wrapper.
  Namespace types: FLOAT
  Parameters:
    self (FLOAT): The wrapped FLOAT instance.
  Returns: The underlying `float` value.

method from_BOOL(self)
  Extracts the boolean value from a BOOL wrapper.
  Namespace types: BOOL
  Parameters:
    self (BOOL): The wrapped BOOL instance.
  Returns: The underlying `bool` value.

method from_STRING(self)
  Extracts the string value from a STRING wrapper.
  Namespace types: STRING
  Parameters:
    self (STRING): The wrapped STRING instance.
  Returns: The underlying `string` value.

method from_COLOR(self)
  Extracts the color value from a COLOR wrapper.
  Namespace types: COLOR
  Parameters:
    self (COLOR): The wrapped COLOR instance.
  Returns: The underlying `color` value.

method from_LINE(self)
  Extracts the line object from a LINE wrapper.
  Namespace types: LINE
  Parameters:
    self (LINE): The wrapped LINE instance.
  Returns: The underlying `line` object.

method from_LABEL(self)
  Extracts the label object from a LABEL wrapper.
  Namespace types: LABEL
  Parameters:
    self (LABEL): The wrapped LABEL instance.
  Returns: The underlying `label` object.

method from_BOX(self)
  Extracts the box object from a BOX wrapper.
  Namespace types: BOX
  Parameters:
    self (BOX): The wrapped BOX instance.
  Returns: The underlying `box` object.

method from_TABLE(self)
  Extracts the table object from a TABLE wrapper.
  Namespace types: TABLE
  Parameters:
    self (TABLE): The wrapped TABLE instance.
  Returns: The underlying `table` object.

method from_CHART_POINT(self)
  Extracts the chart.point from a CHART_POINT wrapper.
  Namespace types: CHART_POINT
  Parameters:
    self (CHART_POINT): The wrapped CHART_POINT instance.
  Returns: The underlying `chart.point` value.

method from_POLYLINE(self)
  Extracts the polyline object from a POLYLINE wrapper.
  Namespace types: POLYLINE
  Parameters:
    self (POLYLINE): The wrapped POLYLINE instance.
  Returns: The underlying `polyline` object.

method from_LINEFILL(self)
  Extracts the linefill object from a LINEFILL wrapper.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The wrapped LINEFILL instance.
  Returns: The underlying `linefill` object.

method has_error(self)
  Returns true if the INT wrapper has an active log entry.
  Namespace types: INT
  Parameters:
    self (INT): The INT instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the FLOAT wrapper has an active log entry.
  Namespace types: FLOAT
  Parameters:
    self (FLOAT): The FLOAT instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the BOOL wrapper has an active log entry.
  Namespace types: BOOL
  Parameters:
    self (BOOL): The BOOL instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the STRING wrapper has an active log entry.
  Namespace types: STRING
  Parameters:
    self (STRING): The STRING instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the COLOR wrapper has an active log entry.
  Namespace types: COLOR
  Parameters:
    self (COLOR): The COLOR instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the LINE wrapper has an active log entry.
  Namespace types: LINE
  Parameters:
    self (LINE): The LINE instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the LABEL wrapper has an active log entry.
  Namespace types: LABEL
  Parameters:
    self (LABEL): The LABEL instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the BOX wrapper has an active log entry.
  Namespace types: BOX
  Parameters:
    self (BOX): The BOX instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the TABLE wrapper has an active log entry.
  Namespace types: TABLE
  Parameters:
    self (TABLE): The TABLE instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the CHART_POINT wrapper has an active log entry.
  Namespace types: CHART_POINT
  Parameters:
    self (CHART_POINT): The CHART_POINT instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the POLYLINE wrapper has an active log entry.
  Namespace types: POLYLINE
  Parameters:
    self (POLYLINE): The POLYLINE instance to check.
  Returns: True if an error or message is active in the log.

method has_error(self)
  Returns true if the LINEFILL wrapper has an active log entry.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The LINEFILL instance to check.
  Returns: True if an error or message is active in the log.

void_return()
  Utility function used when a return is syntactically required but functionally unnecessary.
  Returns: Nothing. Function never executes its body.

argument_error(condition, function, argument, message)
  Throws a runtime error when a condition is met. Used for strict argument validation.
  Parameters:
    condition (bool): Boolean expression that triggers the runtime error.
    function (string): Name of the calling function (for formatting).
    argument (string): Name of the problematic argument.
    message (string): Description of the error cause.
  Returns: Never returns. Halts execution if the condition is true.

argument_log_info(condition, function, argument, message)
  Logs an informational message when a condition is met. Used for optional debug visibility.
  Parameters:
    condition (bool): Boolean expression that triggers the log.
    function (string): Name of the calling function.
    argument (string): Argument name being referenced.
    message (string): Informational message to log.
  Returns: Nothing. Logs if the condition is true.

argument_log_warning(condition, function, argument, message)
  Logs a warning when a condition is met. Non-fatal but highlights potential issues.
  Parameters:
    condition (bool): Boolean expression that triggers the warning.
    function (string): Name of the calling function.
    argument (string): Argument name being referenced.
    message (string): Warning message to log.
  Returns: Nothing. Logs if the condition is true.

argument_log_error(condition, function, argument, message)
  Logs an error message when a condition is met. Does not halt execution.
  Parameters:
    condition (bool): Boolean expression that triggers the error log.
    function (string): Name of the calling function.
    argument (string): Argument name being referenced.
    message (string): Error message to log.
  Returns: Nothing. Logs if the condition is true.

init_static_log(error_type, message, active)
  Initializes a persistent (var) Log object. Ideal for global logging in scripts or modules.
  Parameters:
    error_type (series ErrorType): Initial severity level (required).
    message (string): Optional starting message string. Default value of ("").
    active (bool): Whether the log should be flagged active on initialization. Default value of (false).
  Returns: A static Log object with the given parameters.

method new_line(self)
  Appends a newline character to the Log message. Useful for separating entries during chained writes.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance to modify.
  Returns: The updated Log object with a newline appended.

method write(self, message, flag_active, error_type)
  Appends a message to a Log object without a newline. Updates severity and active state if specified.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance being modified.
    message (string): The text to append to the log.
    flag_active (bool): Whether to activate the log for conditional rendering. Default value of (false).
    error_type (series ErrorType): Optional override for the severity level. Default value of (na).
  Returns: The updated Log object.

method write_line(self, message, flag_active, error_type)
  Appends a message to a Log object, prefixed with a newline for clarity.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance being modified.
    message (string): The text to append to the log.
    flag_active (bool): Whether to activate the log for conditional rendering. Default value of (false).
    error_type (series ErrorType): Optional override for the severity level. Default value of (na).
  Returns: The updated Log object.

method clear(self, flag_active, error_type)
  Clears a Log object’s message and optionally reactivates it. Can also update the error type.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance being cleared.
    flag_active (bool): Whether to activate the log after clearing. Default value of (false).
    error_type (series ErrorType): Optional new error type to assign. If not provided, the previous type is retained. Default value of (na).
  Returns: The cleared Log object.

method render_condition(self, flag_active, error_type)
  Conditionally renders the log if it is active. Allows overriding error type and controlling active state afterward.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance to evaluate and render.
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override. Useful for contextual formatting just before rendering. Default value of (na).
  Returns: The updated Log object.

method render_now(self, flag_active, error_type)
  Immediately renders the log regardless of `active` state. Allows overriding error type and active flag.
  Namespace types: Log
  Parameters:
    self (Log): The Log instance to render.
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override. Allows dynamic severity adjustment at render time. Default value of (na).
  Returns: The updated Log object.

render(self, condition, flag_active, error_type)
  Renders the log conditionally or unconditionally. Allows full control over render behavior.
  Parameters:
    self (Log): The Log instance to render.
    condition (bool): If true, renders only if the log is active. If false, always renders. Default value of (false).
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override passed to the render methods. Default value of (na).
  Returns: The updated Log object.

Log
  A structured object used to store and render logging messages.
  Fields:
    error_type (series ErrorType): The severity level of the message (from the ErrorType enum).
    message (series string): The text of the log message.
    active (series bool): Whether the log should trigger rendering when conditionally evaluated.

INT
  A wrapped integer type with attached logging for validation or tracing.
  Fields:
    v (series int): The underlying `int` value.
    e (Log): Optional log object describing validation status or error context.

FLOAT
  A wrapped float type with attached logging for validation or tracing.
  Fields:
    v (series float): The underlying `float` value.
    e (Log): Optional log object describing validation status or error context.

BOOL
  A wrapped boolean type with attached logging for validation or tracing.
  Fields:
    v (series bool): The underlying `bool` value.
    e (Log): Optional log object describing validation status or error context.

STRING
  A wrapped string type with attached logging for validation or tracing.
  Fields:
    v (series string): The underlying `string` value.
    e (Log): Optional log object describing validation status or error context.

COLOR
  A wrapped color type with attached logging for validation or tracing.
  Fields:
    v (series color): The underlying `color` value.
    e (Log): Optional log object describing validation status or error context.

LINE
  A wrapped line object with attached logging for validation or tracing.
  Fields:
    v (series line): The underlying `line` value.
    e (Log): Optional log object describing validation status or error context.

LABEL
  A wrapped label object with attached logging for validation or tracing.
  Fields:
    v (series label): The underlying `label` value.
    e (Log): Optional log object describing validation status or error context.

BOX
  A wrapped box object with attached logging for validation or tracing.
  Fields:
    v (series box): The underlying `box` value.
    e (Log): Optional log object describing validation status or error context.

TABLE
  A wrapped table object with attached logging for validation or tracing.
  Fields:
    v (series table): The underlying `table` value.
    e (Log): Optional log object describing validation status or error context.

CHART_POINT
  A wrapped chart point with attached logging for validation or tracing.
  Fields:
    v (chart.point): The underlying `chart.point` value.
    e (Log): Optional log object describing validation status or error context.

POLYLINE
  A wrapped polyline object with attached logging for validation or tracing.
  Fields:
    v (series polyline): The underlying `polyline` value.
    e (Log): Optional log object describing validation status or error context.

LINEFILL
  A wrapped linefill object with attached logging for validation or tracing.
  Fields:
    v (series linefill): The underlying `linefill` value.
    e (Log): Optional log object describing validation status or error context.

3 hari lalu

Nota Keluaran

v2

Minor (or major? lol) fix with pass through conditions.

self.error_type := switch
		not na(error_type) => error_type
		=> error_type

is now

self.error_type := switch
		not na(error_type) => error_type
		=> self.error_type

and

self.error_type := switch
		not na(error_type) => error_type
		=> error_type

	self.message += message

	self.active := switch
		flag_active => true
		=> flag_active

is now

self.error_type := switch
		not na(error_type) => error_type
		=> self.error_type

	self.message += message

	self.active := switch
		flag_active => true
		=> self.active
	self

Whoops lol

3 hari lalu

Nota Keluaran

Added log manipulation wrappers for all error wrapped types.

v3

Updated:
method new_line(self)
  Appends a newline character to the Log message. Useful for separating entries during chained writes.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance to modify.
  Returns: The updated Log object with a newline appended.

method write(self, message, flag_active, error_type)
  Appends a message to a Log object without a newline. Updates severity and active state if specified.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance being modified.
    message (string): The text to append to the log.
    flag_active (bool): Whether to activate the log for conditional rendering. Default value of (false).
    error_type (series ErrorType): Optional override for the severity level. Default value of (na).
  Returns: The updated Log object.

method write_line(self, message, flag_active, error_type)
  Appends a message to a Log object, prefixed with a newline for clarity.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance being modified.
    message (string): The text to append to the log.
    flag_active (bool): Whether to activate the log for conditional rendering. Default value of (false).
    error_type (series ErrorType): Optional override for the severity level. Default value of (na).
  Returns: The updated Log object.

method clear(self, flag_active, error_type)
  Clears a Log object’s message and optionally reactivates it. Can also update the error type.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance being cleared.
    flag_active (bool): Whether to activate the log after clearing. Default value of (false).
    error_type (series ErrorType): Optional new error type to assign. If not provided, the previous type is retained. Default value of (na).
  Returns: The cleared Log object.

method render_condition(self, flag_active, error_type)
  Conditionally renders the log if it is active. Allows overriding error type and controlling active state afterward.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance to evaluate and render.
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override. Useful for contextual formatting just before rendering. Default value of (na).
  Returns: The updated Log object.

method render_now(self, flag_active, error_type)
  Immediately renders the log regardless of `active` state. Allows overriding error type and active flag.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The Log instance to render.
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override. Allows dynamic severity adjustment at render time. Default value of (na).
  Returns: The updated Log object.

render(self, condition, flag_active, error_type)
  Renders the log conditionally or unconditionally. Allows full control over render behavior.
  Parameters:
    self (LINEFILL): The Log instance to render.
    condition (bool): If true, renders only if the log is active. If false, always renders. Default value of (false).
    flag_active (bool): Whether to activate the log after rendering. Default value of (false).
    error_type (series ErrorType): Optional error type override passed to the render methods. Default value of (na).
  Returns: The updated Log object.

kelmarin

Nota Keluaran

Added value logging, allowing for users to log a variable with a simple function/method.

v4

Added:
method log_value(self, var_name)
  Logs the internal state of a LINEFILL value to the console.
Includes value breakdown and optional variable name if provided.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The value to log.
    var_name (string): Optional name of the variable for display in the output.
  Returns: Nothing. Emits a structured `log.info()` message.

Updated:
method INT(self)
  Converts a FLOAT wrapper to an INT wrapper, truncating the float value.
The original log context is preserved.
  Namespace types: FLOAT
  Parameters:
    self (FLOAT): The FLOAT instance to convert.
  Returns: An INT wrapper with the truncated integer value and original log.

method FLOAT(self)
  Converts an INT wrapper to a FLOAT wrapper.
The original log context is preserved.
  Namespace types: INT
  Parameters:
    self (INT): The INT instance to convert.
  Returns: A FLOAT wrapper with the float-casted value and original log.

method STRING(self)
  Converts a FLOAT wrapper to a STRING wrapper using `str.tostring()`.
The original log context is preserved.
  Namespace types: FLOAT
  Parameters:
    self (FLOAT): The FLOAT instance to convert.
  Returns: A STRING wrapper with the string representation and original log.

kelmarin

Nota Keluaran

Now you can get formatted strings for all of the types. You can also pick the log level for the log_value() methods.

v5

Added:
method log_level(self, error_type)
  Logs the message from a `Log` object at a specified severity level.
  Namespace types: Log
  Parameters:
    self (Log): The `Log` object containing the message.
    error_type (series ErrorType): The severity level to use when logging the message.
  Returns: Nothing. Emits the `Log.message` using the selected `log.*` or `runtime.error`.

method value_string(self, var_name)
  Returns a formatted string of a `LINEFILL` object, including both lines and error info.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The `LINEFILL` object to stringify.
    var_name (string): Optional variable name for identification.
  Returns: A formatted string of both line components and their error state.

Updated:
method log_value(self, var_name, error_type)
  Logs both lines and error context of a `LINEFILL` object.
  Namespace types: LINEFILL
  Parameters:
    self (LINEFILL): The wrapped linefill type (`LINEFILL`).
    var_name (string): Optional variable name label for clarity in logs.
    error_type (series ErrorType): The severity level to use for logging (default: `info`).
  Returns: Nothing. Emits a log at the specified level.