NAME

       trace-run -  (debugging)

PURPOSE

       Emit trace.

SYNTAX

           trace-run [ <format>, <variable> [ , ... ] ]

DESCRIPTION

       trace-run  formats  a tracing message according to the <format> string and a list of <variable>s and then
       writes the result into current process' trace file.

       trace-run can be used without any clauses, in which case a  location  (file  name  and  line  number)  is
       recorded  in  the  trace file - this is useful when you only want to know if the execution passed through
       your code.

       If trace-run has any other clauses, then <format> string must be present and there must be at  least  one
       <variable> (it means if you want to trace a simple string literal you still have to use "%s" as format).

       For  tracing  to  have  effect,  tracing must be enabled (see "--debug" and "--trace" options in gg). For
       location of trace files, see directories.

       FORMAT

       <format> string must be a literal. Variables must follow <format> separated by commas in the  same  order
       as placeholders. If you use any placeholders other than specified below, or the type of variables you use
       do  not  match  the type of a corresponding placeholder in <format>, your program will error out. You can
       use the following placeholders in <format> (see trace-run for an example of usage):

           • %s for a string

           • %c for a number displayed as a character,

           • %<number>s for a string output with a width of at least <number> (any excess filled with spaces  to
           the left),

           • %ld for a number (use "lo" for displaying in octal notation and "lx" for hexadecimal notation).

           • %<number>ld for a number output with a width of at least <number> (any excess filled with spaces to
           the left). Use "lo" for displaying in octal notation and "lx" for hexadecimal notation.

       Here's an example of using the format placeholders:

           %% /my-request public
               @Hi
               trace-run "%s it's %ld degrees outside, or with minimum width: %20s it's %20ld outside", "yes", 90, "yes", 90
           %%

       Create and make the application:

           sudo mgrg -i -u $(whoami) test
           gg --trace --debug

       Run it:

           gg -r --req="/my-request" --exec

       The output is:

           Hi

       And to find the location of trace file:

           gg -t 1

       The line in the trace file output by your trace-run would be similar to:

           2024-08-01-17-13-55 (my_request.golf:4)| my_request yes it's 90 degrees outside, or with minimum width:                  yes it's                   90 outside

EXAMPLES

           // Trace information
           trace-run "Program wrote %ld bytes into file %s", num_bytes, file_name

           // Trace that program execution passed through here
           trace-run

SEE ALSO

        Debugging

       debugging trace-run See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)