{
* UTextSnippetDoc.pas
*
* Implements a class that renders a document that describes a snippet as plain
* text.
*
* $Rev$
* $Date$
*
* ***** BEGIN LICENSE BLOCK *****
*
* Version: MPL 1.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
* the specific language governing rights and limitations under the License.
*
* The Original Code is UTextSnippetDoc.pas, formerly UTextRoutineDoc.pas.
*
* The Initial Developer of the Original Code is Peter Johnson
* (http://www.delphidabbler.com/).
*
* Portions created by the Initial Developer are Copyright (C) 2009-2011 Peter
* Johnson. All Rights Reserved.
*
* Contributor(s)
* NONE
*
* ***** END LICENSE BLOCK *****
}
unit UTextSnippetDoc;
interface
uses
// Delphi
Classes,
// Project
UActiveText, UEncodings, UIStringList, USnippetDoc;
type
{
TTextSnippetDoc:
Class that renders a document that describes a snippet as plain text.
}
TTextSnippetDoc = class(TSnippetDoc)
strict private
var fWriter: TStringWriter; // Used to write plain text to stream
const cPageWidth = 80; // Width of output in characters
const cIndent = 2; // Size of indentation in characters
strict protected
procedure InitialiseDoc; override;
{Create writer object for output stream.
}
procedure RenderHeading(const Heading: string); override;
{Writes heading (snippet name) to output stream.
@param Heading [in] Heading to be written.
}
procedure RenderDescription(const Desc: string); override;
{Writes snippet description to output stream.
@param Desc [in] Description to be written.
}
procedure RenderSourceCode(const SourceCode: string); override;
{Writes snippet's source code to output stream.
@param SourceCode [in] Source code to be written.
}
procedure RenderTitledText(const Title, Text: string); override;
{Outputs text preceded by a title.
@param Title [in] Text title.
@param Text [in] Text to be written.
}
procedure RenderTitledList(const Title: string; List: IStringList);
override;
{Writes a comma-separated list preceded by a title to output stream.
@param Title [in] List title.
@param List [in] List of text to be written.
}
procedure RenderCompilerInfo(const Heading: string;
const Info: TCompileDocInfoArray); override;
{Writes details of compiler information to output stream.
@param Heading [in] Heading for compiler information.
@param Info [in] Array of compiler results (name and result as text).
}
procedure RenderExtra(const ExtraText: IActiveText); override;
{Writes snippet's extra information to output stream.
@param ExtraText [in] Text to be written.
}
procedure RenderDBInfo(const Text: string); override;
{Writes information about code snippets database to output stream.
@param Text [in] Text to be written.
}
function FinaliseDoc: TEncodedData; override;
{Renders text document as Unicode encoded data. Releases write object.
@return Unicode encoded text document.
}
end;
implementation
uses
// Delphi
SysUtils,
// Project
UStrUtils;
{ TTextSnippetDoc }
function TTextSnippetDoc.FinaliseDoc: TEncodedData;
{Renders text document as Unicode encoded data. Releases write object.
@return Unicode encoded text document.
}
begin
Result := TEncodedData.Create(fWriter.ToString, etUnicode);
fWriter.Free;
end;
procedure TTextSnippetDoc.InitialiseDoc;
{Create writer object to build up text.
}
begin
fWriter := TStringWriter.Create;
end;
procedure TTextSnippetDoc.RenderCompilerInfo(const Heading: string;
const Info: TCompileDocInfoArray);
{Writes details of compiler information to output stream.
@param Heading [in] Heading for compiler information.
@param Info [in] Array of compiler results (name and result as text).
}
var
Idx: Integer; // loops compiler information table
begin
fWriter.WriteLine;
fWriter.WriteLine(Heading);
for Idx := Low(Info) to High(Info) do
fWriter.WriteLine('%-20s%s', [Info[Idx].Compiler, Info[Idx].Result]);
end;
procedure TTextSnippetDoc.RenderDBInfo(const Text: string);
{Writes information about code snippets database to output stream.
@param Text [in] Text to be written.
}
begin
fWriter.WriteLine;
fWriter.WriteLine(StrWrap(Text, cPageWidth, 0));
end;
procedure TTextSnippetDoc.RenderDescription(const Desc: string);
{Writes snippet description to output stream.
@param Desc [in] Description to be written.
}
begin
fWriter.WriteLine;
fWriter.WriteLine(StrWrap(Desc, cPageWidth, 0));
end;
procedure TTextSnippetDoc.RenderExtra(const ExtraText: IActiveText);
{Writes snippet's extra information to output stream.
@param ExtraText [in] Text to be written.
}
var
Elem: IActiveTextElem; // each active text element
TextElem: IActiveTextTextElem; // refers to active text text elements
ActionElem: IActiveTextActionElem; // refers to active text action elements
Text: string; // text to be output
InBlock: Boolean; // flag true if inside a block level tag
resourcestring
sURL = ' (%s)'; // formatting for URLs from hyperlinks
begin
Assert(not ExtraText.IsEmpty, ClassName + '.RenderExtra: ExtraText is empty');
Assert(Supports(ExtraText[0], IActiveTextActionElem) and
((ExtraText[0] as IActiveTextActionElem).DisplayStyle = dsBlock),
ClassName + '.RenderExtra: ExtraText must begin with a block tag');
Assert(Supports(ExtraText[Pred(ExtraText.Count)], IActiveTextActionElem) and
((ExtraText[Pred(ExtraText.Count)] as IActiveTextActionElem).DisplayStyle
= dsBlock),
ClassName + '.RenderExtra: ExtraText must end with a block tag');
Text := '';
InBlock := False;
for Elem in ExtraText do
begin
if Supports(Elem, IActiveTextTextElem, TextElem) then
begin
if InBlock then
Text := Text + TextElem.Text;
end
else if Supports(Elem, IActiveTextActionElem, ActionElem) then
begin
case ActionElem.Kind of
ekPara, ekHeading:
begin
// paragraphs and headings start new lines, and are separated by
case ActionElem.State of
fsOpen:
begin
// open block: reset text - writing deferred until end of block
Text := '';
InBlock := True;
end;
fsClose:
begin
// close block: emit blank line then write any pending text only
// if there is any text
// note that we are guaranteed that a block close will be last
// thing in active text, so all text will be flushed
if Text <> '' then
begin
fWriter.WriteLine;
fWriter.WriteLine(StrWrap(Text, cPageWidth, 0));
Text := '';
InBlock := False;
end;
end;
end;
end;
ekLink:
begin
// hyperlink element: output in brackets only if closing element
if InBlock and (ActionElem.State = fsClose) then
Text := Text
+ Format(sURL, [ActionElem.Attrs[TActiveTextAttrNames.Link_URL]]);
end;
end;
end;
end;
end;
procedure TTextSnippetDoc.RenderHeading(const Heading: string);
{Writes heading (snippet name) to output stream.
@param Heading [in] Heading to be written.
}
begin
fWriter.WriteLine(Heading);
end;
procedure TTextSnippetDoc.RenderSourceCode(const SourceCode: string);
{Writes snippet's source code to output stream.
@param SourceCode [in] Source code to be written.
}
begin
fWriter.WriteLine;
fWriter.WriteLine(SourceCode);
fWriter.WriteLine;
end;
procedure TTextSnippetDoc.RenderTitledList(const Title: string;
List: IStringList);
{Writes a comma-separated list preceded by a title to output stream.
@param Title [in] List title.
@param List [in] List of text to be written.
}
begin
RenderTitledText(Title, CommaList(List));
end;
procedure TTextSnippetDoc.RenderTitledText(const Title, Text: string);
{Outputs text preceded by a title.
@param Title [in] Text title.
@param Text [in] Text to be written.
}
begin
fWriter.WriteLine(Title);
fWriter.WriteLine(StrWrap(Text, cPageWidth - cIndent, cIndent));
end;
end.
