BRP(1)                      General Commands Manual                     BRP(1)



NAME
       brp - line oriented universal preprocesser using posix-shell

SYNOPSIS
       brp [-hHQsS]

TL;DR
       ~$ brp -s | tee src.sh.c
       ~$ sh src.sh.c -a   #>>output 'hw'
       ~$ sh src.sh.c -a -b -a       #>>hw, exec ls, hw


OPTIONS
       -hHV   usage, version

       -Q     output corecode

       -sS    output sample

DESCRIPTION
       brp  is  portable  preprocesser.  code  is separated with 2 parts, main
       code(#inc...#END) and option code (//SH_OP ...). workflow is:

         1: exec src as shell script. ~$ sh src.sh.c -a
         2: main code searches regex suitable line (dfl: //SH_OP, /*SH_OP etc)
         3: read hitline and save string to vars ($Ca, $Cb, $C... etc)
         4: exec option code if you use -a >> eval "$Ca", -z >> eval "$Cz"


   main code
       brp exec the head 10 line code as shell script and exit.

            #inc...
            C='^[/][/*]SH_'    ; ...
                 ...#END

       main code holds regex string var `C` to get option code line. this  var
       is used as:

            ~$ cat src.sh.c | sed -ne "/$C/p"       #BRE-reg.

       and gather //SH_OP or //SH_??? etc. linetop #include... is assert() for
       c/cpp (~$ cc src.sh.c #stop) so you can delete if you want.
       main code holds predefined option code, -w, -m. see below for details.

   option code
       you can expand the brp working with option code.
            //SH_OP  b: z=100;echo "good-bye $2 $Ob $1 $z $R0"
              1  2 3 4                5

       1      dfl opthead is "//SH_" or "/*SH_". see below $C.

       2      option line suffix `OP` is fixed.

       3      separate with blank char(spaces or tabs)

       4      optchar is [a-zA-Z0-9] or `_`(see below). add colon if  use  op‐
              targ

       5      write raw sh-script with ONE LINE. code is used as below.
              Cb=$(cat<<'E'
              z=100;echo "good-bye $2 $Ob $1 $z $R0"
              E
              )
              eval "$Cb"          #if -b set

       -      if you set special optchar `_`, it works only once at the script
              beginning.
              //SH_OP _ echo "preset AA";AA=1
              //SH_OP a echo "$AA"     #>>~$ sh src.sh.c -a ... disp "1"

       -      adopt new one if overlap the option setting.
              //SH_OP a echo "hw" #>> ignored. sh src.sh.c -a  -> disp "gw"
              //SH_OP a echo "gw"

   about reserved vars or other
       1-2char var names R?, C?, O? are reserved (R,C,O,Ra,R7,Cg,O5 ...).  op‐
       targ is set to $O? ( a: >> $Oa , v: >> $Ov etc)

       $R0,Rm,Rs,Rh
              orig/tMp/src/header  fname.  ($Rm  ->  src.tmp.c etc) fname uses
              topname + last suffix. eg) src.xx.yy.py3 -> ./src.py3
              original fname should avoid tmp/src/header fname.
              (sh src.c -w >> src.h / src.c ...orig destroyed)

       $C?    $Ca/$Cb etc. code buffer.
              //SH_OP a echo "$Rm"     # ~$ sh brp.sh.c -a >> disp brp.tmp.c
              //SH_OP b printf "$Ca"   # ~$ sh brp.sh.c -b >> disp echo "$Rm"
              //SH_OP c eval "$Ca"     #.. -c works as equals to -a

       $Cw    predefined -w option. uses for c-lang. you will  make  sense  of
              the work by exec.

              ~$ brp -S > src.sh.c     #sample
              ~$ sh src.sh.c -w

              1. write SH_LS - SH_ED(LS_block) to both src.h($Rh)/src.c($Rs)
              2. add HD_block to src.h, SC_block to src.c
              3. disp filename to stdout.  (src.h src.c)
              -. suffixes(LS,HD,SC,ED) are fixed

       $Cm    predefined  -m option. remove brp maincode(#inc...#END) and out‐
              put to $Rm (XX.tmp.XX). you may uses for general perpose.

       $C     comment regex. dfl is C=`^[/][/*]SH_`, //SH_xx or /*SH_yy etc.
              brp uses  linecmt  as  directive.  if  you  want  to  use  other
              pg-lang(python etc), edit srctop `C=...` directly. use BRE-reg.

              shell : C='^#ANYSTR_';   >>  #ANYSTR_LS, #ANYSTR_ED etc
              python: C='^["]["]["]MARKER_';     >> """MARKER_OP   etc
              basic : C="^[']SH_";     >> 'SH_OP etc

              $C is used as follows. escape slash / plz.
               sed -e "/${C}ED/"  ...  (bad)C='^/[/*]SH_' (good)C='^\/[/*]SH_'

       $O?    optargs. //SH_OP a: echo "$Oa"  .. ~$ sh src.sh.c -a 11 ..11

       $O     newline(\n). eg) //SH_OP a echo "a${O}b" >> disp a(\n)b

       $0,1,2 normal args. this pg uses getopts. checked opts are removed.
              eg) //SH_OP a echo "$1" #~$ sh src.sh.c -a -c 11 >> output 11

EXSAMPLE
   sample for cxx
       --- copy & paste main script ---
       #include <iostream>
       int main(void){
         std::cout << "hw" << std::endl;
       }
       //SH_OP b eval "$Cm";g++ "$Rm"; ./a.out

       ...save as `src.brp.cpp` and run ~$ sh src.brp.c -b >>> hw.

   one liner script
       this app frequency uses one liner. introduce some tips.

       //SH_OP m sed -ne "/[E]ND/{n;bl};d;:l;p;n;bl"<"$R0">"$Rm";echo "$Rm"
       >>
       sed -ne '*see below*' < "$R0" > "$Rm"
       echo "$Rm"
       >>
       cat 'foo.sh.c' | sed -ne '...' > foo.tmp.c
       echo "foo.tmp.c"

       sed command pseudocode is the follows:

       ------
       sed -ne '/[E]ND/{n;bl};d;:l;p;n;bl'
       >>
       sed -n(o print. print only when requested) -e(xpression as script)

       if (line==/END/){  .../[E]ND/
         n(ext read) ...n (if not -n opt, print nowline & readnext)
         goto label l ...b l (b=jump/goto. babc -> b abc -> goto abc)
       }
       del line (& read nextline & *goto top*) ...d (d cmd is hard worker)
       label l:       ... :l (label. ':' + 'lbl name')
       p(rint line)        ... p
       n(extline read)          ... n
       goto label l        ... b l

       ...del lines until 1st hit 'END'. print all lines until EOF.
       -------

       sed cmd is difficult but very powerful. Most requests can be solved  by
       referring to the above.

   edit string with sed/shell
       sed cant use shortest match, but shell is possible(shotest+longest).

            str="aa_bb_cc"
            echo "${str#*_}"    #>> bb_cc (match aa_ and del)
            echo "${str##*_}"   #>> cc (longet)
            echo "${str%_*}"    #>> aa_bb (from tail)
            echo "${str%%_*}"   #>> aa

       shell pattern(glob pattern) is very similar to sed-regex:
            aa_bb_cc -> a_bb_cc
            reg: s/^.//g
            sh : ${str#?}  ... any one char. reg:'.'    sh:'?'

            aa_bb_cc -> (del)
            reg: ^[.]*
            sh : ${str#*}  ... all. sh can uses wild card.

            aa_bb_cc -> aa_
            reg: [^a_]*
            sh : ${str%%[!a_]*} ... not.  reg:'^'    sh:'!'
            ...[], bracket works as same, 'one char'

            escape
            sh: ${str%123"*"*}  ... "*" uses as literal. 0123*567 -> 0

       see https://en.wikipedia.org/wiki/Glob_%28programming%29 ..or..
       ~$ man sh + input `/` + input `pattern` + enter + `n` + `shift_n`

EXIT_STATUS
       -

NOTES
       --- concept
       I wondered why to write dependencies or compile options to makefiles.
       The source code should contain all the necessary information.
       Because the programmer's will is written in it. I dont like writing
       in separate files and increasing the workflow.

       - avoid info fragmentation (script/src/header/gcc opt/ini/config etc)
       - small. avoid disturbing the main code.
       - (consider readability)
       - portable. avoid vender lockin, bashism etc.
       - low learning cost. good usage help, dont need installation etc
       - others ... see unix philosophy.


CONFORMING_TO
       posix-shell

COPYRIGHT
       Copyright (C) 2021 Momi-g
       License GPLv3+ <https://gnu.org/licenses/gpl.html>

VERSION
       2021-09-14 v1.0.2

SEE_ALSO
       https://en.wikipedia.org/wiki/Glob_%28programming%29
       http://catb.org/%7Eesr/writings/taoup/html/ch10s05.html



                                                                        BRP(1)
