README.md

   1
   2 README of shlib
   3
   4   Copyright (C) 2022- Free Software Foundation, Inc.
   5
   6   Copying and distribution of this file, with or without modification,
   7 are permitted in any medium without royalty provided the copyright
   8   notice and this notice are preserved.
   9
  10 The following contributions warranted legal paper exchanges with the
  11 Free Software Foundation.
  12
  13
  14 This is the README file for the shlib distribution.
  15 shlib include many script lib files, and some utils program.
  16
  17
  18 # instroduction
  19 ===============
  20
  21         shlib is a bash shell script library project. it allows programmer
  22 to use shell script code as a library.
  23         normally, script does not have a public dir to store global lib
  24 files, we shoud use absolute path to 'souce' it. by using shlib, you
  25 can install xxx.shlib to global shlib path, and use it like
  26 'include xxx.shlib'. it provide a conception of system global shell
  27 script lib.
  28
  29         there is something should pay attention on debug string output when
  30 we invoke it in a while loop with stdio re-direction.
  31
  32 stdout=250
  33 exec 250 >& 1
  34 while true; do
  35     echo output to file.txt
  36     echo output as a debug info to console > $stdout
  37 done > file.txt
  38
  39         we should force to re-direct debug string to stdout file handler of
  40 parent process that saved at first. absolute this output method as some
  41 functions in shlib, we can re-use it next time by invoking 'dbgout xxxxxxx'
  42 in stdio.shlib. and it is more easier then orignal system command.
  43         that's the meaning of code re-use as a library for shell script.
  44
  45         when i wrote other programs by shell script, i put the public code
  46 into a shlib file as a function feature. it can be re-used, and it let
  47 the script programming more easier. some of usefull code can be share with
  48 other developers, and shlib provide the general method to 'source' your
  49 lib code.
  50
  51         shell script is not a fully-featured program languge. it has many weekness
  52 on some thing like paramter variable type. the purpose of shlib and some other
  53 pkg like 'dvar' is used to let shell script to be a normal program language,
  54 and keep its command line feature at the same time.
  55         shlib is a pioneer on new sh-script language feature. some of them can be
  56 inegerated into shell program, or developed as a binary program when it is widly
  57 used.
  58
  59
  60 # package dirs and files
  61 ========================
  62
  63     put some gnu doc file into doc dir.
  64 @ bin, shell script program dir.
  65 @ shlib, shell script library dir.
  66 @ src, some of feature should be implemented by c/c++, and put the src code here.
  67 @ doc/design-doc, the code design doc for shlib.
  68 @ doc/UM.<type>.<encoding>, user manual doc of shlib.
  69 @ doc, contains copyright、author、changelog ... etc, that a gnu project
  70 needed.
  71
  72
  73 # features
  74 ==========
  75
  76         in this version of shlib, it provide those features:
  77
  78 V0.1.0
  79 @ shlibinc, the shlib include file by '. shlibinc' before include any other
  80   shlibs.
  81 @ shlibopt, config shlib function like command of 'shopt'. althouth it is nearly
  82   blank, but it's an interface for shlib global paramter setting when it is
  83   needed.
  84 @ gplib.shlib, general perpurse lib, it used to support function invoking with
  85   '[ param ]' as the parameter string, and use freturn to return with a string
  86   stored in env var. and some other usefull functions.
  87 @ stdio.shlib, save program stdio file handler, and output debug string
  88   to stdio channel of program, but not the sub process stdout, that maybe
  89   re-directed by developer. it seperate data string output and terminal info
  90   string output.
  91   it also provide different kind of debug info string, like linux kernal.
  92 @ dbgout.shlib, it's parted from stdio.shlib. some function for debug purpose
  93 output with frequently used functions.
  94
  95
  96 # animates
  97 ===========
  98
  99     user manual doc like a static dictionary data for developer, comparing with
 100 this, animates is more active and direct. but video file is too large for tutorial,
 101 gif is smaller. for pure char environment on shell console, there is a software
 102 called ttyrec, it record chars on console, and interval time between every input.
 103 the .ttyrec file can be displayed on console like a video record.
 104     In path of doc/tutorial, there are some files with .ttyrec surfix. it's the
 105 record data of ttyrec program. before using, you will install ttyrec pkg first.
 106
 107 sudo apt-get install ttyrec
 108
 109     or, install it by src code.
 110     when you want to see the tutorial, type this command :
 111
 112 ttyplay xxx.ttyrec
 113
 114     ttyplay can display command line operation that has been recorded.
 115
 116
 117 # goals
 118 =======
 119
 120     shlib provide functions when we write script programs.
 121
 122 @ lib support.
 123     code can be re-used as a library through 'include xxx.shlib'. and the shlib can
 124 provide a set of function feature, and it let script code more esaier as a normal
 125 program language with shell script.
 126 @ data type support.
 127     shell program based on command line, all paramter is string. append data type
 128 support, to implement more feature like a normal program language.
 129 @ structured data support.
 130     environment variable is just a single variable. it's the weekness of shell script
 131 on processing structured data. some application need to use structured data, for
 132 example, a xml dispatching program dispatch xml file to some structured data for other
 133 programs.
 134 @ data share between programs.
 135
 136     shell is a language based on command line, many feature is implemnetd by seperated
 137 program process. for example grep, and sed. the default method for data transfer is pipe
 138 operation. but sometimes we need to fransfer or share data as a variable. so, it need
 139 a shared variable to exchange data between two programs. for example, an xml file
 140 dispatching program dispatched a xml file, and the method of data sharing with other
 141 programs is that store dispathing data in shared var in global system. then other program
 142 can use dispatched xml file data directly in program. that's the c-code-style method
 143 to write program.
 144
 145 @ large data processing imporve. grep, sed, or other regex applications process text
 146 with whole data block, and output data at the same time. the program mapfile has
 147 improve this on pipe data read operation. it's usefull when a large src code file
 148 is processing by grep or sed, and it can dispaly result info in a short time.
 149 @ gui program support.
 150     an other weekness of shell script is graphic ui program. the program 'dialog'
 151 provide a methed to implemnet it, but it still can't operate with controllers.
 152 @ I hope that shell script can be used for writing util programs easily and simply
 153 as a RAD program.
 154
 155         shell script is a normal script, maybe not called language. by appending shlib,
 156 and some pkg of other features, it can be used as a normal program language, and it
 157 can be used as a command line also.
 158
 159
 160 # other packages
 161 ================
 162
 163         shlib is borned when i write pkg named 'dvar'. it is a pkg to allow shell script to
 164 use variable as a filesystem data file. it can share global data in system, and it
 165 can orgnize data with a struct. it provide the implementation of data type and variable
 166 defination. use dvar and shlib, shell script can be used as a normal program language.
 167
 168