#!/usr/bin/env perl
#
#  This file is part of WebDyne.
#
#  This software is copyright (c) 2026 by Andrew Speer <andrew.speer@isolutions.com.au>.
#
#  This is free software; you can redistribute it and/or modify it under
#  the same terms as the Perl 5 programming language system itself.
#
#  Full license text is available at:
#
#  <http://dev.perl.org/licenses/>
#


#
#  Compile and/or show compiled version of WebDyne HTML scripts
#
package main;


#  Compiler pragma, load library path
#
use strict qw(vars);
use vars   qw($VERSION);
use warnings;


#  Use the base modules
#
use WebDyne::Util;


#  External modules
#
use WebDyne::Compile;
use Getopt::Long;
use Pod::Usage;
use Data::Dumper;
use File::Spec;
use FindBin qw($RealBin $Script);
$Data::Dumper::Indent=1;
$Data::Dumper::Sortkeys=1;


#  Version Info, must be all one line for MakeMaker, CPAN.
#
$VERSION='2.065';


#  Run main
#
exit ${&main(\@ARGV) || die errdump()};


#===================================================================================================


sub main {


    #  Get argv array ref
    #
    my $argv_ar=shift();


    #  Base options will pass to compile
    #
    my %opt=(

        nofilter      => 1,    # don't run through any filters
        noperl        => 1,    # don't run perl code,
        notimestamp   => 1,
        manifest      => 1,

        #stage5   => 1,    # default

    );


    #  Now import command line options. Command line option compilation stages are different from
    #  internal stage numbers so maps are 0=>stage0, 1=>stage2, 2=>stage3, 3=>stage4, confusing ..
    #
    GetOptions(
        \%opt, qw(
            stage0|0
            stage1|1
            stage2|2
            stage3|3
            stage4|4
            stage5|5|final
            meta
            data
            manifest!
            outfile|dest|dest_fn:s
            all
            timestamp!
            repeat|r|num|n=s
            perl!
            filter!
            version
            help|?
            man
            opt
        )) || pod2usage(2);
    pod2usage(-verbose => 99, -sections => 'SYNOPSIS|OPTIONS', -exitval => 1) if $opt{'help'};
    pod2usage(-verbose => 2)                                                  if $opt{'man'};
    $opt{'version'} && do {
        print "$Script version: $VERSION\n";
        print "WebDyne version: $WebDyne::VERSION ($WebDyne::VERSION_GIT_SHA)\n";
        exit 0
    };


    #  Clunky, too hard to change module logic
    #
    map {$opt{"no${_}"}=!($opt{$_})} qw(perl filter timestamp manifest);


    #  Get srce file, add to options
    #
    my $srce_fn=$argv_ar->[0] ||
        pod2usage("$Script: no source file specified !");
    $opt{'srce'}=$srce_fn;


    #  Dump options for debugging
    #
    die Dumper(\%opt) if $opt{'opt'};


    #  Loop if required as diagnostic for consistant compiles, i.e. making
    #  sure we haven't deleted an attribute from save data tree etc.
    #
    for (1 .. ($opt{'repeat'} || 1)) {

        #  Create and run compile object
        #
        my $compile_or=WebDyne::Compile->new(\%opt);
        my $data_ar=$compile_or->compile(\%opt) ||
            return err();


        #  Dump it
        #
        if ($opt{'all'}) {
            print Dumper($data_ar);
        }
        elsif ($opt{'meta'}) {
            print Dumper($data_ar->[0])
        }
        else {
            print Dumper($data_ar->[1])
        }

    }

    #print Data::Dumper::Dumper(grep {$_} $opt{'meta'} ? $data_ar->[0] : undef, $data_ar->[1]);


    #  Return success
    #
    return \0;


}

__END__



=pod

=head1 wdcompile(1)

=head1 NAME

wdcompile - parse and display internal data representation of WebDyne files

=head1 SYNOPSIS

C<<<< wdcompile [OPTIONS] FILE >>>>

=head1 Description

The  C<<<< wdcompile >>>>  command displays internal compiled (Storable) representation of a .psp page using the WebDyne perl module.

WebDyne parses HTML into an intermediate format which is then stored to disk to speed up subsequent rendering of pages. It is dependent on HTML::Treebuilder and HTML::Parser modules to build the tree, and results are stored to disk in a data array format via the Storable module.

The parser may build incorrect representations on a HTML tree if the HTML is badly formed or there are errors in the WebDyne compiler itself. This utility is useful for diagnosing any such errors.

The parser interprets files in 3 main stages (and some lesser intermediate stages that do not impact data structure but are used in the test suites): a full HTML::TreeBuilder representation of all tags with no optimisation, an intermediate partial optimisation stage that re-renders tags with no dynamic components (e.g. no <perl> or similar tags) back into
 static HTML and a final fully optimised file that should only contain a data structure for dynamic components of the page.

The final data structure contains various artifacts used by the render engine such as a manifest section, and notation of line numbers for dynamic sections to aid in error display and source file tracebacks should an error occur in any dynamic code at render time.

=head1 Options

=over

=item * B<<< -h, --help >>>

Show brief help message.

=item * B<<< --meta >>>

Show just the file metadata in compile output

=item * B<<< --data >>>

Show just the file data structure in compile output, no meta data. This is the default

=item * B<<< --all >>>

Show both the file meta and core data in output

=item * B<<< --[no]manifest >>>

Do/do not populate the filename into the metadata manifest section. Only used in test suite.

=item * B<<< --[no]timestamp >>>

Do/do not populate the timestamp into the metadata manifest section. Only used in test suite.

=item * B<<< --[no]perl >>>

Do/do not run Perl in __PERL__ section at compile time. The default is to not run any Perl sections.

=item * B<<< --[no]filter >>>

Do/do not run any filter stages that may be nominated in the file.

=item * B<<< --outfile >>>

Specify the output file to save the Storable representation of the data.

=item * B<<< --repeat | --r | --num | --n >>>

Specify the number of times to repeat the compile. Used for consistency testing

=item * B<<< --stage[n]|stage0|stage1|stage2|stage3|stage4|stage5|final >>>

Stop at a certain stage of the compile process. The default is to compile to final representation. The most significant intermediate stages are stage 0 for the raw tree, stage 4 for the first intermediate compile optimisation and stage 5 (final) for final optimisation.

=item * B<<< --man >>>

Display the full manual.

=item * B<<< --version >>>

Display the script version and exit.

=back

=head1 Examples

    # Reference file saved as time.psp
    #
    <start_html>
    The current server time is: <? localtime() ?>

    # Show the final compiled data structure of time.psp
    #
    $ wdcompile time.psp
    
    $VAR1 = [
      '<!DOCTYPE html><html lang="en"><head><title>Untitled Document</title><meta charset="UTF-8"><meta content="width=device-width, initial-scale=1.0" name="viewport"></head>
    <body><p>The current server time is: ',
      [
        'perl',
        {
          'inline' => 1,
          'perl' => ' localtime() '
        },
        undef,
        undef,
        2,
        2,
        \'time.psp'
      ],
      '</p></body></html>'
    ];

    # Show the initial compiled data structure (stage 0) of the time.psp file including metadata
    #
    $ wdcompile --all --stage0 time.psp
    
    $VAR1 = [
      {
        'manifest' => [
          'time.psp'
        ]
      },
      [
        'html',
        {
          'lang' => 'en'
        },
        [
          [
            'head',
            undef,
            [
              [
                'title',
                undef,
                [
                  'Untitled Document'
                ],
                undef,
                1,
                1,
                \$VAR1->[0]{'manifest'}[0]
                ...

=head1 Notes

The  C<<<< wdcompile >>>>  command will attempt to build the HTML tree as faithfully as possible from the command line environment, but may not be able to interpret all HTML files, especially those with malformed HTML tags. It is reliant on HTML::TreeBuilder and HTML::Parser. If you are sure your HTML is compliant (all tags closed, all attributes double quoted
 etc.) and wdcompile is still producing a malformed tree you can submit a big report with the smallest possible HTML file needed to replicate the issue.

=head1 Author

Written by Andrew Speer,  <andrew@webdyne.org>

=head1 LICENSE and COPYRIGHT

This file is part of WebDyne.

This software is copyright (c) 2026 by Andrew Speer L<mailto:andrew.speer@isolutions.com.au>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

Full license text is available at:

L<http://dev.perl.org/licenses/>

=cut