Dita::PCD - Implementation of the Please Change Dita Language.
Applying the PCD file test.pcd:
# Sample pcd file Change d under c under b to D change D d c b Change B to b change b B rn BBBB Merge two adjacent b mergeLikePrev b
To a sample Xml file 1.dita:
<a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a>
Produces the following messages:
Change d under c under b to D at test.pcd line 2 BBBB at test.pcd line 8 <b> <c> <d/> </c> </b> Change B to b at test.pcd line 6 Merge two adjacent b at test.pcd line 10
And the following output Xml in out/1.dita:
<a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a>
The Dita::Pcd commands available are those documented in: Data::Edit::Xml.
Each block of commands is applied to each node of the parse tree produced by Data::Edit::Xml. If the block completes successfully the description line at the head of the block is printed. Execution of a block is halted if one of the commands in the block returns a false value. Any changes made to the parse tree before a block halts are retained so it is sensible to put as many tests as might be necessary at the start of the block to ensure that all the conditions are met to allow the block to complete successfully or to halt the block before the block starts making changes to the parse tree.
Implementation of the Please Change Dita Language.
Version 20201030.
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Edit Dita using directives written in Dita::Pcd. An introduction to Dita::Pcd can be found at: PCD.
Parse the url representation of a parse tree.
Parameter Description 1 $url Url
Example:
if (1) {my $testUrl = {q(001_action) => q(), q(001_rowType1) => q(comment), q(001_rowType2) => q(comment), q(001_method) => q(Sample+Pcd+file), q(002_action) => q(), q(002_rowType1) => q(description), q(002_rowType2) => q(description), q(002_method) => q(sf-111+unwrap+ph+under+title), q(003_action) => q(), q(003_rowType1) => q(method), q(003_rowType2) => q(method), q(003_method) => q(unwrap), q(003_context_1) => q(ph), q(003_context_2) => q(title), q(003_context_3) => q()}; my $parseTree = parseUrlRepresentationOfPcd($testUrl); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 ok representPcdParseTreeAsText($parseTree) eq <<END; # Sample Pcd file sf-111 unwrap ph under title unwrap ph title END }
This method can be imported via:
use Dita::PCD qw(parseUrlRepresentationOfPcd)
Compile the specified Dita::Pcd directives $file specifying changes to be made to Dita files.
Parameter Description 1 $if Input file
my $in = temporaryFolder; my $out = temporaryFolder; my $inXml = <<END; <a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a> END my $outXml = <<END; <a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a> END writeFile(fpe($in, qw(1 dita)), $inXml); my $inFile = writeFile(fpe($in, qw(test pcd)), <<END); Change d under c under b to D change D d c b Change B to b change b B Merge two adjacent b mlp b END pleaseChangeDita(in=>$in, out=>$out); ok readFile(fpe($out, qw(1 dita))) eq $outXml; my $blocks = compilePcdFile($inFile); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 ok dump(compilePcdFiles($in)) eq dump($blocks); for(1..1) {my $x = Data::Edit::Xml::new($inXml); transformDitaWithPcdOptimized(q(), $x, $blocks); ok -p $x eq $outXml; } clearFolder($_, 1e2) for $in, $out; my $in = temporaryFolder; my $f = owf(fpe($in, qw(test pcd)), <<END); # Sample Pcd file sf-111 unwrap ph under title unwrap2 ph2 title END my $p = parsePcdFile($f); delete $p->{inputFile}; is_deeply $p, bless({ errors => [], rows => [ bless({ action => "", actionError => "", comment => "Sample Pcd file", rowType => "comment", rowTypeError => "", }, "DitaPcdComment"), bless({ action => "", actionError => "", description => "sf-111 unwrap ph under title", rowType => "description", rowTypeError => "", }, "DitaPcdDescription"), bless({ action => "", actionError => "", context => ["ph2", "title"], contextErrors => {}, method => "unwrap2", methodError => "", rowType => "method", rowTypeError => "", }, "DitaPcdMethod"), ], }, "DitaPCDParseTree");
use Dita::PCD qw(compilePcdFile)
Locate and compile the Dita files in the specified folder @in.
Parameter Description 1 @in Input folders
my $in = temporaryFolder; my $out = temporaryFolder; my $inXml = <<END; <a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a> END my $outXml = <<END; <a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a> END writeFile(fpe($in, qw(1 dita)), $inXml); my $inFile = writeFile(fpe($in, qw(test pcd)), <<END); Change d under c under b to D change D d c b Change B to b change b B Merge two adjacent b mlp b END pleaseChangeDita(in=>$in, out=>$out); ok readFile(fpe($out, qw(1 dita))) eq $outXml; my $blocks = compilePcdFile($inFile); ok dump(compilePcdFiles($in)) eq dump($blocks); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 for(1..1) {my $x = Data::Edit::Xml::new($inXml); transformDitaWithPcdOptimized(q(), $x, $blocks); ok -p $x eq $outXml; } clearFolder($_, 1e2) for $in, $out; my $in = temporaryFolder; my $f = owf(fpe($in, qw(test pcd)), <<END); # Sample Pcd file sf-111 unwrap ph under title unwrap2 ph2 title END my $p = parsePcdFile($f); delete $p->{inputFile}; is_deeply $p, bless({ errors => [], rows => [ bless({ action => "", actionError => "", comment => "Sample Pcd file", rowType => "comment", rowTypeError => "", }, "DitaPcdComment"), bless({ action => "", actionError => "", description => "sf-111 unwrap ph under title", rowType => "description", rowTypeError => "", }, "DitaPcdDescription"), bless({ action => "", actionError => "", context => ["ph2", "title"], contextErrors => {}, method => "unwrap2", methodError => "", rowType => "method", rowTypeError => "", }, "DitaPcdMethod"), ], }, "DitaPCDParseTree");
use Dita::PCD qw(compilePcdFiles)
Transform the contents of file $if represented as a parse tree $x by applying the specified Dita::Pcd directives in $blocks.
Parameter Description 1 $if Input file 2 $x Parse tree 3 $blocks Change blocks
my $in = temporaryFolder; my $out = temporaryFolder; my $inXml = <<END; <a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a> END my $outXml = <<END; <a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a> END writeFile(fpe($in, qw(1 dita)), $inXml); my $inFile = writeFile(fpe($in, qw(test pcd)), <<END); Change d under c under b to D change D d c b Change B to b change b B Merge two adjacent b mlp b END pleaseChangeDita(in=>$in, out=>$out); ok readFile(fpe($out, qw(1 dita))) eq $outXml; my $blocks = compilePcdFile($inFile); ok dump(compilePcdFiles($in)) eq dump($blocks); for(1..1) {my $x = Data::Edit::Xml::new($inXml); transformDitaWithPcdOptimized(q(), $x, $blocks); ok -p $x eq $outXml; } clearFolder($_, 1e2) for $in, $out; my $in = temporaryFolder; my $f = owf(fpe($in, qw(test pcd)), <<END); # Sample Pcd file sf-111 unwrap ph under title unwrap2 ph2 title END my $p = parsePcdFile($f); delete $p->{inputFile}; is_deeply $p, bless({ errors => [], rows => [ bless({ action => "", actionError => "", comment => "Sample Pcd file", rowType => "comment", rowTypeError => "", }, "DitaPcdComment"), bless({ action => "", actionError => "", description => "sf-111 unwrap ph under title", rowType => "description", rowTypeError => "", }, "DitaPcdDescription"), bless({ action => "", actionError => "", context => ["ph2", "title"], contextErrors => {}, method => "unwrap2", methodError => "", rowType => "method", rowTypeError => "", }, "DitaPcdMethod"), ], }, "DitaPCDParseTree");
use Dita::PCD qw(transformDitaWithPcd)
Transform the specified parse tree $x by applying the specified Dita::Pcd directive $blocks without any reporting to speed up execution.
my $in = temporaryFolder; my $out = temporaryFolder; my $inXml = <<END; <a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a> END my $outXml = <<END; <a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a> END writeFile(fpe($in, qw(1 dita)), $inXml); my $inFile = writeFile(fpe($in, qw(test pcd)), <<END); Change d under c under b to D change D d c b Change B to b change b B Merge two adjacent b mlp b END pleaseChangeDita(in=>$in, out=>$out); ok readFile(fpe($out, qw(1 dita))) eq $outXml; my $blocks = compilePcdFile($inFile); ok dump(compilePcdFiles($in)) eq dump($blocks); for(1..1) {my $x = Data::Edit::Xml::new($inXml); transformDitaWithPcdOptimized(q(), $x, $blocks); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 ok -p $x eq $outXml; } clearFolder($_, 1e2) for $in, $out;
use Dita::PCD qw(transformDitaWithPcdOptimized)
Transform L[dita] files as specified by the directives in Dita::Pcd files.
Parameter Description 1 %options Execution options
my $in = temporaryFolder; my $out = temporaryFolder; my $inXml = <<END; <a> <b> <c> <d/> </c> </b> <B> <c> <d/> </c> </B> </a> END my $outXml = <<END; <a> <b> <c> <D/> </c> <c> <d/> </c> </b> </a> END writeFile(fpe($in, qw(1 dita)), $inXml); my $inFile = writeFile(fpe($in, qw(test pcd)), <<END); Change d under c under b to D change D d c b Change B to b change b B Merge two adjacent b mlp b END pleaseChangeDita(in=>$in, out=>$out); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 ok readFile(fpe($out, qw(1 dita))) eq $outXml; my $blocks = compilePcdFile($inFile); ok dump(compilePcdFiles($in)) eq dump($blocks); for(1..1) {my $x = Data::Edit::Xml::new($inXml); transformDitaWithPcdOptimized(q(), $x, $blocks); ok -p $x eq $outXml; } clearFolder($_, 1e2) for $in, $out; my $in = temporaryFolder; my $f = owf(fpe($in, qw(test pcd)), <<END); # Sample Pcd file sf-111 unwrap ph under title unwrap2 ph2 title END my $p = parsePcdFile($f); delete $p->{inputFile}; is_deeply $p, bless({ errors => [], rows => [ bless({ action => "", actionError => "", comment => "Sample Pcd file", rowType => "comment", rowTypeError => "", }, "DitaPcdComment"), bless({ action => "", actionError => "", description => "sf-111 unwrap ph under title", rowType => "description", rowTypeError => "", }, "DitaPcdDescription"), bless({ action => "", actionError => "", context => ["ph2", "title"], contextErrors => {}, method => "unwrap2", methodError => "", rowType => "method", rowTypeError => "", }, "DitaPcdMethod"), ], }, "DitaPCDParseTree");
use Dita::PCD qw(pleaseChangeDita)
Apply a pcd string to an xml string and return the resulting string
Parameter Description 1 $xml Xml 2 $pcd Pcd options 3 %options Options
ok pleaseChangeDitaString(q(<a><b>C</b></a>), qq(Unwrap unwrap b))->string eq qq(<a>C</a>); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
use Dita::PCD qw(pleaseChangeDitaString)
Description of a comment
Comment text
Description
Description text
Base of various objects used by the editor
Parameter Description 1 $rowType Row type
Create a new comment
Parameter Description 1 %options Attributes
Create a new description
Create a new Method
Create a new Parse Tree
Parse the specified Dita::Pcd directives $string specifying changes to be made to Dita files.
Parameter Description 1 $string String of PCD directives
Parse the specified Dita::Pcd directives $file specifying changes to be made to Dita files.
Validate a $parseTree
Parameter Description 1 $parseTree Parse tree
Create a data list
Parameter Description 1 $name Name 2 @values Values
Print a PCD using HTML
Parameter Description 1 $string Pcd as a string
Print a parse tree as text
Compile the specified Dita::Pcd directives in the supplied $string optionally associated with $file.
Parameter Description 1 $string Input string 2 $file Optional name of file associated with string
Replace <> by < > to make example html displayable
Parameter Description 1 $string String
Print the PCD examples found in the module description of Data::Edit::Xml.
Parameter Description 1 $mod Module description of Data::Edit::Xml 2 $formatter Optional sub to format xml
1 compilePcdFile - Compile the specified Dita::Pcd directives $file specifying changes to be made to Dita files.
2 compilePcdFiles - Locate and compile the Dita files in the specified folder @in.
3 compilePcdString - Compile the specified Dita::Pcd directives in the supplied $string optionally associated with $file.
4 ditaPcdBase - Base of various objects used by the editor
5 editPcdParseTree - Validate a $parseTree
6 formatHtml - Replace <> by < > to make example html displayable
7 makeDataList - Create a data list
8 newDitaPcdComment - Create a new comment
9 newDitaPcdDescription - Create a new description
10 newDitaPcdMethod - Create a new Method
11 newDitaPcdParseTree - Create a new Parse Tree
12 parsePcdFile - Parse the specified Dita::Pcd directives $file specifying changes to be made to Dita files.
13 parsePcdString - Parse the specified Dita::Pcd directives $string specifying changes to be made to Dita files.
14 parseUrlRepresentationOfPcd - Parse the url representation of a parse tree.
15 pleaseChangeDita - Transform L[dita] files as specified by the directives in Dita::Pcd files.
16 pleaseChangeDitaString - Apply a pcd string to an xml string and return the resulting string
17 printPcdExamplesHtml - Print the PCD examples found in the module description of Data::Edit::Xml.
18 printPcdHtml - Print a PCD using HTML
19 representPcdParseTreeAsHtml - Parse the specified Dita::Pcd directives $file specifying changes to be made to Dita files.
20 representPcdParseTreeAsText - Print a parse tree as text
21 transformDitaWithPcd - Transform the contents of file $if represented as a parse tree $x by applying the specified Dita::Pcd directives in $blocks.
22 transformDitaWithPcdOptimized - Transform the specified parse tree $x by applying the specified Dita::Pcd directive $blocks without any reporting to speed up execution.
All of the following methods can be imported via:
use Dita::PCD qw(:all);
Or individually via:
use Dita::PCD qw(<method>);
1 compilePcdFile
2 compilePcdFiles
3 parseUrlRepresentationOfPcd
4 pleaseChangeDita
5 pleaseChangeDitaString
6 transformDitaWithPcd
7 transformDitaWithPcdOptimized
This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:
sudo cpan install Dita::PCD
philiprbrenan@gmail.com
http://www.appaapps.com
Copyright (c) 2016-2019 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.
To install Dita::PCD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dita::PCD
CPAN shell
perl -MCPAN -e shell install Dita::PCD
For more information on module installation, please visit the detailed CPAN module installation guide.