/
IBuildAssembler.cs
109 lines (95 loc) · 5.12 KB
/
IBuildAssembler.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
//===============================================================================================================
// System : Sandcastle Tools - Sandcastle Tools Core Class Library
// File : IBuildAssembler.cs
// Author : Eric Woodruff (Eric@EWoodruff.us)
// Updated : 02/27/2022
// Note : Copyright 2022, Eric Woodruff, All rights reserved
//
// This file contains the interface used to define the common Build Assembler tool methods
//
// This code is published under the Microsoft Public License (Ms-PL). A copy of the license should be
// distributed with the code and can be found at the project website: https://GitHub.com/EWSoftware/SHFB. This
// notice, the author's name, and all copyright notices must remain intact in all applications, documentation,
// and source files.
//
// Date Who Comments
// ==============================================================================================================
// 02/26/2021 EFW Created the code
//===============================================================================================================
using System;
using System.Collections.Generic;
using System.Xml.XPath;
using Sandcastle.Core.BuildAssembler.BuildComponent;
using Sandcastle.Core.PresentationStyle.Transformation;
namespace Sandcastle.Core.BuildAssembler
{
/// <summary>
/// This interface defines the common Build Assembler tool properties, events, and methods used to generate
/// help topics.
/// </summary>
public interface IBuildAssembler
{
/// <summary>
/// This read-only property returns the verbosity level for the message handlers
/// </summary>
/// <value>The value can be <c>Info</c>, <c>Warn</c>, or <c>Error</c>. The default level is
/// <see cref="MessageLevel.Info"/> so that all messages are displayed. Setting it to a higher
/// level will suppress messages below the given level.</value>
/// <remarks>It is up to the message handler to make use of this property</remarks>
MessageLevel VerbosityLevel { get; }
/// <summary>
/// This read-only property returns the topic transformation to use for the presentation style
/// </summary>
TopicTransformationCore TopicTransformation { get; }
/// <summary>
/// This read-only property returns the current list of build components
/// </summary>
IEnumerable<BuildComponentCore> BuildComponents { get; }
/// <summary>
/// This read-only property returns a dictionary that can be used to store information shared between
/// build components.
/// </summary>
IDictionary<string, object> Data { get; }
/// <summary>
/// This event is raised when a component wants to signal that something of interest has happened
/// </summary>
event EventHandler ComponentEvent;
/// <summary>
/// This is used to raise the <see cref="ComponentEvent" />
/// </summary>
/// <param name="sender">The sender of the event</param>
/// <param name="e">The event arguments</param>
void OnComponentEvent(object sender, EventArgs e);
/// <summary>
/// Add a set of components based on the given configuration
/// </summary>
/// <param name="configuration">The configuration containing the component definitions</param>
void AddComponents(XPathNavigator configuration);
/// <summary>
/// Dispose of all components and clear them from the collection
/// </summary>
void ClearComponents();
/// <summary>
/// This is used to load a set of components in a configuration and return them as an enumerable list
/// </summary>
/// <param name="configuration">The configuration node from which to get the components</param>
/// <returns>An enumerable list of components created based on the configuration information</returns>
IEnumerable<BuildComponentCore> LoadComponents(XPathNavigator configuration);
/// <summary>
/// This is used to create a component based on the given configuration
/// </summary>
/// <param name="configuration">The component configuration</param>
/// <returns>A component created using the given definition</returns>
/// <exception cref="ArgumentNullException">This is thrown if <paramref name="configuration"/> is null</exception>
BuildComponentCore LoadComponent(XPathNavigator configuration);
/// <summary>
/// Write a component message to the message log
/// </summary>
/// <param name="componentName">The name of the component writing the message</param>
/// <param name="level">The message level</param>
/// <param name="key">An optional topic key related to the message or null if there isn't one</param>
/// <param name="message">The message to write to the console</param>
/// <remarks>If the message level is below the current verbosity level setting, the message is ignored</remarks>
void WriteMessage(string componentName, MessageLevel level, string key, string message);
}
}