scummvm-cursorfix/engines/ags/shared/debugging/debug_manager.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

//=============================================================================
//
// AGS logging system is built with idea that the engine components should not
// be bothered with specifying particular output method. Instead they use
// generic logging interface, and the actual message printing is done by one
// or more registered handlers.
// Firstly this makes logging functions independent of running platform or
// back-end, secondly it grants end-users ability to configure output according
// to their preference.
//
// To make the logging work we need to register two sets of "entities":
// debug groups and output targets.
// Debug group is an arbitrary object with a name that describes message
// sender.
// Output target defines printing handler and a set of verbosity rules
// one per each known group.
//
// When the message is sent, it is tagged with one of the existing group IDs
// and a message type (debug info, warning, error). This message is sent onto
// each of the registered output targets, which do checks to find out whether
// the message is permitted to be sent further to the printing handler, or not.
//
//=============================================================================

#ifndef AGS_SHARED_DEBUGGING_DEBUG_MANAGER_H
#define AGS_SHARED_DEBUGGING_DEBUG_MANAGER_H

#include "common/std/memory.h"
#include "common/std/map.h"
#include "ags/shared/debugging/out.h"
#include "ags/shared/debugging/output_handler.h"
#include "ags/shared/util/string.h"
#include "ags/shared/util/string_types.h"

namespace AGS3 {
namespace AGS {
namespace Shared {

// DebugGroup is a message sender definition, identified by DebugGroupID
// and providing OutputName that could be used when printing its messages.
// OutputName may or may not be same as DebugGroupID.SID.
struct DebugGroup {
	DebugGroupID    UID;
	String          OutputName;

	DebugGroup() {
	}
	DebugGroup(DebugGroupID id, String out_name) : UID(id), OutputName(out_name) {
	}
};

// DebugOutput is a slot for IOutputHandler with its own group filter
class DebugOutput {
public:
	DebugOutput(const String &id, IOutputHandler *handler, MessageType def_verbosity = kDbgMsg_All, bool enabled = true);

	String          GetID() const;
	IOutputHandler *GetHandler() const;

	bool            IsEnabled() const;
	void            SetEnabled(bool enable);
	// Setup group filter: either allow or disallow a group with the given ID
	void            SetGroupFilter(DebugGroupID id, MessageType verbosity);
	// Assign same verbosity level to all known groups
	void            SetAllGroupFilters(MessageType verbosity);
	// Clear all group filters; this efficiently disables everything
	void            ClearGroupFilters();
	// Try to resolve group filter unknown IDs
	void            ResolveGroupID(DebugGroupID id);
	// Test if given group id is permitted
	bool            TestGroup(DebugGroupID id, MessageType mt) const;

private:
	String          _id;
	IOutputHandler *_handler;
	bool            _enabled;
	MessageType     _defaultVerbosity;
	// Set of permitted groups' numeric IDs
	std::vector<MessageType> _groupFilter;
	// Set of unresolved groups, which numeric IDs are not yet known
	typedef std::unordered_map<String, MessageType, IgnoreCase_Hash, IgnoreCase_EqualTo> GroupNameToMTMap;
	GroupNameToMTMap _unresolvedGroups;
};

typedef std::shared_ptr<DebugOutput> PDebugOutput;


class DebugManager {
	friend class DebugOutput;

public:
	DebugManager();

	// Gets full group ID for any partial one; if the group is not registered returns unset ID
	DebugGroup   GetGroup(DebugGroupID id);
	// Gets output control interface for the given ID
	PDebugOutput GetOutput(const String &id);
	// Registers debugging group with the given string ID; numeric ID
	// will be assigned internally. Returns full ID pair.
	// If the group with such string id already exists, returns existing ID.
	DebugGroup RegisterGroup(const String &id, const String &out_name);
	// Registers output delegate for passing debug messages to;
	// if the output with such id already exists, replaces the old one
	PDebugOutput RegisterOutput(const String &id, IOutputHandler *handler, MessageType def_verbosity = kDbgMsg_All, bool enabled = true);
	// Unregisters all groups and all targets
	void UnregisterAll();
	// Unregisters debugging group with the given ID
	void UnregisterGroup(DebugGroupID id);
	// Unregisters output delegate with the given ID
	void UnregisterOutput(const String &id);

	// Output message of given group and message type
	void Print(DebugGroupID group_id, MessageType mt, const String &text);
	// Send message directly to the output with given id; the message
	// must pass the output's message filter though
	void SendMessage(const String &out_id, const DebugMessage &msg);

private:
	// OutputSlot struct wraps over output target and adds a flag which indicates
	// that this target is temporarily disabled (for internal use only)
	struct OutputSlot {
		PDebugOutput Target;
		bool          Suppressed;

		OutputSlot() : Suppressed(false) {
		}
	};

	typedef std::vector<DebugGroup> GroupVector;
	typedef std::unordered_map<String, DebugGroupID, IgnoreCase_Hash, IgnoreCase_EqualTo> GroupByStringMap;
	typedef std::unordered_map<String, OutputSlot, IgnoreCase_Hash, IgnoreCase_EqualTo> OutMap;

	void RegisterGroup(const DebugGroup &id);
	void SendMessage(OutputSlot &out, const DebugMessage &msg);

	uint32_t            _firstFreeGroupID;
	uint32_t            _lastGroupID;
	GroupVector         _groups;
	GroupByStringMap    _groupByStrLookup;
	OutMap              _outputs;
};

} // namespace Shared
} // namespace AGS
} // namespace AGS3

#endif