libzypp 17.37.17
ztui::Out Class Referenceabstract

Base class for producing common (for now) zypper output. More...

#include <zypp-tui/output/Out.h>

Inheritance diagram for ztui::Out:

Classes

class  Error
 Convenience class Error reporting. More...
struct  Info
class  ParentOut
 Convenience base class storing the back reference to Out. More...
struct  ParFormat
 Less common Paragraph formats. More...
class  ProgressBar
 Convenience class for progress output. More...
class  TitleNode
 XmlNode with optional normal text headline (NL appended) More...
class  XmlNode
 XML only: RAII writing a XML nodes start/end tag. More...

Public Types

enum  Verbosity { QUIET = 0 , NORMAL = 1 , HIGH = 2 , DEBUG = 3 }
 Verbosity levels. More...
enum  TypeBit { TYPE_NORMAL = 0x01<<0 , TYPE_XML = 0x01<<1 }
 Known output types implemented by derived classes. More...
using PromptId = unsigned

Public Member Functions

 ZYPP_DECLARE_FLAGS (Type, TypeBit)
virtual ~Out ()
void xmlNode (const std::string &name_r, const std::initializer_list< XmlNode::Attr > &attrs_r={})
 XML only: Write a leaf node without PCDATA.
void xmlNode (const std::string &name_r, XmlNode::Attr attr_r)
template<class TContainer, class TFormater = out::ListFormater>
void list (const std::string &nodeName_r, const std::string &title_r, const TContainer &container_r, const TFormater &formater_r=TFormater())
 Write list from container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.
template<class TContainer, class TFormater = out::TableFormater>
void table (const std::string &nodeName_r, const std::string &title_r, const TContainer &container_r, const TFormater &formater_r=TFormater())
 Write table from container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.
void gap ()
 NORMAL: An empty line.
void printRichText (std::string text, unsigned indent_r=0U)
template<class Text>
void par (size_t indent_r, const Text &text_r, ParFormat format_r=ParFormat())
 Paragraph of text, optionally indented, or without leading gap.
template<class Text>
void par (const Text &text_r, ParFormat format_r=ParFormat())
template<class TText, class Text>
void taggedPar (size_t indent_r, const TText &tag_r, const Text &text_r, ParFormat format_r=ParFormat())
 Paragraph of text preceded by 'tag_r' and a ' '.
template<class TText, class Text>
void taggedPar (const TText &tag_r, const Text &text_r, ParFormat format_r=ParFormat())
template<class Text>
void notePar (size_t indent_r, const Text &text_r, ParFormat format_r=ParFormat())
 Paragraph tagged with 'Note: '.
template<class Text>
void notePar (const Text &text_r, ParFormat format_r=ParFormat())
template<class Text>
void warningPar (size_t indent_r, const Text &text_r, ParFormat format_r=ParFormat())
 Paragraph tagged with 'Warning: '.
template<class Text>
void warningPar (const Text &text_r, ParFormat format_r=ParFormat())
template<class Text>
void errorPar (size_t indent_r, const Text &text_r, ParFormat format_r=ParFormat())
 Paragraph tagged with 'Error: '.
template<class Text>
void errorPar (const Text &text_r, ParFormat format_r=ParFormat())
virtual void info (const std::string &msg, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)=0
 Show an info message.
void info (std::string msg, const std::string &msg2, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)
virtual void infoLine (const TermLine &msg_r, Verbosity verbosity_r=NORMAL, Type mask_r=TYPE_ALL)
 info taking a TermLine
Info info ()
void infoLR (const std::string &lmsg, const std::string &rmsg, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)
 Info message, 2 strings L/R-adjusted.
void infoLRHint (const std::string &lmsg, const std::string &hint, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)
 Info message with R-adjusted "(hint)".
virtual void warning (const std::string &msg, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)=0
 Show a warning.
virtual void error (const std::string &problem_desc, const std::string &hint="")=0
 Show an error message and an optional hint.
virtual void error (const zypp::Exception &e, const std::string &problem_desc, const std::string &hint="")=0
 Prints the problem description caused by an exception, its cause and, optionally, a hint for the user.
Progress of an operation.
Todo
provide an error() method with a/r/i prompt, more read_action_ari here
virtual void progressStart (const std::string &id, const std::string &label, bool is_tick=false)=0
 Start of an operation with reported progress.
virtual void progress (const std::string &id, const std::string &label, int value=-1)=0
 Progress report for an on-going operation.
virtual void progressEnd (const std::string &id, const std::string &label, const std::string &donetag, bool error=false)=0
 End of an operation with reported progress.
void progressEnd (const std::string &id, const std::string &label, ProgressEnd donetag)
void progressEnd (const std::string &id, const std::string &label, bool error=false)

Static Public Attributes

static constexpr Type TYPE_NONE = Type(0x00)
static constexpr Type TYPE_ALL = Type(0xff)

Protected Member Functions

 Out (TypeBit type, Verbosity verbosity=NORMAL)

Private Member Functions

template<class TContainer, class TFormater>
void container (const std::string &nodeName_r, const std::string &title_r, const TContainer &container_r, const TFormater &formater_r)
 Write container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.

Download progress with download rate

Verbosity _verbosity
const TypeBit _type
virtual void dwnldProgressStart (const zypp::Url &uri)=0
 Reoprt start of a download.
virtual void dwnldProgress (const zypp::Url &uri, int value=-1, long rate=-1)=0
 Reports download progress.
virtual void dwnldProgressEnd (const zypp::Url &uri, long rate=-1, zypp::TriBool error=false)=0
 Reports end of a download.
virtual void searchResult (const Table &table_r)
 Print out a search result.
virtual void prompt (PromptId id, const std::string &prompt, const PromptOptions &poptions, const std::string &startdesc="")=0
 Prompt the user for a decision.
virtual void promptHelp (const PromptOptions &poptions)=0
 Print help for prompt, if available.
Verbosity verbosity () const
 Get current verbosity.
void setVerbosity (Verbosity verbosity)
 Set current verbosity.
zypp::DtorReset scopedVerbosity (Verbosity verbosity_r)
 Return RAII class for exception safe scoped verbosity change.
virtual void setUseColors (bool yesno)
 Hint for a handler whether config would allow to use colors.
TypeBit type () const
 Return the type of the instance.
bool type (TypeBit type_r) const
 Test for a specific type.
bool typeNORMAL () const
bool typeXML () const
unsigned defaultFormatWidth (unsigned desired_r=0) const
 Terminal width or 150 if unlimited.
virtual unsigned termwidth () const
 Width for formatted output [0==unlimited].
virtual bool mine (Type type)=0
 Determine whether the output is intended for the particular type.
virtual bool progressFilter ()
 Determine whether to show progress.
virtual std::string zyppExceptionReport (const zypp::Exception &e)
 Return a Exception as a string suitable for output.

Detailed Description

Base class for producing common (for now) zypper output.

This is an abstract class providing interface for writing output like info messages, warnings, error messages, user prompts, progress reports, and download progress reports. See descriptions of the methods for more details.

The output is produced using Out derived class instances.

// create output object SomePointerType<Out> out; if (options.count("xmlout")) out = new OutXML(); else out = new OutNormal();

out->info("output instance ready to use", Out::HIGH); out->info("Doing foo"); try { foo(); out->prompt(PROMPT_FOO, "Need your action?", "y/n"); // see output/prompt.h if (action()) out->info("result", Out::QUIET); // always show the result else cout << "special result" << endl; // special output must be done // the usual way for now } catch(const Exception & e) { out->error(e, "Problem doing foo", "Do 'bar' to deal with this"); }

Definition at line 423 of file Out.h.

Member Typedef Documentation

◆ PromptId

using ztui::Out::PromptId = unsigned

Definition at line 447 of file Out.h.

Member Enumeration Documentation

◆ Verbosity

Verbosity levels.

Enumerator
QUIET 

Only important messages (no progress or status, only the result).

NORMAL 

Default output verbosity level.

Progress for important tasks, moderate amount of status messages, operation information, result.

HIGH 

More detailed description of the operations.

DEBUG 
Todo
drop this level in favor of zypper.log?

Definition at line 427 of file Out.h.

◆ TypeBit

Known output types implemented by derived classes.

Enumerator
TYPE_NORMAL 

plain text output

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

TYPE_XML 

xml output

Definition at line 437 of file Out.h.

Constructor & Destructor Documentation

◆ Out()

ztui::Out::Out ( TypeBit type,
Verbosity verbosity = NORMAL )
inlineprotected

Definition at line 450 of file Out.h.

◆ ~Out()

ztui::Out::~Out ( )
virtual

Definition at line 120 of file Out.cc.

Member Function Documentation

◆ ZYPP_DECLARE_FLAGS()

ztui::Out::ZYPP_DECLARE_FLAGS ( Type ,
TypeBit  )

◆ xmlNode() [1/2]

void ztui::Out::xmlNode ( const std::string & name_r,
const std::initializer_list< XmlNode::Attr > & attrs_r = {} )
inline

XML only: Write a leaf node without PCDATA.

<node attr="val"/>

Definition at line 509 of file Out.h.

◆ xmlNode() [2/2]

void ztui::Out::xmlNode ( const std::string & name_r,
XmlNode::Attr attr_r )
inline

Definition at line 512 of file Out.h.

◆ container()

template<class TContainer, class TFormater>
void ztui::Out::container ( const std::string & nodeName_r,
const std::string & title_r,
const TContainer & container_r,
const TFormater & formater_r )
inlineprivate

Write container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.

Definition at line 529 of file Out.h.

◆ list()

template<class TContainer, class TFormater = out::ListFormater>
void ztui::Out::list ( const std::string & nodeName_r,
const std::string & title_r,
const TContainer & container_r,
const TFormater & formater_r = TFormater() )
inline

Write list from container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.

Definition at line 549 of file Out.h.

◆ table()

template<class TContainer, class TFormater = out::TableFormater>
void ztui::Out::table ( const std::string & nodeName_r,
const std::string & title_r,
const TContainer & container_r,
const TFormater & formater_r = TFormater() )
inline

Write table from container creating a TitleNode with size="nnn" attribute and replacing optional %1% in title_r with size.

Definition at line 556 of file Out.h.

◆ gap()

void ztui::Out::gap ( )
inline

NORMAL: An empty line.

Definition at line 562 of file Out.h.

◆ printRichText()

void ztui::Out::printRichText ( std::string text,
unsigned indent_r = 0U )
inline

Definition at line 564 of file Out.h.

◆ par() [1/2]

template<class Text>
void ztui::Out::par ( size_t indent_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Paragraph of text, optionally indented, or without leading gap.

Definition at line 574 of file Out.h.

◆ par() [2/2]

template<class Text>
void ztui::Out::par ( const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Definition at line 583 of file Out.h.

◆ taggedPar() [1/2]

template<class TText, class Text>
void ztui::Out::taggedPar ( size_t indent_r,
const TText & tag_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Paragraph of text preceded by 'tag_r' and a ' '.

Definition at line 589 of file Out.h.

◆ taggedPar() [2/2]

template<class TText, class Text>
void ztui::Out::taggedPar ( const TText & tag_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Definition at line 593 of file Out.h.

◆ notePar() [1/2]

template<class Text>
void ztui::Out::notePar ( size_t indent_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Paragraph tagged with 'Note: '.

Definition at line 599 of file Out.h.

◆ notePar() [2/2]

template<class Text>
void ztui::Out::notePar ( const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Definition at line 603 of file Out.h.

◆ warningPar() [1/2]

template<class Text>
void ztui::Out::warningPar ( size_t indent_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Paragraph tagged with 'Warning: '.

Definition at line 608 of file Out.h.

◆ warningPar() [2/2]

template<class Text>
void ztui::Out::warningPar ( const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Definition at line 612 of file Out.h.

◆ errorPar() [1/2]

template<class Text>
void ztui::Out::errorPar ( size_t indent_r,
const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Paragraph tagged with 'Error: '.

Definition at line 617 of file Out.h.

◆ errorPar() [2/2]

template<class Text>
void ztui::Out::errorPar ( const Text & text_r,
ParFormat format_r = ParFormat() )
inline

Definition at line 621 of file Out.h.

◆ info() [1/3]

virtual void ztui::Out::info ( const std::string & msg,
Verbosity verbosity = NORMAL,
Type mask = TYPE_ALL )
pure virtual

Show an info message.

Parameters
msgThe message to be displayed.
verbosityMinimal level o verbosity in which the message will be shown. Out::QUIET means the message will be always be displayed. Out::HIGH means the message will be displayed only if the current verbosity level is HIGH (-v) or DEBUG (-vv).
maskDetermines the types of output for which is this message intended. By default, the message will be shown in all types of output.

Implemented in ztui::OutNormal.

◆ info() [2/3]

void ztui::Out::info ( std::string msg,
const std::string & msg2,
Verbosity verbosity = NORMAL,
Type mask = TYPE_ALL )
inline

Definition at line 640 of file Out.h.

◆ infoLine()

virtual void ztui::Out::infoLine ( const TermLine & msg_r,
Verbosity verbosity_r = NORMAL,
Type mask_r = TYPE_ALL )
inlinevirtual

info taking a TermLine

Reimplemented in ztui::OutNormal.

Definition at line 644 of file Out.h.

◆ info() [3/3]

Info ztui::Out::info ( )
inline

Definition at line 678 of file Out.h.

◆ infoLR()

void ztui::Out::infoLR ( const std::string & lmsg,
const std::string & rmsg,
Verbosity verbosity = NORMAL,
Type mask = TYPE_ALL )
inline

Info message, 2 strings L/R-adjusted.

Definition at line 682 of file Out.h.

◆ infoLRHint()

void ztui::Out::infoLRHint ( const std::string & lmsg,
const std::string & hint,
Verbosity verbosity = NORMAL,
Type mask = TYPE_ALL )
inline

Info message with R-adjusted "(hint)".

Definition at line 691 of file Out.h.

◆ warning()

virtual void ztui::Out::warning ( const std::string & msg,
Verbosity verbosity = NORMAL,
Type mask = TYPE_ALL )
pure virtual

Show a warning.

Parameters
msgThe warning message to be displayed.
verbosityMinimal level o verbosity in which the message will be shown. Out::QUIET means the message will be always be displayed. Out::HIGH means the message will be displayed only if the current verbosity level is HIGH (-v) or DEBUG (-vv).
maskDetermines the types of output for which is this message intended. By default, the message will be shown in all types of output.

Implemented in ztui::OutNormal.

◆ error() [1/2]

virtual void ztui::Out::error ( const std::string & problem_desc,
const std::string & hint = "" )
pure virtual

Show an error message and an optional hint.

An error message should be shown regardless of the verbosity level.

Parameters
problem_descProblem description (what happened)
hintHint for the user (what to do, or explanation)

Implemented in ztui::OutNormal.

◆ error() [2/2]

virtual void ztui::Out::error ( const zypp::Exception & e,
const std::string & problem_desc,
const std::string & hint = "" )
pure virtual

Prints the problem description caused by an exception, its cause and, optionally, a hint for the user.

Parameters
eException which caused the problem.
Problemdescription for the user.
Hintfor the user how to cope with the problem.

Implemented in ztui::OutNormal.

◆ progressStart()

virtual void ztui::Out::progressStart ( const std::string & id,
const std::string & label,
bool is_tick = false )
pure virtual

Start of an operation with reported progress.

Parameters
idIdentifier. Any string used to match multiple overlapping progress reports (doesn't happen now, but probably will in the future).
labelProgress description.
is_tickfalse for known progress percentage, true for 'still alive' notifications

Implemented in ztui::OutNormal.

◆ progress()

virtual void ztui::Out::progress ( const std::string & id,
const std::string & label,
int value = -1 )
pure virtual

Progress report for an on-going operation.

Parameters
idIdentifier. Any string used to match multiple overlapping progress reports.
labelProgress description.
valuePercentage value or -1 if unknown ('still alive' notification)

Implemented in ztui::OutNormal.

◆ progressEnd() [1/3]

virtual void ztui::Out::progressEnd ( const std::string & id,
const std::string & label,
const std::string & donetag,
bool error = false )
pure virtual

End of an operation with reported progress.

Parameters
idIdentifier. Any string used to match multiple overlapping progress reports.
labelProgress description.
donetagOptional string overwriting the default [done]/[error] tags.
errorfalse if the operation finished with success, true otherwise.

Implemented in ztui::OutNormal.

◆ progressEnd() [2/3]

void ztui::Out::progressEnd ( const std::string & id,
const std::string & label,
ProgressEnd donetag )

Definition at line 138 of file Out.cc.

◆ progressEnd() [3/3]

void ztui::Out::progressEnd ( const std::string & id,
const std::string & label,
bool error = false )
inline

Definition at line 792 of file Out.h.

◆ dwnldProgressStart()

virtual void ztui::Out::dwnldProgressStart ( const zypp::Url & uri)
pure virtual

Reoprt start of a download.

Parameters
uriUri of the file to download.

Implemented in ztui::OutNormal.

◆ dwnldProgress()

virtual void ztui::Out::dwnldProgress ( const zypp::Url & uri,
int value = -1,
long rate = -1 )
pure virtual

Reports download progress.

Parameters
uriUri of the file being downloaded.
valueValue of the progress in percents. -1 if unknown.
rateCurrent download rate in B/s. -1 if unknown.

Implemented in ztui::OutNormal.

◆ dwnldProgressEnd()

virtual void ztui::Out::dwnldProgressEnd ( const zypp::Url & uri,
long rate = -1,
zypp::TriBool error = false )
pure virtual

Reports end of a download.

Parameters
uriUri of the file to download.
rateAverage download rate at the end. -1 if unknown.
errorError flag - did the download finish with error? indeterminate == 'not found'

Implemented in ztui::OutNormal.

◆ searchResult()

void ztui::Out::searchResult ( const Table & table_r)
virtual

Print out a search result.

Default implementation prints table_r on stdout.

Parameters
table_rTable containing the search result.
Todo
Using a more generic format than a Table is desired.

Definition at line 133 of file Out.cc.

◆ prompt()

virtual void ztui::Out::prompt ( PromptId id,
const std::string & prompt,
const PromptOptions & poptions,
const std::string & startdesc = "" )
pure virtual

Prompt the user for a decision.

Parameters
idUnique prompt identifier for use by machines.
promptPrompt text.
optionsA PromptOptions object
startdescInitial detailed description of the prompt to be prepended to the prompt text. Should be used only whe prompting for the first time and left empty when retrying after an invalid answer has been given.
See also
prompt.h
../zypper-prompt.h

Implemented in ztui::OutNormal.

◆ promptHelp()

virtual void ztui::Out::promptHelp ( const PromptOptions & poptions)
pure virtual

Print help for prompt, if available.

This method should be called after '?' prompt option has been entered.

Implemented in ztui::OutNormal.

◆ verbosity()

Verbosity ztui::Out::verbosity ( ) const
inline

Get current verbosity.

Definition at line 864 of file Out.h.

◆ setVerbosity()

void ztui::Out::setVerbosity ( Verbosity verbosity)
inline

Set current verbosity.

Definition at line 867 of file Out.h.

◆ scopedVerbosity()

zypp::DtorReset ztui::Out::scopedVerbosity ( Verbosity verbosity_r)
inline

Return RAII class for exception safe scoped verbosity change.

Definition at line 884 of file Out.h.

◆ setUseColors()

virtual void ztui::Out::setUseColors ( bool yesno)
inlinevirtual

Hint for a handler whether config would allow to use colors.

Reimplemented in ztui::OutNormal.

Definition at line 891 of file Out.h.

◆ type() [1/2]

TypeBit ztui::Out::type ( ) const
inline

Return the type of the instance.

Definition at line 895 of file Out.h.

◆ type() [2/2]

bool ztui::Out::type ( TypeBit type_r) const
inline

Test for a specific type.

Definition at line 898 of file Out.h.

◆ typeNORMAL()

bool ztui::Out::typeNORMAL ( ) const
inline

Definition at line 900 of file Out.h.

◆ typeXML()

bool ztui::Out::typeXML ( ) const
inline

Definition at line 902 of file Out.h.

◆ defaultFormatWidth()

unsigned ztui::Out::defaultFormatWidth ( unsigned desired_r = 0) const
inline

Terminal width or 150 if unlimited.

If a desired_r value is given, return the closest width that fits the terminal.

Definition at line 908 of file Out.h.

◆ termwidth()

virtual unsigned ztui::Out::termwidth ( ) const
inlinevirtual

Width for formatted output [0==unlimited].

Reimplemented in ztui::OutNormal.

Definition at line 919 of file Out.h.

◆ mine()

virtual bool ztui::Out::mine ( Type type)
protectedpure virtual

Determine whether the output is intended for the particular type.

Implemented in ztui::OutNormal.

◆ progressFilter()

bool ztui::Out::progressFilter ( )
protectedvirtual

Determine whether to show progress.

Returns
true if the progress should be filtered out, false if it should be shown.

Definition at line 123 of file Out.cc.

◆ zyppExceptionReport()

std::string ztui::Out::zyppExceptionReport ( const zypp::Exception & e)
protectedvirtual

Return a Exception as a string suitable for output.

Definition at line 128 of file Out.cc.

Member Data Documentation

◆ TYPE_NONE

Out::Type ztui::Out::TYPE_NONE = Type(0x00)
staticconstexpr

Definition at line 444 of file Out.h.

◆ TYPE_ALL

Out::Type ztui::Out::TYPE_ALL = Type(0xff)
staticconstexpr

Definition at line 445 of file Out.h.

◆ _verbosity

Verbosity ztui::Out::_verbosity
private

Definition at line 942 of file Out.h.

◆ _type

const TypeBit ztui::Out::_type
private

Definition at line 943 of file Out.h.


The documentation for this class was generated from the following files: