Page 1 of 1

PIE: new documentation format for batch scripts. Concept and implementation

Posted: 30 Oct 2016 13:30
by siberia-man
Preamble

This idea came when I desibed to develop a script creating some kind of sandbox for the application I am working on my job. It is java application working both win and unix. The main purpose was to settle the application into the filesystem looking like unix FS. The first version was written as HTA and left without supporting for long time. Recently I decided to revive it and rewrite as a command line tool. I did it and invented new approach in formatting documentation for batch scripts. It looks like Perl POD (the Plain Old Documentation) but it allows to display texts, echo variables and execute batch commands on the fly. I decided to call it PIE (the Plain or Primitive, Impressive and Executable documentation format).

Introduction

Well known fact: the documenting of batch scripts is a bit pain.

The simplest way is echoing some text but it is pain.

There are comments (using "rem" and "::"). Comments allow writing of documentation without problems in text echoing. But there is no simple and ready-in-use way to print something dynamically (for exxample, some variables etc).

Heredoc is good approach but it is available only through the tricky way (http://www.dostips.com/forum/viewtopic.php?f=3&t=6493).

In this topic I am suggesting PIE, new and simple syntax for writing documentation in batch scripts.

As it has been said above PIE stands for Plain, Impressive and Executable documentation format. Its roots come from Perl POD (Plain Old Documentation). But there is less markup and the syntax is more batch scripting oriented.

Description

PIE consists of few things

Ordinary text
There is any text you are typing. It will be printed as is without any changes.

Substitution
Environment variables, like %PATH%; replaceable variables in the form as %[format]name (those we us in "FOR" command like %a etc).

Command
This is the main thing of PIE. Using pie-commands we can extend documentation. Let's look at the source code of the cmdpie.bat file implementing the concept of PIE.

Source

Source codes can be found by the links:
Standalone PIE: https://github.com/ildar-shaimordanov/c ... cmdpie.bat
Working example: https://github.com/ildar-shaimordanov/c ... /fsbox.bat

Welcome for baking, testing scripts and discussion.

Code: Select all

@echo off

if not "%~1" == "" goto :pie

call :pie BAKE "%~f0"
goto :EOF

:: ========================================================================

::PIE-BEGIN	BAKE
NAME

  pie - the Plain, Impressive, Executable documentation format


DESCRIPTION

  Pie is a simple-in-use markup language used for writing documentation 
  for batch scripts in Windows DOS.

  Pie consists of few basic things: ordinary text, substitutions and 
  commands.

Ordinary text
  The majority of text in the documentation is the ordinary text blocks 
  like this one. You simply write it as is, without any markup.

Substitution
  It is any text surrounded with the percent characters "%" or the 
  replaceable variables in the form "%[format]name", where "name" is a 
  single letter, "format" is an option expanding the variable. For 
  details, see "FOR /?". Substitutions are used together with commands.

Command
  A command is the specially formatted string that turns some features. 
  Usually it is beginning or ending of Pie, calling some DOS commands or 
  echoing some text with substitution.

  All commands start with the double colon "::" followed by an identifier 
  and followed by some parameters separated with whitespaces.

There are commands:
::PIE-ECHO	"  ::PIE-BEGIN label"
::PIE-ECHO	"  ::PIE-END [STOP]"

::PIE-ECHO	"  ::PIE-ECHO text"
::PIE-ECHO	"  ::PIE-CALL command"

::PIE-ECHO	"  ::PIE-SETFILE "filename""
::PIE-ECHO	"  ::PIE-OPENFILE"
::PIE-ECHO	"  ::PIE-CREATEFILE"

::PIE-ECHO	"  ::PIE-COMMENT-BEGIN"
::PIE-ECHO	"  ::PIE-COMMENT-END"

The detailed explanation of each pie-command is given below.

::PIE-ECHO	"  ::PIE-BEGIN label"
  "::PIE-BEGIN" starts Pie itself. The mandatory "label" is used to 
  identify Pie. This allows to have more than one Pie within a single 
  file.

::PIE-ECHO	"  ::PIE-END [STOP]"
  "::PIE-END" ends the current Pie block. If the argument "STOP" is 
  specified, processing of the rest of input file will not be continued. 

::PIE-ECHO	"  ::PIE-ECHO text"
  "::PIE-ECHO" prints the specified "text". Any occurance of environment 
  or replaceable variables will be substituted. If the echoed text 
  contains the percent characters "%" they should be double to display.

::PIE-ECHO	"  ::PIE-CALL command"
  "::PIE-CALL" calls the specified command or commands. Substitution is 
  also available.

::PIE-ECHO	"  ::PIE-SETFILE "filename""
  "::PIE-SETFILE" specifies a name of a file to write to. The filename can 
  be relative or absolute file path or can contain environment variables 
  that will be substituted too. The text it is expanded removing leading 
  and trailing quotes "" around the text. This gives ability to indent the 
  echoed text. 

::PIE-ECHO	"  ::PIE-OPENFILE"
::PIE-ECHO	"  ::PIE-CREATEFILE"
  "::PIE-OPENFILE" and "::PIE-CREATEFILE" initialize writing to the file 
  specified by the command "::PIE-SETFILE". New data are appended to the 
  end of the file. The difference between these commands is that 
  "::PIE-CREATEFILE" truncates the file before the real writing. 

  Setting of the file and its opening are separated to enable additional 
  commands between them (for example, logging of an action before 
  performing it).

::PIE-ECHO	"  ::PIE-COMMENT-BEGIN"
::PIE-ECHO	"  ::PIE-COMMENT-END"
  "::PIE-COMMENT-BEGIN" starts and "::PIE-COMMENT-END" ends a block of 
  comments. This could be useful, if you need to escape printing of some 
  text but its removing from the file is unwanted.

AUTHORS

  Copyright (C) 2016, Ildar Shaimordanov

::PIE-END

:: ========================================================================

:pie
setlocal enabledelayedexpansion

set "pie-enabled="
set "pie-filename="
set "pie-openfile="
set "pie-comment="

for /f "delims=] tokens=1,*" %%r in ( '
	find /n /v "" "%~f2" 
' ) do for /f "tokens=1,2,*" %%a in (
	"LINE %%s"
) do if not defined pie-enabled (
	if "%%b %%~c" == "::PIE-BEGIN %~1" set "pie-enabled=1"
) else if "%%b" == "::PIE-SETFILE" (
	call set "pie-filename=%%~c"
	set "pie-openfile="
) else if "%%b" == "::PIE-OPENFILE" (
	set "pie-openfile=1"
) else if "%%b" == "::PIE-CREATEFILE" (
	set "pie-openfile=1"
	if "%%~c" == "NEW" type nul >"!pie-filename!" || exit /b 1
) else if "%%b" == "::PIE-COMMENT-BEGIN" (
	set "pie-comment=1"
) else if "%%b" == "::PIE-COMMENT-END" (
	set "pie-comment="
) else if "%%b" == "::PIE-END" (
	set "pie-enabled="
	set "pie-filename="
	set "pie-openfile="
	if "%%~c" == "STOP" (
		endlocal
		goto :EOF
	)
) else if not defined pie-comment (
	if defined pie-openfile (
		>>"!pie-filename!" (
			setlocal disabledelayedexpansion
			if "%%b" == "::PIE-ECHO" (
				call echo:%%~c
			) else if "%%b" == "::PIE-CALL" (
				call %%c
			) else (
				echo:%%s
			)
			endlocal
		) || exit /b 1
	) else (
		(
			setlocal disabledelayedexpansion
			if "%%b" == "::PIE-ECHO" (
				call echo:%%~c
			) else if "%%b" == "::PIE-CALL" (
				call %%c
			) else (
				echo:%%s
			)
			endlocal
		) || exit /b 1
	)
)

endlocal
goto :EOF

:: ========================================================================

:: EOF

Re: PIE: new documentation format for batch scripts. Concept and implementation

Posted: 31 Oct 2016 08:04
by aGerman
I don't understand the syntax :oops:

I have cmdpie.bat and fsbox.bat in the same directory. I opened a cmd prompt and navigated to the directory.
How should the command lines look like in order to access certain phrases of the documentation in fsbox.bat?

Steffen

Re: PIE: new documentation format for batch scripts. Concept and implementation

Posted: 31 Oct 2016 08:18
by siberia-man
Shame to me. If you don't understand, i haven't explained it well.

cmdpie.bat is documented with PIE. You can run it and compare output with PIE.
Let me time to reread what I have written before and I give more explanation.

Regarding fsbox.bat.
It is formatted with PIE but it is executable part creating new files in a sandbox. In fact, fsbox.bat is the script itself and some portion of another scripts that will be copied on a disk. PIE is a glue between of them.

Code: Select all

cmdpie HELP fsbox.bat

Re: PIE: new documentation format for batch scripts. Concept and implementation

Posted: 31 Oct 2016 08:31
by aGerman
Thanks for your explanation.
Probably I still miss something. Shouldn't that print the content of the ::PIE-BEGIN HELP phrase?

Code: Select all

C:\Users\steffen\Desktop>dir cmdpie.bat fsbox.bat
 Datenträger in Laufwerk C: ist OS
 Volumeseriennummer: E643-135D

 Verzeichnis von C:\Users\steffen\Desktop

30.10.2016  21:51             5.468 cmdpie.bat

 Verzeichnis von C:\Users\steffen\Desktop

31.10.2016  14:38            15.711 fsbox.bat
               2 Datei(en),         21.179 Bytes
               0 Verzeichnis(se),  8.737.202.176 Bytes frei

C:\Users\steffen\Desktop>cmdpie help fsbox.bat

C:\Users\steffen\Desktop>cmdpie HELP fsbox.bat

C:\Users\steffen\Desktop>cmdpie.bat HELP fsbox.bat

C:\Users\steffen\Desktop>

Re: PIE: new documentation format for batch scripts. Concept and implementation

Posted: 31 Oct 2016 09:04
by siberia-man
Definitely, I don't understand something. Each new Windows instance is like a separate operating system. Couple of hours ago the user of the Russian Grey forum has reported that on his PC the results of assoc/ftype commands differ if the arguments are quoted and not.

Please check, if you have the latest versions of these scripts. Also try to convert unix line endings (LF) to windows line ending (CRLF). I have downloaded both files and checked with LF and CRLF. In both cases it does work properly. Most probably it is not true in your case because of different Windows.

Re: PIE: new documentation format for batch scripts. Concept and implementation

Posted: 31 Oct 2016 09:44
by aGerman

Code: Select all

C:\Users\steffen\Desktop>cmdpie HELP fsbox.bat
Usage: cmdpie OPTIONS

Create sandbox for UNIX like filesystem structure

-p PATH       set a directory where the sandbox will be installed
-d DISK       set a virtual drive to which a path will be assigned
-n NAME       set a name of the sandbox
-f DIRS       set a list of directories whcih will be created

--install     start installation
--persistent  install persistent virtual drive
--readonly    set read only attribute over all installed files

--help        display this help and exit
--version     display version information and exit

C:\Users\steffen\Desktop>

Even if there were the correct line endings CRLF before, I again copied the scripts from github. Now it works like a charme :D
I have no idea what was going wrong before. Thanks again for your support!

Steffen