Interface IReadsAndWritesDocument

An object which may read & write IDocument instances to/from streams. This is the core interface of "a document provider".

Namespace: ZptSharp.Dom

Assembly: ZptSharp.Abstractions.dll

Syntax

public interface IReadsAndWritesDocument

Remarks

A document provider is an add-on (albeit a required one) which allows ZptSharp to read & write markup documents. The ZptSharp core manipulates DOM documents via an abstraction; this is the IDocument interface and related types. Implementations of this interface allow reading/writing those abstract documents from/to instances of System.IO.Stream. In practical terms, this is the "load" and "save" logic of ZptSharp.

In order to have a working/usable ZptSharp environment, at least one document provider must be registered with dependency injection. This should be performed during application start-up, using extension methods for IBuildsHostingEnvironment.

Document provider implementations typically use 3rd-party libraries/APIs to perform a native read & write of the DOM documents. They then provide their own implementations of IDocument, INode & IAttribute which wrap the DOM nodes returned by that 3rd-party implementation. This is essentially an application of the https://en.wikipedia.org/wiki/Adapter_pattern.

Properties

ResolvableType

Gets the type of the current instance, for the purpose of future dependency resolution.

Declaration

Type ResolvableType { get; }

Property Value

Type	Description
System.Type

Remarks

Gets the type of the current instance, for the purpose of dependency resolution. This is not/should not be quite the same as System.Object.GetType(), because a derived implementation might not always be resolved as its precise type, it might be resolved as a less-derived base type.

Methods

CanReadWriteForFilename(String)

Gets a value which indicates whether or not the current instance may be used to read & write documents which have the specified filename.

Declaration

bool CanReadWriteForFilename(string filenameOrPath)

Parameters

Type	Name	Description
System.String	filenameOrPath	The file name or file path of a ZPT document.

Returns

Type	Description
System.Boolean	true, if this instance may be used for the specified file name/file path; false if not.

Remarks

This is the mechanism by which an IGetsZptDocumentRendererForFilePath (and ultimately an IRendersZptFile) selects an appropriate document provider implementation for a specified file.

This enables document providers to be used with the strategy pattern - https://en.wikipedia.org/wiki/Strategy_pattern - interrogating each of the available providers to determine which can perform the required task.

See Also

IGetsZptDocumentRendererForFilePath

IRendersZptFile

GetDocumentAsync(Stream, RenderingConfig, IDocumentSourceInfo, CancellationToken)

Gets a document instance from the specified input stream which contains text markup.

Declaration

Task<IDocument> GetDocumentAsync(Stream stream, RenderingConfig config, IDocumentSourceInfo sourceInfo = null, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.IO.Stream	stream	A stream containing the source of the document.
RenderingConfig	config	Rendering configuration.
IDocumentSourceInfo	sourceInfo	Information which identifies the source of the document.
System.Threading.CancellationToken	token	An object used to cancel the operation if required.

Returns

Type	Description
System.Threading.Tasks.Task<IDocument>	A task which provides the document which has been read.

Remarks

This method is used to 'load' a ZptSharp IDocument from a stream. Streams are used rather than files so that ZptSharp is not limited to only loading documents from files on disk. In most circumstances the sourceInfo will have been specified and this object will indicate the source of the stream, which should be passed to the returned document.

The API of this method is asynchronous (returning a task) although it is recognised that not all implementations will fully support asynchronous loading of documents. This also means that there is no certainty that implementations will honour the usage of the token to cancel/abort the operation before it completes.

Finally, implementations should honour the rendering config passed to this method, but are permitted not to honour settings which are either irrelevant or which cannot be supported.

WriteDocumentAsync(IDocument, RenderingConfig, CancellationToken)

Writes the document to text markup and returns a stream containing the rendered document.

Declaration

Task<Stream> WriteDocumentAsync(IDocument document, RenderingConfig config, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
IDocument	document	The document to write.
RenderingConfig	config	Rendering configuration.
System.Threading.CancellationToken	token	An object used to cancel the operation if required.

Returns

Type	Description
System.Threading.Tasks.Task<System.IO.Stream>	A task which provides the output stream.

Remarks

This method is used to 'save' a ZptSharp IDocument to a System.IO.Stream. Streams are used rather than files so that ZptSharp is not limited to only saving documents as files on disk.

The API of this method is asynchronous (returning a task) although it is recognised that not all implementations will fully support asynchronous writing of documents. This also means that there is no certainty that implementations will honour the usage of the token to cancel/abort the operation before it completes.

Finally, implementations should honour the rendering config passed to this method, but are permitted not to honour settings which are either irrelevant or which cannot be supported.

See Also

IDocument

INode

IAttribute

IBuildsHostingEnvironment