Name

Dita::PCD - Implementation of the Please Change Dita Language.

Synopsis

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.

Description

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.

Please Change Dita

Edit Dita using directives written in Dita::Pcd. An introduction to Dita::Pcd can be found at: PCD.

parseUrlRepresentationOfPcd($url)

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)

compilePcdFile($if)

Compile the specified Dita::Pcd directives $file specifying changes to be made to Dita files.

   Parameter  Description
1  $if        Input file

Example:

    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");

This method can be imported via:

use Dita::PCD qw(compilePcdFile)

compilePcdFiles(@in)

Locate and compile the Dita files in the specified folder @in.

   Parameter  Description
1  @in        Input folders

Example:

    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");

This method can be imported via:

use Dita::PCD qw(compilePcdFiles)

transformDitaWithPcd($if, $x, $blocks)

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

Example:

    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");

This method can be imported via:

use Dita::PCD qw(transformDitaWithPcd)

transformDitaWithPcdOptimized($if, $x, $blocks)

Transform the specified parse tree $x by applying the specified Dita::Pcd directive $blocks without any reporting to speed up execution.

   Parameter  Description
1  $if        Input file
2  $x         Parse tree
3  $blocks    Change blocks

Example:

    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;

This method can be imported via:

use Dita::PCD qw(transformDitaWithPcdOptimized)

pleaseChangeDita(%options)

Transform L[dita] files as specified by the directives in Dita::Pcd files.

   Parameter  Description
1  %options   Execution options

Example:

    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");

This method can be imported via:

use Dita::PCD qw(pleaseChangeDita)

pleaseChangeDitaString($xml, $pcd, %options)

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

Example:

ok pleaseChangeDitaString(q(<a><b>C</b></a>), qq(Unwrap
unwrap b))->string eq qq(<a>C</a>);    # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲

This method can be imported via:

use Dita::PCD qw(pleaseChangeDitaString)

DitaPcdComment Definition

Description of a comment

Output fields

comment

Comment text

DitaPcdDescription Definition

Description

Output fields

description

Description text

Private Methods

ditaPcdBase($rowType)

Base of various objects used by the editor

   Parameter  Description
1  $rowType   Row type

newDitaPcdComment(%options)

Create a new comment

   Parameter  Description
1  %options   Attributes

newDitaPcdDescription(%options)

Create a new description

   Parameter  Description
1  %options   Attributes

newDitaPcdMethod(%options)

Create a new Method

   Parameter  Description
1  %options   Attributes

newDitaPcdParseTree(%options)

Create a new Parse Tree

   Parameter  Description
1  %options   Attributes

parsePcdString($string)

Parse the specified Dita::Pcd directives $string specifying changes to be made to Dita files.

   Parameter  Description
1  $string    String of PCD directives

parsePcdFile($if)

Parse the specified Dita::Pcd directives $file specifying changes to be made to Dita files.

   Parameter  Description
1  $if        Input file

editPcdParseTree($parseTree)

Validate a $parseTree

   Parameter   Description
1  $parseTree  Parse tree

makeDataList($name, @values)

Create a data list

   Parameter  Description
1  $name      Name
2  @values    Values

representPcdParseTreeAsHtml($parseTree)

Parse the specified Dita::Pcd directives $file specifying changes to be made to Dita files.

   Parameter   Description
1  $parseTree  Parse tree

printPcdHtml($string)

Print a PCD using HTML

   Parameter  Description
1  $string    Pcd as a string

representPcdParseTreeAsText($parseTree)

Print a parse tree as text

   Parameter   Description
1  $parseTree  Parse tree

compilePcdString($string, $file)

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

formatHtml($string)

Replace <> by < > to make example html displayable

   Parameter  Description
1  $string    String

printPcdExamplesHtml($mod, $formatter)

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

Index

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.

Exports

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

Installation

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

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Name

Synopsis

Description

Please Change Dita

parseUrlRepresentationOfPcd($url)

compilePcdFile($if)

compilePcdFiles(@in)

transformDitaWithPcd($if, $x, $blocks)

transformDitaWithPcdOptimized($if, $x, $blocks)

pleaseChangeDita(%options)

pleaseChangeDitaString($xml, $pcd, %options)

DitaPcdComment Definition

Output fields

comment

DitaPcdDescription Definition

Output fields

description

Private Methods

ditaPcdBase($rowType)

newDitaPcdComment(%options)

newDitaPcdDescription(%options)

newDitaPcdMethod(%options)

newDitaPcdParseTree(%options)

parsePcdString($string)

parsePcdFile($if)

editPcdParseTree($parseTree)

makeDataList($name, @values)

representPcdParseTreeAsHtml($parseTree)

printPcdHtml($string)

representPcdParseTreeAsText($parseTree)

compilePcdString($string, $file)

formatHtml($string)

printPcdExamplesHtml($mod, $formatter)

Index

Exports

Installation

Author

Copyright

Module Install Instructions