diff --git a/doc/specs/stdlib_logger.md b/doc/specs/stdlib_logger.md index 2f902a98d..9677b48ad 100644 --- a/doc/specs/stdlib_logger.md +++ b/doc/specs/stdlib_logger.md @@ -29,7 +29,7 @@ The logger variables have the option to: that prompted the log message; * follow a message with the `iostat` and `iomsg` of the I/O error report that prompted the log message; -* label a message with one of `'INFO: '`, `'WARN: '`, +* label a message with one of `'DEBUG: '`, `'INFO: '`, `'WARN: '`, `'ERROR: '`, or `'I/O ERROR: '`; * indent subsequent lines of the messages; and * format the text to fit within a maximum column width. @@ -110,6 +110,7 @@ Method | Class | Description [`add_log_unit`](./stdlib_logger.html#add_log_unit-add-a-unit-to-the-array-self-log_units) | Subroutine | Adds an existing unit to the `log_units` list [`configuration`](./stdlib_logger.html#configuration-report-a-loggers-configuration) | Subroutine | Reports the details of the logging configuration [`configure`](./stdlib_logger.html#configure-configure-the-logging-process) | Subroutine | Configures the details of the logging process +[`log_debug`](./stdlib_logger.html#log_debug-writes-the-string-message-to-self-log_units) | Subroutine | Sends a message prepended by `'DEBUG: '` [`log_error`](./stdlib_logger.html#log_error-writes-the-string-message-to-self-log_units) | Subroutine | Sends a message prepended by `'ERROR: '` optionally followed by a `stat` or `errmsg` [`log_information`](./stdlib_logger.html#log_information-writes-the-string-message-to-self-log_units) | Subroutine | Sends a message prepended by `'INFO: '` [`log_io_error`](./stdlib_logger.html#log_io_error-write-the-string-message-to-self-log_units) | Subroutine | Sends a message prepended by `'I/O ERROR: '` optionally followed by an `iostat` or `iomsg` @@ -395,6 +396,75 @@ program demo_configure end program demo_configure ``` +### `log_debug` - Writes the string `message` to `self % log_units` + +#### Status + +Experimental + +#### Description + +Writes the string `message` to `self % log_units` with optional additional text. + +#### Syntax + +`call self % [[logger_type(type):log_debug(bound)]]( message [, module, procedure ] )` + +#### Behavior + +If time stamps are active, a time stamp is written, followed +by `module` and `procedure` if present, and then +`message` is written with the prefix `'DEBUG: '`. + +#### Class + +Subroutine + +#### Arguments + +`self`: shall be a scalar variable of type `logger_type`. It is an +`intent(in)` argument. It is the logger used to send the message. + +`message`: shall be a scalar default character expression. It is an + `intent(in)` argument. + +* Note `message` may have embedded new_line calls. + +`module` (optional): shall be a scalar default character + expression. It is an `intent(in)` argument. It should be the name of + the module containing the `log_information` call. + +`procedure` (optional): shall be a scalar default character + expression. It is an `intent(in)` argument. It should be the name of + the procedure containing the `log_information` call. + +#### Example + +```fortran +module example_mod + use stdlib_logger + + real, allocatable :: a(:) + + type(logger_type) :: logger + contains + + subroutine example_sub( selection ) + integer, intent(out) :: selection + character(128) :: errmsg, message + integer :: stat + write(*,'(a)') "Enter an integer to select a widget" + read(*,'(i0)') selection + write( message, '(a, i0)' ) & + "The user selected ", selection + call logger % log_DEBUG( message, & + module = 'EXAMPLE_MOD', procedure = 'EXAMPLE_SUB' ) + + end subroutine example_sub + +end module example_mod +``` + ### `log_error` - Writes the string `message` to `self % log_units` #### Status diff --git a/src/stdlib_logger.f90 b/src/stdlib_logger.f90 index 0cdaa4f36..979aeed29 100644 --- a/src/stdlib_logger.f90 +++ b/src/stdlib_logger.f90 @@ -91,6 +91,7 @@ module stdlib_logger procedure, public, pass(self) :: add_log_unit procedure, public, pass(self) :: configuration procedure, public, pass(self) :: configure + procedure, public, pass(self) :: log_debug procedure, public, pass(self) :: log_error procedure, public, pass(self) :: log_information procedure, public, pass(self) :: log_io_error @@ -755,6 +756,64 @@ subroutine handle_write_failure( unit, procedure_name, iostat, iomsg ) end subroutine handle_write_failure + subroutine log_debug( self, message, module, procedure ) +!! version: experimental + +!! Writes the string `message` to `self % log_units` with optional additional +!! text. +!!([Specification](../page/specs/stdlib_logger.html#log_debug-writes-the-string-message-to-self-log_units)) +!! +!!##### Behavior +!! +!! If time stamps are active, a time stamp is written, followed by +!! `module` and `procedure` if present, and then `message` is +!! written with the prefix 'DEBUG: '. +!! +!!##### Example +!! +!! module example_mod +!! use stdlib_logger +!! ... +!! real, allocatable :: a(:) +!! ... +!! type(logger_type) :: alogger +!! ... +!! contains +!! ... +!! subroutine example_sub( selection ) +!! integer, intent(out) :: selection +!! integer :: stat +!! write(*,'(a)') "Enter an integer to select a widget" +!! read(*,'(i0)') selection +!! write( message, `(a, i0)' ) & +!! "The user selected ", selection +!! call alogger % log_debug( message, & +!! module = 'EXAMPLE_MOD', & +!! procedure = 'EXAMPLE_SUB' ) +!! ... +!! end subroutine example_sub +!! ... +!! end module example_mod +!! + + class(logger_type), intent(in) :: self +!! The logger used to send the message + character(len=*), intent(in) :: message +!! A string to be written to log_unit + character(len=*), intent(in), optional :: module +!! The name of the module contining the current invocation of `log_information` + character(len=*), intent(in), optional :: procedure +!! The name of the procedure contining the current invocation of +!! `log_information` + + call self % log_message( message, & + module = module, & + procedure = procedure, & + prefix = 'DEBUG' ) + + end subroutine log_debug + + subroutine log_error( self, message, module, procedure, stat, errmsg ) !! version: experimental diff --git a/src/tests/logger/test_stdlib_logger.f90 b/src/tests/logger/test_stdlib_logger.f90 index 9c7c9944e..8a9e1d959 100644 --- a/src/tests/logger/test_stdlib_logger.f90 +++ b/src/tests/logger/test_stdlib_logger.f90 @@ -142,6 +142,22 @@ subroutine test_logging_configuration() module = 'N/A', & procedure = 'TEST_STDLIB_LOGGER' ) + call global % log_debug( 'This message should be output ' // & + 'to OUTPUT_UNIT, unlimited in width, not preceded by ' // & + 'a blank line, then by a time stamp, then by MODULE % ' // & + 'PROCEDURE, be prefixed by DEBUG and be indented on ' // & + 'subsequent lines by 4 columns.', & + module = 'N/A', & + procedure = 'TEST_STDLIB_LOGGER' ) + + call global % log_debug( 'This message should be output ' // & + 'to OUTPUT_UNIT, unlimited in width, not preceded by ' // & + 'a blank line, then by a time stamp, then by MODULE % ' // & + 'PROCEDURE, be prefixed by DEBUG. ' // new_line('a') // & + 'This is a new line of the same log message.', & + module = 'N/A', & + procedure = 'TEST_STDLIB_LOGGER' ) + call global % configure( add_blank_line=.true., indent=.false., & max_width=72, time_stamp=.false. )