Simulated run option

[coemgenuslcp]

I propose a "simulated run" option that will show the results of a command without truly executing it. Hypothetical example:

Normal run:
pmlc convert --input_file "$inputFilePath" --output_directory "$outputFolderPath"

Simulated run:
pmlc convert --input_file "$inputFilePath" --output_directory "$outputFolderPath" --simulate

The new argument would look like this:

Id             : simulate
Title          : Simulate
Type           : yes_no
Description    : If this parameter is set to 'yes' then:
                 - the output directory is not generated if it doesn't already exist
                 - no files are copied to the output directory
                 - the intended changes are revealed to the console output
                 By default this parameter is set to 'no'.
Required       : no
Default value  : no
Examples       : --simulate

The simulated run can show the intended changes to the generated output, similar to Ansible's --check or --diff argument or Terraform's plan command.

An alternatve implementation might be like Terraform's --auto-approve option, wherewith the intended changes are revealed, and the executable by default pauses for user input ("Do you want to continue?") before applying the changes, with the auto-approve argument overriding that behavior to not pause.

The console output might also helpfully reveal the locations of the output_directory, resources_directory, etc. as they will appear on your file system after the command is run for real. This in turn can help you know whether your arguments are set correctly. Sample output might include this information, for instance:

Input file                      : my project/my input file.pml
Input file resolves to          : /home/user/my workspace/my project/my input file.pml
Output directory                : ../../my generated HTML
Output directory resolves to    : /home/user/my generated HTML/
Resources directory             : null
Resources directory resolves to : (not generated: resource references will be dangling) <-- (bad wording on my part, but you get the idea)

For inspiration by similarity, see also pmlc command_info --command convert which appears to dynamically show certain "default values" as resolved relative to your file system:

2.
Id             : HTML_header, html_header, header
Type           : absolute_or_relative_file_path or null
Required       : no
Default value  : /home/user/myapps/PML/pml-to-html-converter_1.5.0-1_amd64/lib/runtime/resources/html/default_html_header.txt

[pml-lang]

I propose a "simulated run" option that will show the results of a command without truly executing it.

Excellent idea!

--simulate

As far as I know, the argument dryrun is often used for this kind of execution. So maybe we can adhere to that convention. Although IMO simulate is a better term for non-technical people.

show the intended changes to the generated output

I suppose that "intended changes" relates to changes in the file system (directory/file created/copied, etc), and not to changes in the resulting HTML document, right?

An alternatve implementation might be like Terraform's --auto-approve option, wherewith the intended changes are revealed, and the executable by default pauses for user input

That would be more sophisticated, but also a bit more time-consuming to implement. I suggest to start with a simulate/dryrun option, and add more options later, if asked by the community.

also helpfully reveal the locations of the output_directory, resources_directory, etc.

Yes!

dynamically show certain "default values" as resolved relative to your file system

Very helpful too.

Thanks!

[coemgenuslcp]

I hold no personal preference either way of the name choice. I like "simulate" for its clarity, but also "dry run" is a common term, and one that is really not obscure or confusing.

I suppose that "intended changes" relates to changes in the file system (directory/file created/copied, etc), and not to changes in the resulting HTML document, right?

Indeed, showing the files that will be generated or replaced is likely sufficient for the near future. Content changes would obviously be more intricate to implement, and so a topic not worth treating immediately.

[pml-lang]

Content changes would obviously be more intricate to implement, and so a topic not worth treating immediately.

True