Name

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

Synopsis

Applying the PCD Language 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 20190811.

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 Language.

compilePcdFile($)

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

     Parameter  Description
  1  $if        Input file

Example:

  if (1) {                                                                          
   my $blocks =
  [[["Change d under c under b to D", 1, "test.pcd"],
   [["\$o->change((\"D\", \"d\", \"c\", \"b\"));",  2, "test.pcd"]]],
   [["Change B to b", 4, "test.pcd"],
   [["\$o->change((\"b\", \"B\"));", 5, "test.pcd"]]],
   [["Merge two adjacent b", 7, "test.pcd"],
   [["\$o->mlp(\"b\");", 8, "test.pcd"]],
  ]];
  
    is_deeply [eval(dump(𝗰𝗼𝗺𝗽𝗶𝗹𝗲𝗣𝗰𝗱𝗙𝗶𝗹𝗲($inFile)) =~ s($in) ()gsr)], $blocks;
    is_deeply  eval(dump(compilePcdFiles($in))    =~ s($in) ()gsr),  $blocks;
  
    ok -p transformDitaWithPcd(Data::Edit::Xml::new(<<END), $blocks) eq <<END;
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <B>
      <c>
        <d/>
      </c>
    </B>
  </a>
  END
  <a>
    <b>
      <c>
        <D/>
      </c>
      <c>
        <d/>
      </c>
    </b>
  </a>
  END
  
  }
  clearFolder($_, 1e2) for $in, $out;
  
  done_testing;
  

This method can be imported via:

  use Dita::PCD qw(compilePcdFile)

compilePcdFiles(@)

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

     Parameter  Description
  1  @in        Input folders

Example:

  if (1) {                                                                          
   my $blocks =
  [[["Change d under c under b to D", 1, "test.pcd"],
   [["\$o->change((\"D\", \"d\", \"c\", \"b\"));",  2, "test.pcd"]]],
   [["Change B to b", 4, "test.pcd"],
   [["\$o->change((\"b\", \"B\"));", 5, "test.pcd"]]],
   [["Merge two adjacent b", 7, "test.pcd"],
   [["\$o->mlp(\"b\");", 8, "test.pcd"]],
  ]];
  
    is_deeply [eval(dump(compilePcdFile($inFile)) =~ s($in) ()gsr)], $blocks;
    is_deeply  eval(dump(𝗰𝗼𝗺𝗽𝗶𝗹𝗲𝗣𝗰𝗱𝗙𝗶𝗹𝗲𝘀($in))    =~ s($in) ()gsr),  $blocks;
  
    ok -p transformDitaWithPcd(Data::Edit::Xml::new(<<END), $blocks) eq <<END;
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <B>
      <c>
        <d/>
      </c>
    </B>
  </a>
  END
  <a>
    <b>
      <c>
        <D/>
      </c>
      <c>
        <d/>
      </c>
    </b>
  </a>
  END
  
  }
  clearFolder($_, 1e2) for $in, $out;
  
  done_testing;
  

This method can be imported via:

  use Dita::PCD qw(compilePcdFiles)

transformDitaWithPcd($$$)

Transform the specified parse tree $x by applying the specified Dita::PCD directive $blocks optionally tracing the transformations applied if $trace is true.

     Parameter  Description
  1  $x         Parse tree
  2  $blocks    Change blocks
  3  $trace     Trace block execution if true

Example:

  if (1) {                                                                          
   my $blocks =
  [[["Change d under c under b to D", 1, "test.pcd"],
   [["\$o->change((\"D\", \"d\", \"c\", \"b\"));",  2, "test.pcd"]]],
   [["Change B to b", 4, "test.pcd"],
   [["\$o->change((\"b\", \"B\"));", 5, "test.pcd"]]],
   [["Merge two adjacent b", 7, "test.pcd"],
   [["\$o->mlp(\"b\");", 8, "test.pcd"]],
  ]];
  
    is_deeply [eval(dump(compilePcdFile($inFile)) =~ s($in) ()gsr)], $blocks;
    is_deeply  eval(dump(compilePcdFiles($in))    =~ s($in) ()gsr),  $blocks;
  
    ok -p 𝘁𝗿𝗮𝗻𝘀𝗳𝗼𝗿𝗺𝗗𝗶𝘁𝗮𝗪𝗶𝘁𝗵𝗣𝗰𝗱(Data::Edit::Xml::new(<<END), $blocks) eq <<END;
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <B>
      <c>
        <d/>
      </c>
    </B>
  </a>
  END
  <a>
    <b>
      <c>
        <D/>
      </c>
      <c>
        <d/>
      </c>
    </b>
  </a>
  END
  
  }
  clearFolder($_, 1e2) for $in, $out;
  
  done_testing;
  

This method can be imported via:

  use Dita::PCD qw(transformDitaWithPcd)

pleaseChangeDita(%)

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

     Parameter  Description
  1  %options   Execution options

Example:

  𝗽𝗹𝗲𝗮𝘀𝗲𝗖𝗵𝗮𝗻𝗴𝗲𝗗𝗶𝘁𝗮(in=>$in, out=>$out, trace=>1);                                 
  

This method can be imported via:

  use Dita::PCD qw(pleaseChangeDita)

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 pleaseChangeDita - Transform L[dita] files as specified by the directives in Dita::PCD files.

4 transformDitaWithPcd - Transform the specified parse tree $x by applying the specified Dita::PCD directive $blocks optionally tracing the transformations applied if $trace is true.

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 pleaseChangeDita

4 transformDitaWithPcd

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

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.