apt-pkg/contrib/error.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: error.h,v 1.8 2001/05/07 05:06:52 jgg Exp $
   4 /* ######################################################################
   5
   6    Global Erorr Class - Global error mechanism
   7
   8    This class has a single global instance. When a function needs to
   9    generate an error condition, such as a read error, it calls a member
  10    in this class to add the error to a stack of errors.
  11
  12    By using a stack the problem with a scheme like errno is removed and
  13    it allows a very detailed account of what went wrong to be transmitted
  14    to the UI for display. (Errno has problems because each function sets
  15    errno to 0 if it didn't have an error thus eraseing erno in the process
  16    of cleanup)
  17
  18    Several predefined error generators are provided to handle common
  19    things like errno. The general idea is that all methods return a bool.
  20    If the bool is true then things are OK, if it is false then things
  21    should start being undone and the stack should unwind under program
  22    control.
  23
  24    A Warning should not force the return of false. Things did not fail, but
  25    they might have had unexpected problems. Errors are stored in a FIFO
  26    so Pop will return the first item..
  27
  28    I have some thoughts about extending this into a more general UI<->
  29    Engine interface, ie allowing the Engine to say 'The disk is full' in
  30    a dialog that says 'Panic' and 'Retry'.. The error generator functions
  31    like errno, Warning and Error return false always so this is normal:
  32      if (open(..))
  33         return _error->Errno(..);
  34
  35    This source is placed in the Public Domain, do with it what you will
  36    It was originally written by Jason Gunthorpe.
  37
  38    ##################################################################### */
  39                                                                         /*}}}*/
  40 #ifndef PKGLIB_ERROR_H
  41 #define PKGLIB_ERROR_H
  42
  43 #include <apt-pkg/macros.h>
  44
  45 #include <iostream>
  46 #include <list>
  47 #include <string>
  48
  49 #include <stdarg.h>
  50
  51 class GlobalError                                                       /*{{{*/
  52 {
  53 public:                                                                 /*{{{*/
  54         /** \brief a message can have one of following severity */
  55         enum MsgType {
  56                 /** \brief Message will be printed instantly as it is likely that
  57                         this error will lead to a complete crash */
  58                 FATAL = 40,
  59                 /** \brief An error does hinder the correct execution and should be corrected */
  60                 ERROR = 30,
  61                 /** \brief indicates problem that can lead to errors later on */
  62                 WARNING = 20,
  63                 /** \brief deprecation warnings, old fallback behavior, … */
  64                 NOTICE = 10,
  65                 /** \brief for developers only in areas it is hard to print something directly */
  66                 DEBUG = 0
  67         };
  68
  69         /** \brief add a fatal error message with errno to the list
  70          *
  71          *  \param Function name of the function generating the error
  72          *  \param Description format string for the error message
  73          *
  74          *  \return \b false
  75          */
  76         bool FatalE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  77
  78         /** \brief add an Error message with errno to the list
  79          *
  80          *  \param Function name of the function generating the error
  81          *  \param Description format string for the error message
  82          *
  83          *  \return \b false
  84          */
  85         bool Errno(const char *Function,const char *Description,...) __like_printf(3) __cold;
  86
  87         /** \brief add a warning message with errno to the list
  88          *
  89          *  A warning should be considered less severe than an error and
  90          *  may be ignored by the client.
  91          *
  92          *  \param Function Name of the function generates the warning.
  93          *  \param Description Format string for the warning message.
  94          *
  95          *  \return \b false
  96          */
  97         bool WarningE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  98
  99         /** \brief add a notice message with errno to the list
 100          *
 101          *  \param Function name of the function generating the error
 102          *  \param Description format string for the error message
 103          *
 104          *  \return \b false
 105          */
 106         bool NoticeE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 107
 108         /** \brief add a debug message with errno to the list
 109          *
 110          *  \param Function name of the function generating the error
 111          *  \param Description format string for the error message
 112          *
 113          *  \return \b false
 114          */
 115         bool DebugE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 116
 117         /** \brief add an fatal error message to the list
 118          *
 119          *  Most of the stuff we consider as "error" is also "fatal" for
 120          *  the user as the application will not have the expected result,
 121          *  but a fatal message here means that it gets printed directly
 122          *  to stderr in addiction to adding it to the list as the error
 123          *  leads sometimes to crashes and a maybe duplicated message
 124          *  is better than "Segfault" as the only displayed text
 125          *
 126          *  \param Description Format string for the fatal error message.
 127          *
 128          *  \return \b false
 129          */
 130         bool Fatal(const char *Description,...) __like_printf(2) __cold;
 131
 132         /** \brief add an Error message to the list
 133          *
 134          *  \param Description Format string for the error message.
 135          *
 136          *  \return \b false
 137          */
 138         bool Error(const char *Description,...) __like_printf(2) __cold;
 139
 140         /** \brief add a warning message to the list
 141          *
 142          *  A warning should be considered less severe than an error and
 143          *  may be ignored by the client.
 144          *
 145          *  \param Description Format string for the message
 146          *
 147          *  \return \b false
 148          */
 149         bool Warning(const char *Description,...) __like_printf(2) __cold;
 150
 151         /** \brief add a notice message to the list
 152          *
 153          *  A notice should be considered less severe than an error or a
 154          *  warning and can be ignored by the client without further problems
 155          *  for some times, but he should consider fixing the problem.
 156          *  This error type can be used for e.g. deprecation warnings of options.
 157          *
 158          *  \param Description Format string for the message
 159          *
 160          *  \return \b false
 161          */
 162         bool Notice(const char *Description,...) __like_printf(2) __cold;
 163
 164         /** \brief add a debug message to the list
 165          *
 166          *  \param Description Format string for the message
 167          *
 168          *  \return \b false
 169          */
 170         bool Debug(const char *Description,...) __like_printf(2) __cold;
 171
 172         /** \brief is an error in the list?
 173          *
 174          *  \return \b true if an error is included in the list, \b false otherwise
 175          */
 176         inline bool PendingError() const {return PendingFlag;};
 177
 178         /** \brief is the list empty?
 179          *
 180          *  The default checks if the list is empty or contains only notices,
 181          *  if you want to check if also no notices happend set the parameter
 182          *  flag to \b false.
 183          *
 184          *  \param WithoutNotice does notices count, default is \b true, so no
 185          *
 186          *  \return \b true if an the list is empty, \b false otherwise
 187          */
 188         bool empty(MsgType const &trashhold = WARNING) const;
 189
 190         /** \brief returns and removes the first (or last) message in the list
 191          *
 192          *  \param[out] Text message of the first/last item
 193          *
 194          *  \return \b true if the message was an error, \b false otherwise
 195          */
 196         bool PopMessage(std::string &Text);
 197
 198         /** \brief clears the list of messages */
 199         void Discard();
 200
 201         /** \brief outputs the list of messages to the given stream
 202          *
 203          *  Note that all messages are discarded, also the notices
 204          *  displayed or not.
 205          *
 206          *  \param[out] out output stream to write the messages in
 207          *  \param threshold minimim level considered
 208          *  \param mergeStack
 209          */
 210         void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
 211                         bool const &mergeStack = true);
 212
 213         /** \brief dumps the list of messages to std::cerr
 214          *
 215          *  Note that all messages are discarded, also the notices
 216          *  displayed or not.
 217          *
 218          *  \param threshold minimum level printed
 219          */
 220         void inline DumpErrors(MsgType const &threshold = WARNING) {
 221                 DumpErrors(std::cerr, threshold);
 222         }
 223
 224         /** \brief put the current Messages into the stack
 225          *
 226          *  All "old" messages will be pushed into a stack to
 227          *  them later back, but for now the Message query will be
 228          *  empty and performs as no messages were present before.
 229          *
 230          * The stack can be as deep as you want - all stack operations
 231          * will only operate on the last element in the stack.
 232          */
 233         void PushToStack();
 234
 235         /** \brief throw away all current messages */
 236         void RevertToStack();
 237
 238         /** \brief merge current and stack together */
 239         void MergeWithStack();
 240
 241         /** \brief return the deep of the stack */
 242         size_t StackCount() const {
 243                 return Stacks.size();
 244         }
 245
 246         GlobalError();
 247                                                                         /*}}}*/
 248 private:                                                                /*{{{*/
 249         struct Item {
 250                 std::string Text;
 251                 MsgType Type;
 252
 253                 Item(char const *Text, MsgType const &Type) :
 254                         Text(Text), Type(Type) {};
 255
 256                 friend std::ostream& operator<< (std::ostream &out, Item i) {
 257                         switch(i.Type) {
 258                         case FATAL:
 259                         case ERROR: out << "E"; break;
 260                         case WARNING: out << "W"; break;
 261                         case NOTICE: out << "N"; break;
 262                         case DEBUG: out << "D"; break;
 263                         }
 264                         return out << ": " << i.Text;
 265                 }
 266         };
 267
 268         std::list<Item> Messages;
 269         bool PendingFlag;
 270
 271         struct MsgStack {
 272                 std::list<Item> const Messages;
 273                 bool const PendingFlag;
 274
 275                 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
 276                          Messages(Messages), PendingFlag(Pending) {};
 277         };
 278
 279         std::list<MsgStack> Stacks;
 280
 281         bool InsertErrno(MsgType type, const char* Function,
 282                          const char* Description, va_list &args);
 283         bool Insert(MsgType type, const char* Description,
 284                          va_list &args);
 285                                                                         /*}}}*/
 286 };
 287                                                                         /*}}}*/
 288
 289 // The 'extra-ansi' syntax is used to help with collisions.
 290 GlobalError *_GetErrorObj();
 291 #define _error _GetErrorObj()
 292
 293 #endif