PIE: new documentation format for batch scripts. Concept and implementation
Posted: 30 Oct 2016 13:30
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.
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
