CBICA Toolkit  1.0.0
cbicaLogging.h
Go to the documentation of this file.
1 /**
2 \file cbicaLogging.h
3 
4 \brief Declaration of the Logging class
5 
6 https://www.med.upenn.edu/sbia/software/// <br>
7 software@cbica.upenn.edu
8 
9 Copyright (c) 2016 University of Pennsylvania. All rights reserved. <br>
10 See COPYING file or https://www.med.upenn.edu/cbica/software-agreement.html
11 
12 */
13 #pragma once
14 
15 #include <iostream>
16 #include <fstream>
17 #include <memory>
18 #include <time.h>
19 #include <stdio.h>
20 
21 #include "cbicaUtilities.h"
22 
23 /*
24 \namespace cbica
25 \brief Namespace for differentiating functions written for internal use
26 */
27 namespace cbica
28 {
29  /**
30  \class Logging
31 
32  \brief The logging class.
33 
34  This automatically generates a machine-parseable log specified by the file name. The user also has the option
35  of submitting free text to be put along with the log. The generated log is in the format show below:
36 
37  <code><4 digit year>:<2 digit month>:<2 digit date>,<2 digit 24 hour>:<2 digit minute>:<2 digit second>;<exe name>;<user name>;<free text></code>
38 
39  Usage:
40  \verbatim
41  // writing to a file
42  cbica::Logging logger( "file_name.txt", "randomness is highly underrated" ); // the file has already been written at this point and can be viewed
43  // to write to console, either initialize the class as 'cbica::Logging logger;' or call EnableConsoleLogging() after the initialization.
44  ...
45  // more code
46  ...
47  logger.Write( "'I accept chaos, I'm not sure whether it accepts me' - Bob Dylan" ); // writes to file_name.txt
48  \endverbatim
49 
50  The class defaults to console logging. Use Logging::EnableTextLogging() or UseNewFile() to switch;
51  by default, it writes to a text file 'EXE_NAME-log.txt' in directory specified by cbica::createTemporaryDirectory()
52  */
53  class Logging
54  {
55  public:
56  /**
57  \brief Actual Constructor
58 
59  \param file_name_with_path The file onto which the log file is to be written
60  \param FreeText_input Free text which the user wants to be present in the log, defaults to an empty string
61  */
62  explicit Logging(const std::string file_name, const std::string FreeText_input);
63 
64  /**
65  \brief Default constructor
66 
67  Just used to keep a track of the user name and executable run at a particular time.
68  */
69  explicit Logging();
70 
71  /**
72  \brief Default constructor
73 
74  Just used to keep a track of the user name and executable run at a particular time.
75  */
76  Logging(const Logging &origin);
77 
78  /**
79  \brief Change Logging file after initializing class
80 
81  \param newLogFile Path of new log file. If empty, it becomes 'cbica::createTmpDir() + cbica::getExecutableName() + "-log.txt"'
82  */
83  void UseNewFile(const std::string &newLogFile);
84 
85  //! The Destructor
86  virtual ~Logging();
87 
88  /**
89  \brief Function to call to write error messages to log file without any free text
90 
91  \param FreeText_input Free text which the user wants to be present in the log
92  */
93  void WriteError(const std::string FreeText_input);
94 
95  /**
96  \brief Function to call to write to log file
97 
98  \param FreeText_input Free text which the user wants to be present in the log, defaults to an empty string
99  */
100  void Write(const std::string FreeText_input);
101 
102  /**
103  \brief Switches from console to text file logging
104 
105  The output stamps are of the form:
106 
107  <4 digit year>:<2 digit month>:<2 digit date>,<2 digit 24 hour>:<2 digit minute>:<2 digit second>;<free text>
108  */
109  void EnableTextLogging(const std::string &newLogFile);
110 
111  /**
112  \brief This is useful in scenarios where the application has been installed in a multi-user machine.
113 
114  This also disables writing of the date in the log since the assumption is that on a single user machine, the filename should be in the following format:
115  ${userHomeDir}/.${appName}/${currentDate} (see CaPTk logging as example). This also disables the writing of the executable name.
116  */
118  {
119  m_multiUserLog = true;
120  }
121 
122  /**
123  \brief Switches from text to console file logging
124 
125  This is helpful if the user wants to visualize the console output. If it is done for saving, the recommended way is to call EnableTextLogging().
126 
127  The output stamps are of the form:
128 
129  <4 digit year>:<2 digit month>:<2 digit date>,<2 digit 24 hour>:<2 digit minute>:<2 digit second>;<free text>
130  */
131  void EnableConsoleLogging();
132 
133  /**
134  \brief This enables logging the date and time in GMT rather than in local (which is the default behavior)
135  */
136  void EnableGMTLogging();
137 
138  /**
139  \brief Get the file name with full path where log has happened
140 
141  \return file_name_with_path
142  */
143  std::string getLoggingFileName();
144 
145  protected:
146  /**
147  \brief The function used to initialize the class
148 
149  Kept private to avoid cluttering global namespace.
150 
151  \param file_name_with_path_wrap Wrap for file_name_with_path
152  \param log_file_wrap Wrap for log_file
153  \param exe_name_wrap Wrap for exe_name
154  \param user_name_wrap Wrap for user_name
155  */
156  inline void initialize_class( std::string &file_name_with_path_wrap,
157  std::ofstream &log_file_wrap, std::string &exe_name_wrap, std::string &user_name_wrap );
158 
159  /**
160  \brief The function used to do the actual writing onto the file
161 
162  Kept private to avoid cluttering global namespace.
163 
164  \param FreeText_wrap Wrap for FreeText
165  \param log_file_wrap Wrap for log_file
166  \param timer_wrap Wrap for timer
167  \param exe_name_wrap Wrap for exe_name
168  \param user_name_wrap Wrap for user_name
169  */
170  inline void writing_function( const std::string &FreeText_wrap, std::ofstream &log_file_wrap,
171  const std::string &exe_name_wrap, const std::string &user_name_wrap, bool isError = false );
172 
173  private:
174  //! The file handler class
175  std::ofstream log_file;
176  //! The name of the executable calling the class
177  std::string exe_name;
178  //! The current active user name
179  std::string user_name;
180  //! The free text to be written the log file. It is taken as input from user_name
181  //std::string FreeText;
182  //! File path
183  std::string file_name_with_path;
184  //! Flag to initialize local logging
185  bool consoleLogging;
186  //! Flag to denote logging in GMT
187  bool GMTLogging;
188  //! This writes out user and exe name(s) to the log
189  bool m_multiUserLog = false;
190  };
191 }
Logging()
Default constructor.
The logging class.
Definition: cbicaLogging.h:53
void writing_function(const std::string &FreeText_wrap, std::ofstream &log_file_wrap, const std::string &exe_name_wrap, const std::string &user_name_wrap, bool isError=false)
The function used to do the actual writing onto the file.
std::string getLoggingFileName()
Get the file name with full path where log has happened.
void EnableGMTLogging()
This enables logging the date and time in GMT rather than in local (which is the default behavior)
void EnableTextLogging(const std::string &newLogFile)
Switches from console to text file logging.
void Write(const std::string FreeText_input)
Function to call to write to log file.
void EnableMultiUserLogging()
This is useful in scenarios where the application has been installed in a multi-user machine.
Definition: cbicaLogging.h:117
void UseNewFile(const std::string &newLogFile)
Change Logging file after initializing class.
void WriteError(const std::string FreeText_input)
Function to call to write error messages to log file without any free text.
Some basic utility functions.
virtual ~Logging()
The Destructor.
void EnableConsoleLogging()
Switches from text to console file logging.
void initialize_class(std::string &file_name_with_path_wrap, std::ofstream &log_file_wrap, std::string &exe_name_wrap, std::string &user_name_wrap)
The function used to initialize the class.