libzypp  17.32.5
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. More...
 
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. More...
 
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. More...
 
void gap ()
 NORMAL: An empty line. More...
 
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. More...
 
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 ' '. More...
 
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: '. More...
 
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: '. More...
 
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: '. More...
 
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. More...
 
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 More...
 
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. More...
 
void infoLRHint (const std::string &lmsg, const std::string &hint, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)
 Info message with R-adjusted "(hint)". More...
 
virtual void warning (const std::string &msg, Verbosity verbosity=NORMAL, Type mask=TYPE_ALL)=0
 Show a warning. More...
 
virtual void error (const std::string &problem_desc, const std::string &hint="")=0
 Show an error message and an optional hint. More...
 
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. More...
 
virtual void searchResult (const Table &table_r)
 Print out a search result. More...
 
virtual void prompt (PromptId id, const std::string &prompt, const PromptOptions &poptions, const std::string &startdesc="")=0
 Prompt the user for a decision. More...
 
virtual void promptHelp (const PromptOptions &poptions)=0
 Print help for prompt, if available. More...
 
Verbosity verbosity () const
 Get current verbosity. More...
 
void setVerbosity (Verbosity verbosity)
 Set current verbosity. More...
 
zypp::DtorReset scopedVerbosity (Verbosity verbosity_r)
 Return RAII class for exception safe scoped verbosity change. More...
 
virtual void setUseColors (bool yesno)
 Hint for a handler whether config would allow to use colors. More...
 
TypeBit type () const
 Return the type of the instance. More...
 
bool type (TypeBit type_r) const
 Test for a specific type. More...
 
bool typeNORMAL () const
 
bool typeXML () const
 
unsigned defaultFormatWidth (unsigned desired_r=0) const
 Terminal width or 150 if unlimited. More...
 
virtual unsigned termwidth () const
 Width for formatted output [0==unlimited]. More...
 
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. More...
 
virtual void progress (const std::string &id, const std::string &label, int value=-1)=0
 Progress report for an on-going operation. More...
 
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. More...
 
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)
 
Download progress with download rate
virtual void dwnldProgressStart (const zypp::Url &uri)=0
 Reoprt start of a download. More...
 
virtual void dwnldProgress (const zypp::Url &uri, int value=-1, long rate=-1)=0
 Reports download progress. More...
 
virtual void dwnldProgressEnd (const zypp::Url &uri, long rate=-1, zypp::TriBool error=false)=0
 Reports end of a download. More...
 

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)
 
virtual bool mine (Type type)=0
 Determine whether the output is intended for the particular type. More...
 
virtual bool progressFilter ()
 Determine whether to show progress. More...
 
virtual std::string zyppExceptionReport (const zypp::Exception &e)
 Return a Exception as a string suitable for output. More...
 

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. More...
 

Private Attributes

Verbosity _verbosity
 
const TypeBit _type
 

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 429 of file Out.h.

Member Typedef Documentation

◆ PromptId

using ztui::Out::PromptId = unsigned

Definition at line 453 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 433 of file Out.h.

◆ TypeBit

Known output types implemented by derived classes.

Enumerator
TYPE_NORMAL 

plain text output

TYPE_XML 

xml output

Definition at line 443 of file Out.h.

Constructor & Destructor Documentation

◆ Out()

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

Definition at line 456 of file Out.h.

◆ ~Out()

ztui::Out::~Out ( )
virtual

Definition at line 109 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 515 of file Out.h.

◆ xmlNode() [2/2]

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

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

Definition at line 518 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 535 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 555 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 562 of file Out.h.

◆ gap()

void ztui::Out::gap ( )
inline

NORMAL: An empty line.

Definition at line 568 of file Out.h.

◆ printRichText()

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

Definition at line 570 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 580 of file Out.h.

◆ par() [2/2]

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

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

Definition at line 589 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 595 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

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

Definition at line 599 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 605 of file Out.h.

◆ notePar() [2/2]

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

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

Definition at line 609 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 614 of file Out.h.

◆ warningPar() [2/2]

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

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

Definition at line 618 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 623 of file Out.h.

◆ errorPar() [2/2]

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

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

Definition at line 627 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

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

Definition at line 646 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 650 of file Out.h.

◆ info() [3/3]

Info ztui::Out::info ( )
inline

Definition at line 684 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 688 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 697 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 
)

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

Definition at line 127 of file Out.cc.

◆ progressEnd() [3/3]

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

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

Definition at line 798 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 122 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 870 of file Out.h.

◆ setVerbosity()

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

Set current verbosity.

Definition at line 873 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 890 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 897 of file Out.h.

◆ type() [1/2]

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

Return the type of the instance.

Definition at line 901 of file Out.h.

◆ type() [2/2]

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

Test for a specific type.

Definition at line 904 of file Out.h.

◆ typeNORMAL()

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

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

Definition at line 906 of file Out.h.

◆ typeXML()

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

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

Definition at line 908 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 914 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 925 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 112 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 117 of file Out.cc.

Member Data Documentation

◆ TYPE_NONE

constexpr Out::Type ztui::Out::TYPE_NONE = Type(0x00)
static

Definition at line 450 of file Out.h.

◆ TYPE_ALL

constexpr Out::Type ztui::Out::TYPE_ALL = Type(0xff)
static

Definition at line 451 of file Out.h.

◆ _verbosity

Verbosity ztui::Out::_verbosity
private

Definition at line 948 of file Out.h.

◆ _type

const TypeBit ztui::Out::_type
private

Definition at line 949 of file Out.h.


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