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

Discussion forum for all Windows batch related topics.

Moderator: DosItHelp

Post Reply
Message
Author
siberia-man
Posts: 126
Joined: 26 Dec 2013 09:28
Contact:

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

#1 Post by siberia-man » 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 (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
Last edited by siberia-man on 07 Aug 2019 12:03, edited 1 time in total.

aGerman
Expert
Posts: 3673
Joined: 22 Jan 2010 18:01
Location: Germany

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

#2 Post by aGerman » 31 Oct 2016 08:04

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

siberia-man
Posts: 126
Joined: 26 Dec 2013 09:28
Contact:

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

#3 Post by siberia-man » 31 Oct 2016 08:18

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

aGerman
Expert
Posts: 3673
Joined: 22 Jan 2010 18:01
Location: Germany

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

#4 Post by aGerman » 31 Oct 2016 08:31

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>

siberia-man
Posts: 126
Joined: 26 Dec 2013 09:28
Contact:

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

#5 Post by siberia-man » 31 Oct 2016 09:04

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.

aGerman
Expert
Posts: 3673
Joined: 22 Jan 2010 18:01
Location: Germany

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

#6 Post by aGerman » 31 Oct 2016 09:44

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

Post Reply