Verbose               package:R.utils               R Documentation

_C_l_a_s_s _t_o _w_r_i_t_i_n_g _v_e_r_b_o_s_e _m_e_s_s_a_g_e_s _t_o _a _c_o_n_n_e_c_t_i_o_n _o_r _f_i_l_e

_D_e_s_c_r_i_p_t_i_o_n:

     Package:  R.utils 
      *Class Verbose*

     'Object'
      '~~|'
      '~~+--''Verbose'

     *Directly known subclasses:*
      NullVerbose

     public static class *Verbose*
      extends Object

     Class to writing verbose messages to a connection or file.

_U_s_a_g_e:

     Verbose(con=stderr(), on=TRUE, threshold=0, asGString=TRUE, timestamp=FALSE, removeFile=TRUE, core=TRUE, ...)

_A_r_g_u_m_e_n_t_s:

     con: A 'connection' or a 'character' string filename.

      on: A 'logical' indicating if the writer is on or off.

threshold: A 'numeric' threshold that the 'level' argument of any write
          method has to be equal to or larger than in order to the
          message being written. Thus, the lower the threshold is the
          more and more details will be outputted.

timestamp: If 'TRUE', each output is preceded with a timestamp.

removeFile: If 'TRUE' and 'con' is a filename, the file is first
          deleted, if it exists.

asGString: If 'TRUE', all messages are interpreted as 'GString' before
          being output, otherwise not.

    core: Internal use only.

     ...: Not used.

_F_i_e_l_d_s _a_n_d _M_e_t_h_o_d_s:

     *Methods:*

         'as.character'        Returns a character string version of this object.
         'as.double'           Gets a numeric value of this object.
         'as.logical'          Gets a logical value of this object.
         'capture'             Captures output of a function.
         'cat'                 Concatenates and prints objects if above threshold.
         'enter'               Writes a message and indents the following output.
         'equals'              Checks if this object is equal to another.
         'evaluate'            Evaluates a function and prints its results if above threshold.
         'exit'                Writes a message and unindents the following output.
         'getThreshold'        Gets current verbose threshold.
         'getTimestampFormat'  Gets the default timestamp format.
         'header'              Writes a header.
         'isOn'                Checks if the output is on.
         'isVisible'           Checks if a certain verbose level will be shown or not.
         'newline'             Writes one or several empty lines.
         'off'                 Turn off the output.
         'on'                  Turn on the output.
         'popState'            -
         'print'               Prints objects if above threshold.
         'printf'              Formats and prints object if above threshold.
         'pushState'           Pushes the current indentation state of the Verbose object.
         'ruler'               Writes a ruler.
         'setDefaultLevel'     Sets the current default verbose level.
         'setThreshold'        Sets verbose threshold.
         'setTimestampFormat'  Sets the default timestamp format.
         'str'                 Prints the structure of an object if above threshold.
         'summary'             Generates a summary of an object if above threshold.
         'timestamp'           Writes a timestamp.
         'timestampOff'        -
         'timestampOn'         Turns automatic timestamping on and off.
         'warnings'            Outputs any warnings recorded.
         'writeRaw'            Writes objects if above threshold.

     *Methods inherited from Object*:
      $, $<-, [[, [[<-, as.character, attach, attachLocally, clone,
     detach, equals, extend, finalize, getFields, getInstanciationTime,
     getStaticInstance, hasField, hashCode, ll, load, objectSize,
     print, save

_O_u_t_p_u_t _l_e_v_e_l_s:

     As a guideline, use the following levels when outputting
     verbose/debug message using the Verbose class. For a message to be
     shown, the output level must be greater than (not equal to)
     current threshold. Thus, the lower the threshold is set, the more
     messages will be seen.

   <= -_1_0_0 Only for debug messages, i.e. messages containing all
        necessary information for debugging purposes and to find bugs
        in the code. Normally these messages are so detailed so they
        will be a pain for the regular user, but very useful for bug
        reporting and bug tracking by the developer.

   -_9_9 - -_1_1 Detailed verbose messages. These will typically be useful
        for the user to understand what is going on and do some simple
        debugging fixing problems typically due to themselves and not
        due to bugs in the code.

   -_1_0 - -_1 Verbose messages. For example, these will typically report
        the name of the file to be read, the current step in a sequence
        of analysis steps and so on. These message are not very useful
        for debugging.

   _0 Default level in all output methods and default threshold. Thus,
        by default, messages at level 0 are not shown.

   >= +_1 Message that are always outputted (if threshold is kept at 0).
         We recommend not to output message at this level, because
        methods should be quiet by default (at the default threshold
        0).

_A _c_o_m_p_a_t_i_b_i_l_i_t_y _t_r_i_c_k _a_n_d _a _s_p_e_e_d-_u_p _t_r_i_c_k:

     If you want to include calls to Verbose in a package of yours in
     order to debug code, but not use it otherwise, you might not want
     to load R.utils all the time, but only for debugging. To achieve
     this, the value of a reference variable to a Verbose class is
     always set to 'TRUE', cf. typically an Object reference has value
     'NA'. This makes it possible to use the reference variable as a
     first test before calling Verbose methods. Example:


         foo <- function(..., verbose=FALSE) {
           # enter() will never be called if verbose==FALSE, thus no
     error.
           verbose && enter(verbose, "Loading")
         }

     Thus, R.utils is not required for 'foo()', but for
     'foo(verbose==Verbose(level=-1))' it is.

     Moreover, if using the 'NullVerbose' class for ignoring all
     verbose messages, the above trick will indeed speed up the code,
     because the value of a NullVerbose reference variable is always
     'FALSE'.

_A_u_t_h_o_r(_s):

     Henrik Bengtsson (<URL: http://www.braju.com/R/>)

_S_e_e _A_l_s_o:

     'NullVerbose'.

_E_x_a_m_p_l_e_s:

     verbose <- Verbose(threshold=-1)

     header(verbose, "A verbose writer example", padding=0)

     enter(verbose, "Analysis A")
     for (kk in 1:10) {
       printf(verbose, "step %d\n", kk)
       if (kk == 2) {
         cat(verbose, "Turning ON automatic timestamps")
         timestampOn(verbose);
       } else if (kk == 4) {
         timestampOff(verbose);
         cat(verbose, "Turned OFF automatic timestamps")
         cat(verbose, "Turning OFF verbose messages for steps ", kk, "-6")
         off(verbose)
       } else if (kk == 6) {
         on(verbose)
         cat(verbose, "Turned ON verbose messages just before step ", kk+1)
       }

       if (kk %in% c(5,8)) {
         enter(verbose, "Sub analysis ", kk)
         for (jj in c("i", "ii", "iii")) {
           cat(verbose, "part ", jj)
         }
         exit(verbose)
       }
     }
     cat(verbose, "All steps completed!")
     exit(verbose)

     ruler(verbose)
     cat(verbose, "Demo of some other methods:")
     str(verbose, c(a=1, b=2, c=3))
     print(verbose, c(a=1, b=2, c=3))
     summary(verbose, c(a=1, b=2, c=3))
     evaluate(verbose, rnorm, n=3, mean=2, sd=3)

     ruler(verbose)
     newline(verbose)

