classwork.pp

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class ALog

DescriptionHierarchyFieldsMethodsProperties

Unit

classwork

Declaration

type ALog = class(APrintingObject)

Description

This class represents a generic log, which can be used to output status and error messages to an assigned stream. Any type of information can be logged to ALog by means of ALog.print; however, when the item to be logged is an instance of ALoggedItem or its descendants, then the logging of that instance will be recorded in the list of counters maintained by the log.

Hierarchy

Overview

Fields

Protected MyCounters: ACounterList;
Protected MyOutput: ATextOutputStream;
Protected myOwnOutput: boolean;

Methods

Public constructor toStream(const Dest: ATextOutputStream; const ownStream: boolean = false); virtual;
Public function init: boolean; override;
Public destructor destroy; override;
Public function Log(const ThisItem: ALoggedItem; const freeAfterwards: boolean = true): ALoggedItem; virtual;
Public function print(const items: array of const): TStreamIOSize; virtual;
Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; override;
Public function Counter(const thisName: string): ACounter; virtual;
Public function Counters: ACounterList; virtual;
Public function Output: ATextOutputStream; virtual;
Public function ownsOutput: boolean; virtual;
Public function setOwnsOutput(const flag: boolean): boolean; virtual;

Description

Fields

Protected MyCounters: ACounterList;

Stores counters for errors, hints, warnings, etc.

Protected MyOutput: ATextOutputStream;

Refers to the stream used for output from the log

Protected myOwnOutput: boolean;

Indicates whether the log owns its output stream, and whether it will free this stream when the log itself is destroyed.

Methods

Public constructor toStream(const Dest: ATextOutputStream; const ownStream: boolean = false); virtual;

Construct a new instance of ALog that will output status messages and errors to the given stream.

If ownStream is True, then the log will assume ownership of Dest and will free it when it is, itself, freed. This allows instances of a log to be constructed and assigned to a stream like so: 

        // Log to 'stdout'
        MyLog := ALog.toStream(AConsoleOutputStream.new, true);

Public function init: boolean; override;

Initializer

Public destructor destroy; override;

Frees the log and all resources associated with it.

If ALog.ownsOutput is True, then this routine will ensure that ALog.Output is freed as well. This is useful behavior when it is desirable to construct a log and assign it to a stream of its own in a single statement, as follows: 

        // Log to 'stdout'
        MyLog := ALog.toStream(AStandardOutputStream.new, true);

Public function Log(const ThisItem: ALoggedItem; const freeAfterwards: boolean = true): ALoggedItem; virtual;

Log an item to the log.

This method is defined for convenience. It simply calls Self.print with ThisItem.

If freeAfterwards is True, then ThisItem is freed after it has been logged; this behavior allows you to construct an instance of ALoggedItem on the fly as part of the call to this method.

Returns

If freeAfterwards is False, this method will return ThisItem. Otherwise, it returns Nil.

Public function print(const items: array of const): TStreamIOSize; virtual;

Write one or more items to the log.

This function accepts all types of values. Integer and floating-point values are converted to strings before being written to the log's output stream. Object instances are checked to see if they implement CanPrint; if so, their printTo method is called and directed to output to the log's output stream.

If an instance of ALoggedItem or its descendants is passed to this method, then the counter associated with that instance (as determined by a call to ALoggedItem.counterName) is incremented. If the counter does not yet exist in ALog.Counters, then it is created.

Internally, after checking to see if there are items in items that are instances of ALoggedItem and incrementing the counters associated with any found, this method calls ATextOutputStream.printEach on its output stream.

Returns

The total number of bytes written to the log's output stream.

Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; override;

Print a string representation of the log to the specified stream.

This method does not actually print a string representation of the log itself; rather, it calls ACounterList.printTo on its list of counters. prefix and suffix are passed to that routine and are not used by this one. This behavior ensures that a summary of all logged items is printed every time this method is called.

Returns

The total number of bytes printed to Dest.

Public function Counter(const thisName: string): ACounter; virtual;

Retrieve a reference to the counter with the specified name. The caller should NOT free this reference; the log will free it when it is, itself, freed.

If the counter does not exist in the log's list of counted items, then this routine will return Nil.

Public function Counters: ACounterList; virtual;

Retrieve a reference to the list of all counted items maintained by the log. This reference should NOT be freed by the caller; it will be freed by the log when the log is, itself, freed.

Public function Output: ATextOutputStream; virtual;

Retrieve a reference to the output stream used by the log to print status messages and errors.

The reference returned by this routine should NOT be freed by the caller. If ALog.ownsOutput is True, then the stream will be freed when the log is, itself, freed.

Public function ownsOutput: boolean; virtual;

Retrieve whether or not the log assumes ownership of its output stream.

If this method returns True, it indicates that the log will free its output stream when it is, itself, freed. Otherwise, it is the responsibility of the routine that constructed the log to ensure that the output stream is freed when it is no longer required.

Public function setOwnsOutput(const flag: boolean): boolean; virtual;

Set whether or not the log assumes ownership of its output stream.

If flag is True, then the log will assume ownership of its output stream and will attempt to free that stream when the log is, itself, freed. If set to False, then the log will not attempt to free its output stream and it will be the responsibility of the caller to ensure that stream is freed when it is no longer required.

Generated by PasDoc 0.13.0 on 2015-06-23 19:40:11