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

Command procedures
==================

These procedures are related to the execution of SPEX commands and the SPEX command prompt.

Execute
-------

Executing a single SPEX command through the Fortran interface can be done by:

.. code-block:: fortran

    call spex%execute(command,ier)

The interface of the execute procedure looks like this:

.. code-block:: fortran

      module subroutine spex_utils_execute(this, input, ier)
      class(sapi), intent(inout)    :: this
      character*(*), intent(inout)  :: input
      integer, intent(inout)        :: ier
      end subroutine

Example:

.. code-block:: fortran

    call spex%execute('com cie', ier)

.. _spexapi_log:

Log execute
-----------

Executing a range of SPEX commands is done in SPEX with the ``log execute`` command.
The equivalent procedure in Fortran is:

.. code-block:: fortran

    call spex%log_exec(filename,ier)

The interface for this procedure looks like this:

.. code-block:: fortran

      module subroutine spex_utils_log_execute(this, filename, ier)
      class(sapi), intent(inout)    :: this
      character*(*), intent(in)     :: filename       !! input filename
      integer, intent(inout)        :: ier
      end subroutine

Example:

.. code-block:: fortran

    call spex%log_exec('my_commands.com',ier)

Log save
--------

Executed SPEX commands can be saved to a file with the ``log save`` command.
Please note that this only saves commands given through the SPEX command
interface. It does not save API calls.

.. code-block:: fortran

    call spex%log_save(filename,fmode,ier)

The Fortran interface looks like this:

.. code-block:: fortran

    module subroutine spex_utils_log_save(this,filename,fmode,ier)
    class(sapi), intent(inout)    :: this
    character(len=32), intent(in) :: filename     !! Log save filename (without .com)
    character(len=32), intent(in) :: fmode        !! overwrite,append
    integer, intent(inout)        :: ier
    end subroutine

This procedure opens a file and saves all subsequent commands given.
At the end of the session, the save file needs to be closed with:

.. code-block:: fortran

    call spex%log_save_close()

Example:

.. code-block:: fortran

    call spex%log_save('my_session.com','overwrite',ier)
    call spex%execute('com cie')
    call spex%log_save_close()

Log output
----------

The terminal output of SPEX can be saved to a file as well with the ``log output`` command.
The equivalent in Fortran is the ``log_out`` procedure:

.. code-block:: fortran

    call spex%log_out(filename,fmode,ier)

The Fortran interface looks like this:

.. code-block:: fortran

      module subroutine spex_utils_log_output(this,filename,fmode,ier)
      class(sapi), intent(inout)    :: this
      character(len=32), intent(in) :: filename     !! Log save filename (without .com)
      character(len=32), intent(in) :: fmode        !! overwrite,append
      integer, intent(inout)        :: ier
      end subroutine

This procedure opens a file and writes all subsequent output to it.
At the end of the session, the out file needs to be closed with:

.. code-block:: fortran

    call spex%log_out_close()

Example:

.. code-block:: fortran

    call spex%log_out('my_session.com','overwrite',ier)
    call spex%execute('par show')
    call spex%log_out_close()

Welcome
-------

The SPEX welcome message can be written to the terminal with the ``welcome`` procedure:

.. code-block:: fortran

    call spex%welcome()

News
----

An overview of the recent changes to SPEX can be written to the terminal with the
``news`` procedure:

.. code-block:: fortran

    call spex%news(ier)

Where ``ier`` is the output status integer (0 is OK, non-zero is error).

Prompt
------

One can show a SPEX prompt, which accepts SPEX commands with the ``prompt``
procedure:

.. code-block:: fortran

    call spex%prompt(ier)

This will show the ``SPEX4>`` prompt in the terminal. From this moment onward,
the user can interactively input SPEX commands on the prompt until the
``quit`` command is given. After that, the rest of the program will be executed.


.. _spexapi_watch:

Watch
-----

The equivalent for the SPEX ``watch`` command is the ``watch`` procedure in Fortran:

.. code-block:: fortran

    call spex%watch(wtype,set,ier)

Where ``wtype`` is the watch type, which is either ``time``, to measure the time
spent in subroutines, or ``sub``, to write the executed subroutines to terminal.

The interface is:

.. code-block:: fortran

    module subroutine spex_utils_watch(this, wtype, set, ier)
    class(sapi), intent(inout)    :: this
    character*(*), intent(inout)  :: wtype  !! Watch type
    logical, intent(in)           :: set
    integer, intent(inout)        :: ier
    end subroutine

Example:

.. code-block:: fortran

    call spex%watch('sub',.true.,ier)
    call spex%watch('time',.true.,ier)