.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

Message System (message)
========================

**Module**: ``utils_message``

Overview
--------

Provides SPEX messaging system for terminal output, warnings, error messages, and logging. Supports both interactive and API modes.

Key Features
------------

- Standardized message output
- Error tracking and counting
- Warning and informational messages
- Log file support
- API mode for Python interface

Types
-----

**message**

Main message handling object:

.. list-table::
   :widths: 20 30 50
   :header-rows: 1

   * - Component
     - Type
     - Description
   * - ``errtot``
     - integer
     - Total number of errors detected
   * - ``luw``
     - integer
     - Logical unit for terminal output
   * - ``lue``
     - integer
     - Logical unit for error output
   * - ``apimode``
     - logical
     - .true. for Python API mode
   * - ``sav``
     - type(files)
     - File handler for save operations
   * - ``out``
     - type(files)
     - File handler for log output

**Global Instance**

A global message object is available:

.. code-block:: fortran

   type(message) :: mesg  ! Global message handler

API Reference
-------------

Methods
~~~~~~~

**spout**

.. function:: mesg%spout(string)

   Write standard output message

   :param string: Message text (character(*), input)
   :return: None
   
   Writes to terminal and log file if active.

**sper**

.. function:: mesg%sper(string)

   Write error message and increment error counter

   :param string: Error message text (character(*), input)
   :return: None
   
   Prefixes message with "Error: " and increments ``errtot``.

**spwng**

.. function:: mesg%spwng(string)

   Write warning message

   :param string: Warning message text (character(*), input)
   :return: None
   
   Prefixes message with "Warning: ".

**spexstop**

.. function:: mesg%spexstop()

   Terminate SPEX execution

   :return: None
   
   Stops program execution gracefully.

**lushow**

.. function:: mesg%lushow(lu)

   Show logical unit information

   :param lu: Logical unit to display (integer, input)
   :return: None
   
   Displays information about specified logical unit.

Usage Examples
--------------

**Basic Message Usage**

.. code-block:: fortran

   use utils_message
   type(message) :: mesg
   
   ! Standard output
   call mesg%spout('Processing started...')
   
   ! Warning message
   call mesg%spwng('Low signal-to-noise ratio detected')
   
   ! Error message
   call mesg%sper('Invalid parameter value')
   
   write(*,*) 'Total errors:', mesg%errtot

**Error Handling Pattern**

.. code-block:: fortran

   use utils_message
   type(message) :: mesg
   integer :: status
   
   ! Operation with error checking
   call some_operation(status)
   if (status /= 0) then
      call mesg%sper('Operation failed with error code: ' // status)
      call mesg%spexstop()  ! Terminate on critical error
   endif

**Logging to File**

.. code-block:: fortran

   use utils_message
   type(message) :: mesg
   
   ! Enable log file
   call mesg%out%open('processing', 'log', 1, 2, status)
   if (status == 0) then
      call mesg%spout('Log file opened')
      
      ! Messages now go to both terminal and log
      call mesg%spout('Processing data...')
      call mesg%spwng('Background subtraction applied')
      
      ! Close log when done
      call mesg%out%close(status)
   endif

**API Mode for Python**

.. code-block:: fortran

   use utils_message
   type(message) :: mesg
   
   ! Enable API mode (suppresses some terminal output)
   mesg%apimode = .true.
   
   ! Messages handled differently in API mode
   call mesg%spout('API mode activated')
   call mesg%spwng('Running in batch mode')

**Error Counting**

.. code-block:: fortran

   use utils_message
   type(message) :: mesg
   integer :: i, n_operations
   
   ! Reset error counter
   mesg%errtot = 0
   
   ! Perform multiple operations
   n_operations = 10
   do i = 1, n_operations
      if (operation_failed(i)) then
         call mesg%sper('Operation ' // i // ' failed')
      endif
   enddo
   
   ! Report final error count
   if (mesg%errtot > 0) then
      call mesg%spwng('Completed with errors: ' // mesg%errtot)
   else
      call mesg%spout('All operations completed successfully')
   endif

Notes
-----

**Message Types**

.. list-table::
   :widths: 20 30 50
   :header-rows: 1

   * - Method
     - Prefix
     - Typical Usage
   * - ``spout``
     - None
     - Informational messages
   * - ``sper``
     - "Error: "
     - Error conditions
   * - ``spwng``
     - "Warning: "
     - Non-critical issues

**Error Handling**

- ``errtot`` counter tracks total errors
- Use for validation and quality control
- Reset counter as needed for different operations

**Performance**

- Minimal overhead for message operations
- Buffered output for efficiency
- Suitable for frequent messaging

**Best Practices**

1. **Use appropriate message type** for each situation
2. **Check error counter** for critical operations
3. **Enable logging** for important processes
4. **Use API mode** for batch processing
5. **Provide clear, actionable** error messages

See Also
--------

- :doc:`system` - System information
- :doc:`../io/scratch` - Temporary file management