*********************
   "$d_bin"'fileops.sh' - library of handy bash functions for file needs
      # do NOT run this directly!, use, for example, "$d_bin"'fileops run.sh'
   +-----+
   Setup 
   02Jun2021 I have assigned not-so-random numbers to FILE with read loops 
      to avoid "crossover effects of nesting" of this bash library.  
   +-----+
   fprintf - LMDE doesn't have this!! not worth doing...
   +-----+
   [symbol, function] symbol codes - to prevent "cross-over" between library calls 
   code_get(no args)  - generate a list of existing library codes 
      to check against new random codes
   code_make(fractionSeed)  - generate a code for [symbol, function] not already used in libraries
   +-----+
   [dir, pth] basic functions 
      I do NOT yet have [p,d][new, ovr, add, etc] distinctions that I created in QNial!
   chmod_Howell()  - change standard access rights
      permissions [d_web, online] : root - don't touch!!, dir permissions = 755, file = 644
   chown_Howell(d_target)  - change standard access rights 
      permissions [d_web, online] : root - don't touch!!, dir permissions = 755, file = 644
   pth_get_fnam(pth)  - get fname with extension
   pth_get_fnmNoExt()  - get fname without extension
   pth_get_ext()  - get extension without fname from pth
   fNam_get_ext(fNam)  - retrieve fName extension (NOT pth!)
   pth_get_dir(pth)  - retrieve dir holding pth
   pth_get_dArchive(pth)  - ensures that z_Archive is created 
      if it doesn't exist, returns sArchive
   pth_get_pArchive(pth)  - returns pArc for pth, or 0 for error, assuming archive is dated
      ensures that z_Archive is created if it doesn't exist, 
   pth_getLocal_pArchive(pth)  - returns pArc for pth, or 0 for error
      end with ' archive.<extension>'
      pinn_archiveLocal ensures that z_Archive is created if it doesn't exist 
   pth_get_byteSize(pth) - res ipsa loquitor
   dir_fpat_fsize_compare_optr_process(pth fsizeCompare optr) optr pthL based on fSizes (bytes)
      example :  rm files <200 bytes (probably no corrections to make,rule of thumb only)
   +-----+
   SAFE [backup, restore] cart [pth, dir]s
   pinn_backupDatedTo_zArchive(pInn)  - backup file to a z_Archive pre-fNam-dated now (obsolete)
        zArchive is [specific, with respect] to each path, it is not an overall zArchive  
        Notice that there is no error output (write) - must be handeled by the calling optr! 
   pinn_archiveLocal(pInn)  - backup of form "$dArc951$fNoX951 archive.$fExt951"
   pinn_archiveLocalRm(pInn)  - current file : archive then rm (clear) 
   pBadL_archive_pArchiveL_restore(pBadL)  - archiveDated pBadL, restore archives as current
   +-----+
   timestamp changes 
   pinn_timeAcsTo_timeUnix()  - for lftp uploads
   pinn_timeModTo_timeUnix()  - for lftp uploads
   pinn_timeModTo_pout()  - set pout timeMod to that of pinn
      just use touch  --reference="$pinn"  "$pout"
   pinn_timeChgTo_timeUnix()  - for lftp uploads
   pinn_timeModTo_yymmddhms()  - archive in current dir
      trailing date so fNam sorts alphabetically with function
   pinn_timeChgTo_yymmddhms()  - archive in current dir
      trailing date so fNam sorts alphabetically with function
   +-----+
   rename a selection of files in a dir
   dir_renameFileL()  - rename an extracted list of files in dir using [sed, mv]
   +-----+
   str in dir[,L] - find str in dir[,L], results to pout  
      pout is often a temporary file for further processing  
   dir_fextn_pthLExclud_findPthL_pout - find str in files with fextn in dir, results to pout  
        skips [file, dir]s, eg "z_Old\|z_Archive\|webSite maintain \|file_ops.ndf"
        shows only subDirFname of $dir385
   pinnL_str_extractPthLWithStr_pout()  - grep 'st' --with-file-name, lineNum
      must escape problematic chrs in str,  
   pinnL_str_extractCountPathsWithStrTo_pout()  - [txtLines with str of pinnL]
         write [str count, path]L to pout
   pinnL_pStrL_getPthsWithStrL_pout()  - [txtLines with str of pinnL]
         write [str count, path]L to pout
   pInnL_pChrP_get_pOut(pInnL pChrP pOut)  - extract strL with chr[start, end] on same line
      reverse line each item
   +-----+
   sed  - convert between [human, code] forms of text
      Hum =human         : human-readable, non-encoded format 
      Cde =code          : safe for sed expressions like "s|$strOld|$strNew|g"
      Apo =apostrophe '  : special "quote-enclosed" case, as apo can't be apo-enclosed
      Quo =quotation  "  : special "apostophe-enclosed" case, 
                           not used much here as almost all sed expressions are apo-enclosed
   sedChrL_legend  - chrL of special chrs that have to be encoded for sed 
   sed[x]To[y] - sedExpressions to [, de]-code chrSedL between [human, encoded] formats
   strHum_sed_strCde()  - convert str format [human -> code] 
   strCde_sed_strHum()  - convert str format [code -> human]  
   str_strP_replace()  - escape str[Old, New] then replace strOld with strNew in apo str
      str[, P] are escaped if bolChrCd == 1, returns same format as input
   +-----+
   [strP, pStrP] sed [search, replace] in pth[L], where strP of form "$strOld"$'\t$strNew"   
   pHum_sed_pCde()  - convert pth format [human -> code], eg for pStrP  
      pHum must NOT already be escaped! 
      pCde is overwritten
   pCde_sed_pHum()  - convert pth format [code -> human]  
      pCde must NOT already be un-escaped! 
      pCde is overwritten
   +-----+
   [strP, pStrP] sed [search, replace] in pth[L], using [, not] encoded [strP, pStrP]
   +-----+
   Original povr[,L]_strP_replace()
   povr_strP_replace_run(povr strP)  - assumes pre-[arXiv, code, strP] checks
   povr_strP_replace(bolArXiv bolChrCd povr strP) sed replace encoded (strP, povr)
   povrL_pStrP_replace(bolArXiv bolChrCd povrL pStrP) sed replace encoded (pStrP, povrL)
      bolChrCd=[0,1] for whether text is already encoded, simply use an actual tab in script str
      WARNING! all pStrP cannot have \t other than to separate!
   +-----+
   pinn[,L]_strP_replace_pTmp(pinn strP pout) parallel series, 12Jan2024 :  
      this targets extraction of links from webPages, for which the file locations not needed
   pinn_strP_replace_pout_run(pinn strP pout)  - assumes pre-[arXiv, code, strP] checks
   pinn_strP_replace_pout(bolChrCd pinn strP pout) sed replace encoded (strP, pinn)
   pinnL_pStrP_replace_dOut(bolChrCd pinnL pStrP dOut) sed replace encoded (pStrP, pinnL)
      PROBLEM - same fnames will be over-written in dOut
   +-----+
   [rgxP, pRgxP] sed [search, replace] in pth[L], rgxP of form "$rgxFind"$'\t$rgxReplace"   
      unlike strP, rgxP uses "pure sed" expressions that must NOT be encoded!
      uses triplicate form 
   povr_rgxP_replace(bolArXiv bolChrCd povr rgxP) sed replace encoded (rgxP, povr)
   povrL_pRgxP_replace(bolArXiv bolChrCd povrL pRgxP) sed replace encoded (pRgxP, povrL)
      sed replaces each [strOld, strNew] in each povr, same pRgxP
      WARNING! all pRgxP cannot have \t other than to separate!
      all [povrL, pRgxPL] are escaped in [povr[L_rgxP_replace(), povr_pRgxP_replace()
   povrL_pTypRgxT_replace(type povrL pTypXprP) uses [(encoded) str, rgx] for sed 
      type, either 'strP ' or 'rgxP '  
      trailing T in function name denotes "triple" (rather than pair)
      pTypXprT: 
         strP of form "strOld\tstrNew"      - expressions may [, not] be encoded
         rgxP of form "rgxFind\trgxReplace" - expressions must NOT    be encoded!
   +-----+
   lines[Old, New] in path[,L]  - 
        auto-create 'z_Archive' subDir if necessary 
        -i option for [capital, small] insensitive - might not want this?
        forwardSlashes will likely be in str[Inn,Out], 
        note that the `| c is used 
           that could also cause problems, but hopefully not in paths!
   pinnL_lineIdx_strTst_split_pYes_pNo(pinnL lineIdx strTst pYes pNo pDifYes pDifNo) 
      split pinnL to [pYes, pNo] according to strTst in line# lineIdx
      cut takes characters #1 through strTst_len333 (could be generalized ...)
   pinnL_getBadLine1_poutL(pinnL poutL)  - 
      list files with only one space 1st line '<!-- /home/bill/howell'
   pinn_getLinseq_povr()  - extract a sequence of lines between [strt, endd] markers in pTxt
      default use of ["^#strt:","^#endd:"]=[strt, endd] markers in pTxt (don't use <> etc!!!)
      for now assumes only 1 [strt, endd]
   povr_pPLines_replace()  - in povr, replaces lines of pOld with pNew
      [pOld, pNew] do NOT generally have the same number of lines
      [pOld, pNew] must NOT have [punctuation, extra spaces]
      very simple exact match of lines - no regular expressions or codes!!! (yet)
      will fail if the first line of pOld is repeated within the line sequence
   povrL_pPLstLines_replace()  - for each povr, replaces each (pLineLOld with pLineLNew)
      pLlineL[Old, New]197 must have the same number of lines, no [punctuation, extra spaces]
      very simple exact match of lines - no regular expressions or codes!!!
   povr_pRgxL_cat_saveLines()  - saves lineSeq to pRgxL 
       used by pinn_sedFndGetPut_povr: find matching lineSeq of pinn, outputs new linSeq
   povr_pRgxL_cat()  - catenates lines of povr that regex match pRgxL (lineSeq) 
      used by pinn_sedFndGetPut_povr: find matching lineSeq of pinn, outputs new linSeq
      pRgxL must [escape, []] sed special chrs 
   pinn_sedFndGetPut_povr()  - finds matching sequences of lines of pinn, outputs new linSeq
      (Fnd=Find, rgx= regular expression, linSeq = line sequence)
      pFnd - line-level rgxL [search, replace] to test if each line in a pinn linSeq matches 
      pGet - line-level rgxL that extracts components of each line into a strLst
      pPut - multi-line rgxL stating how components are to be combined into output lines
   rm_lineSeq_start_to_end()  - cp file, then remove all occurrences of a sequence of lines
   +-----+
   bash-> python ports 
   pBash_pSymL_dPy_stripQuotes_pPython() - strip "$..." from syms in pBash
   +-----+
   wrd[Old, New] replace in path[,L] 
        MUCH safer than str versions!!, creates 'z_Archive' subDir if necessary
        -i option for [capital, small] insensitive - might not want this?
   forwardSlashes will likely be in str[Inn,Out], note that the `| c is used 
   	that could also cause problems, but hopefully not in paths!
   02Mar2023 tests of flagWrd: specialChrs [ \^\$'",*,\\[]{}-\n] 
   flagWrd_test()  
   flagSpecChrs_test()  - must escape ^$[]{}\, enclose all with `' except `' which uses `"
   see bash dir "$d_bin"'code develop/' 
   flagWrd_test()  
   flagSpecChrs_test()  - must escape ^$[]{}\, enclose all with `' except `' which uses `"
      still doesn't work with `'  
   povr_wrdP_replace()  - z_Archive povr, wrdP=(wrdOld, wrdNew) replace in povr 
      error if wrds are not actually words!
      01Mar2023 what about case sensitivity?
   povr_wrdPL_replace() - as listed in the lst of files wrdPL 
   povrL_wrdP_replace() - each povrL [z_Archive, (wrdOld, wrdNew), over-write]
   +-----+
   Paragraph  - contiguous lines, with line breaks but no whitespace lines
   transcript_unite_each_paragraph  - res ipsa loquitor
   +-----+
   path[,L] - check HowellLibrarys for (optrName  arg1  arg2) based on " IS OP  " definitions   
   dirSrc_fbase_fxtn_str_appendTo_pStrUse()  - append list of uses of optrNam 
      in "$dirSrc" to pStrUse
   fNdfL_subDirRef_argOrderNum_dout()  - extract list of uses of each of pthOptrNamL 
        in each of pthL, results for each OptrNam are saved in a optrNam-specific file 
   +-----+
   path[,L] - redistributes StrUse from-str-to-Src basis  output files 
        using results from [pthSrc_subDirRef_optrNam_getArgOrderNum_pout,
                            fNdfL_subDirRef_argOrderNum_dout]   
   fSrc_pStrUse_appendTo_pSrcChk()  - redistributes strUse from-str-to-Src basis  
        append lines in pthLStrUse from fnamSrc to pthSrcStrUse  
   pLibSrcPthVarL_pLibStrUseL_appendTo_pLSrcChk()  - 
        redistributes StrUse from-str-to-Src basis output files  
        using results from [pthSrc_subDirRef_optrNam_getArgOrderNum_pout, 
           fNdfL_subDirRef_argOrderNum_dout]   
        append lines in pthLStrUse from fnamSrc to pthSrcStrUse  
        nor arguments - [global, internal] variables only
   pOvrL_pStrP_pIns_replaceLines(pOvrL pStrP pIns) replace ONE strPStrEnd linSeq in each pOvrL
      pStrP MUST be properly escaped (problem for arbitrary pStrP -> need pHum_sed_pCde)
      n[Strt, Endd] are set manually: to fix "addition" in prodn version instead of "replace"