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) {
 221                 DumpErrors(std::cerr, threshold);
 222         }
 223
 224         // mvo: we do this instead of using a default parameter in the
 225         //      previous declaration to avoid a (subtle) API break for
 226         //      e.g. sigc++ and mem_fun0
 227         /** \brief dumps the messages of type WARNING or higher to std::cerr
 228          *
 229          *  Note that all messages are discarded, displayed or not.
 230          *
 231          */
 232         void inline DumpErrors() {
 233                 DumpErrors(WARNING);
 234         }
 235
 236         /** \brief put the current Messages into the stack
 237          *
 238          *  All "old" messages will be pushed into a stack to
 239          *  them later back, but for now the Message query will be
 240          *  empty and performs as no messages were present before.
 241          *
 242          * The stack can be as deep as you want - all stack operations
 243          * will only operate on the last element in the stack.
 244          */
 245         void PushToStack();
 246
 247         /** \brief throw away all current messages */
 248         void RevertToStack();
 249
 250         /** \brief merge current and stack together */
 251         void MergeWithStack();
 252
 253         /** \brief return the deep of the stack */
 254         size_t StackCount() const {
 255                 return Stacks.size();
 256         }
 257
 258         GlobalError();
 259                                                                         /*}}}*/
 260 private:                                                                /*{{{*/
 261         struct Item {
 262                 std::string Text;
 263                 MsgType Type;
 264
 265                 Item(char const *Text, MsgType const &Type) :
 266                         Text(Text), Type(Type) {};
 267
 268                 friend std::ostream& operator<< (std::ostream &out, Item i) {
 269                         switch(i.Type) {
 270                         case FATAL:
 271                         case ERROR: out << "E"; break;
 272                         case WARNING: out << "W"; break;
 273                         case NOTICE: out << "N"; break;
 274                         case DEBUG: out << "D"; break;
 275                         }
 276                         return out << ": " << i.Text;
 277                 }
 278         };
 279
 280         std::list<Item> Messages;
 281         bool PendingFlag;
 282
 283         struct MsgStack {
 284                 std::list<Item> const Messages;
 285                 bool const PendingFlag;
 286
 287                 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
 288                          Messages(Messages), PendingFlag(Pending) {};
 289         };
 290
 291         std::list<MsgStack> Stacks;
 292
 293         bool InsertErrno(MsgType type, const char* Function,
 294                          const char* Description, va_list &args);
 295         bool Insert(MsgType type, const char* Description,
 296                          va_list &args);
 297                                                                         /*}}}*/
 298 };
 299                                                                         /*}}}*/
 300
 301 // The 'extra-ansi' syntax is used to help with collisions.
 302 GlobalError *_GetErrorObj();
 303 #define _error _GetErrorObj()
 304
 305 #endif