Document use of Validation section

[SorraTheOrc]

Validation sections are both a normal part of a document and a way to test if a prerequisite is run. This issue is about their use as a normal part of a document. In this mode the validation section should be run. Consider the example below which should output and/or test the value of UNIQUE_FILENAME when run in any mode.

ASIDE: I've written this example as both documentation and test script... where should it live?

How to use Environment Variables to Configure SimDem Scripts

It can be convenient to have a SimDem script that creates a number of environment variables for use in other scripts. This script can then be used as a prerequisite to ensure that you have a consistent environment on each execution. To set an environment variable use a command like the following:

MY_VARIABLE="My value"

You can use bash commands to create unique strings too:

UNIQUE_FILENAME=my_filename_$(date +%Y-%m-%d-%H)

If you want to avoid overwriting values provided by the SimDem user, you can easily do so with a value check:

if [ -z "$ANOTHER_UNIQUE_FILENAME" ]; then $ANOTHER_UNIQUE_FILENAME = my_filename_$(date +%Y-%m-%d-%H); fi

Validation

A validation section is useful in two ways. It can be used to ensure we output the final results when executing in a tutorial/demo environment and it can be used to test whether a prerequisite file needs to be run. For example:

if [ -z "$UNIQUE_FILENAME" ]; echo "We need to provide or generate a unique filename"; else "UNIQUE_FILENAME=$UNIQUE_FILENAME"; fi

Results:

UNIQUE_FILENAME=my_filename_yyyy-mm-dd-hh

[lastcoolnameleft]

To answer your aside question: I've put all examples here. We can change it later, but for now it works. https://github.com/Azure/simdem/tree/simdem2/examples

Regarding implementing validation:

• What modes do you expect validation to be implemented?
• What is the expected behavior if validation passes?
  • Is the expected behavior different per mode?
• What is the expected behavior if validation fails?
  • Is the expected behavior different per mode?

[SorraTheOrc]

You are looking at it the wrong way around. The validation section is just a normal part of the document, with one exception (see below). Just treat it as any other section in all modes. The one exception is to establish whether we need to run a prerequisite or not. Here the validation section allows us to prevent the need to run a prerequisite multiple times when it is defined as a prerequisite in multiple documents. If all validation tests pass, prerequisite has already been run. Get Outlook for Android<https://aka.ms/ghei36>

…

________________________________ From: Tommy Falgout <notifications@github.com> Sent: Saturday, March 3, 2018 3:16:06 PM To: Azure/simdem Cc: Ross Gardler; Author Subject: Re: [Azure/simdem] SimDem2: Validation section not run (#100) To answer your aside question: I've put all examples here. We can change it later, but for now it works. https://github.com/Azure/simdem/tree/simdem2/examples<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fsimdem%2Ftree%2Fsimdem2%2Fexamples&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=qcxk8wgdozuBxYm0qkEpiBhnI7ADyozJI9wqwtnn%2B0c%3D&reserved=0> Regarding implementing validation: * What modes do you expect validation to be implemented? * What is the expected behavior if validation passes? * Is the expected behavior different per mode? * What is the expected behavior if validation fails? * Is the expected behavior different per mode? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fsimdem%2Fissues%2F100%23issuecomment-370187609&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=%2FSgEhuBVtRqQp1IPdJoby74Nddn6zkw4bevmgLIU8S8%3D&reserved=0>, or mute the thread<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAPRgKJ7wQZNQ38bFzY9UO0VidWbv4brks5tayQ2gaJpZM4SRPx3&data=04%7C01%7Cross.gardler%40microsoft.com%7Cf5b3cf1f58084c0cddc008d5815cbf21%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636557157704843685%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwifQ%3D%3D%7C-1&sdata=EiUCpnKiYNj60be5EL%2BzSuWGN1%2FPPG3ZhDPCRjx66rs%3D&reserved=0>.

[lastcoolnameleft]

Ah, ok. I was thinking that Validation is a section that validates the entire document completed successfully.

Let me mull over this change as I will probably need to pass the "mode" variable into the parser so that it only treats "# Validation" special if it's a prerequisite.

[lastcoolnameleft]

Correction: I will need to pass "is_prerequisite" into the parser, so that it knows if it should handle the validation section. Otherwise, it should just treat it as a regular body section.

[lastcoolnameleft]

@rgardler Can you validate it works according to spec? I've added the following commit to the simdem2 branch which should fix the issue.

c1c7f99

[SorraTheOrc]

Confirmed... working as expected, thanks. Leaving this open (but dropping priority) as a reminder for me to move the example into docs.