shreadme

copyright_om () 
{ 
    comment "Copyright (C) 2014-2016, JYATL - Just Yet Another Testing Lab";
    comment "mailto: mcgowan (at) alum DOT mit DOT edu";
}
om_tally () 
{ 
    trace_call $*;
    om_list | sort | uniq -c
}
om_help () { echo to see OM functions, om_list; }
om_list () 
{ 
    sfg _ | awk -F_ '{ printf "object\t%s\nmethod\t%s\n", $1, $2 }'
}
om_init () 
{ 
    declare -f om_iam >/dev/null || { comment $(myname) OM_IAM is NOT a function; return 1; }
    om_iam
}
om_iam () 
{ 
    : user identifies themself as an OM object;
    set $(myname 2);
    set ${1%_init};
    report_notcalledby ${1}_init && return 1;

    : create the OM function
    eval "$1 () { om_generic $1 \$*; }"

    : every family has a list of members
    local l=${1}_list;
    declare -f $l > /dev/null 2>&1 || {
	 eval "$l () { (sfg ^${1}_; sfg _${1}$) 2>/dev/null; }";
    }
    : every family may have shell varialbles
    local v=${1}_vars;
    local V=$(UC $1)
    declare -f $v > /dev/null 2>&1 || {
	 eval "$v () { set | grep ^${V}_ 2>/dev/null; }";
    }
    : and a default help function when one doesnt exist
    local h=${1}_help;
    declare -f $h > /dev/null 2>&1 || {
	 eval "$h () { echo $1 functions, variables:; ($v; $l) | sed 's/^/  /'; }";
    }
    : shows Copyright when library is sourced.
    local f=${1}_firsttime;
    eval "$f () { copyright_${1}; unset $f; }";

    : and displays the help
    ${1}_help 
}
om_generic () 
{ 
    : ~ fun { sub arg ... };
    : prefereably executes FUN_SUB arg ...;
    : or FUN_HELP;
    : ====================================;
    local fun=$1;
    shift;
    : only when a function is first use thru the model;
    declare -f ${fun}_firsttime > /dev/null && ${fun}_firsttime;
    [[ $# -lt 1 ]] && { 
	${fun}_help 2> /dev/null;
	return
    };
    local f=${fun}_$1;
    shift;
    declare -f $f >/dev/null 2>&1 || { 
	${fun}_help 2> /dev/null;
	return
    };
    $f $*
}

copyright_report () 
{ 
    comment "Copyright (C) 2015-2016, JYATL - Just Yet Another Testing Lab";
    comment "mailto: mcgowan (at) alum DOT mit DOT edu";
}
report_init ()
{
    om_iam
}
@include report.1
report_init 1>&2

function report_emptyfile
{ 
    [[ -s $1 ]] && return 1;
    report_usage File: is empty
}
function report_isfile
{ 
    [[ -f $1 ]] || return 1;
    report_usage $1 IS a file and should not be
}
function report_needcount
{ 
    [[ $2 -ge $1 ]] && return 1;
    usage need at least $1 arg/s $(shift 2; echo $*)
}
function report_notbase
{ 
    [[ $(basename $PWD) == "$1" ]] && return 1;
    comment change to "$1" directory
}
function report_notblockspecial
{ 
    [[ -b $1 ]] && return 1;
    report_usage $1 is NOT a blockspecial file
}
function report_notcalledby
{ 
    set ${1:-/dev/null} $(myname 3) non-Existant-function;
    [[ $2 == $1 ]] && return 1;
    report_usage was NOT called by $1.
}
function report_notcharacterspecial
{ 
    [[ -c $1 ]] && return 1;
    report_usage $1 is NOT a characterspecial file
}
function report_notdirectory
{ 
    [[ -d $1 ]] && return 1;
    report_usage $1 is NOT a Directory
}
function report_notexecutable
{ 
    [[ -x $1 ]] && return 1;
    report_usage $1 is NOT an executable file
}
function report_notexisting
{ 
    [[ -e $1 ]] && return 1;
    report_usage $1 is NOT an existing file
}
function report_notfunction
{ 
    set ${1:-/dev/null};
    isfunction $1 && return 1;
    report_usage $1 is NOT a Function
}
function report_notgroupiseuid
{ 
    [[ -G $1 ]] && return 1;
    report_usage $1 is NOT a file with groupiseuid
}
function report_notlargeenough
{ 
    [[ $2 -ge $1 ]] && return 1;
    report_usage $1 $(echo 1 $1, 2 $2 $(shift 2; echo $*))
}
function report_notnonzerostring
{ 
    [[ -n $1 ]] && return 1;
    report_usage $1 is NOT a nonzerolengthstring
}
function report_notowneriseuid
{ 
    [[ -O $1 ]] && return 1;
    report_usage $1 is NOT a file with owneriseuid
}
function report_notpipe
{ 
    [[ -p /dev/stdin ]] && return 1;
    report_usage is NOT reading a pipe
}
function report_notreadable
{ 
    [[ -r $1 ]] && return 1;
    report_usage $1 is NOT a readable file
}
function report_notsetgroupid
{ 
    [[ -g $1 ]] && return 1;
    report_usage $1 is NOT a file with setgroupid
}
function report_notsetuserid
{ 
    [[ -u $1 ]] && return 1;
    report_usage $1 is NOT a file with setuserid
}
function report_notsocket
{ 
    [[ -S $1 ]] && return 1;
    report_usage $1 is NOT a socket
}
function report_notstickybitset
{ 
    [[ -k $1 ]] && return 1;
    report_usage $1 is NOT a file with its stickybitset
}
function report_notsymboliclink
{ 
    [[ -L $1 ]] && return 1;
    report_usage $1 is NOT a symboliclink
}
function report_notwritable
{ 
    [[ -w $1 ]] && return 1;
    report_usage $1 is NOT a writable file
}
function report_notzerolengthstring
{ 
    [[ -z $1 ]] && return 1;
    report_usage $1 is NOT a zerolengthstring
}
function report_usage
{ 
    comment USAGE $(myname 3): $*
}
report_functions () 
{ 
    set | awk '$2 ~ /\(\)/ { print $1 }' | grep '^report_'
}
report_nofilefrom () 
{ 
    set $(eval $*) /dev/null $*;
    [[ -f $1 ]] && return 1;
    shift;
    report_usage \'$*\' did not return a file name.
}
report_notargcount () 
{ 
    [[ $2 -ge $1 ]] && return 1;
    report_usage need at least $1 arg/s: $(shift 2; echo $*)
}
report_notcommand () 
{ 
    ignore type -a $1 && return 1;
    report_usage $1 is NOT a command
}
report_notfile () 
{ 
    [[ -f $1 ]] && return 1;
    report_usage $1 is NOT a file
}
report_notfilegreaterthanzero () 
{ 
    [[ -s $1 ]] && return 1;
    report_usage $1 is NOT a filegreaterthanzero
}
report_nottrue () 
{ 
    eval "$@" && return 1;
    report_usage $@ FAILED
}

@include shdoc.1
@include shdoc.2
@include shdoc.3
shdoc_init ()
{
   om_iam
}

shdoc () 
{ 
    : this is a shell doclib "shdoc" comment;
    : an shdoc comment is the first ":"-origin lines;
    : in the shell function, the rest being the executable.;
    for f in ${*:-$(myname)};
    do
	shd_each $f;
    done
}
shd_with () 
{ 
    : removes shd_less functions from shdoc results;
    : creating function {name}_doc for function "name";
    shdoc $* | awk '
   #                  { print "DEBUG: ", fcount, last > "/dev/stderr"; }
   $1 ~ /function/   { fcount++; last = $0; next;  }
   $1 ~ /}/ && last  { next }
   last              { print last; last = ""; fcount = 0;  }
   fcount == 0       { print }
		   '
}
function shdoc_doc {
    : this is a shell doclib "shdoc" comment;
    : an shddoc comment is the first ":"-origin lines;
    : in the shell function, the rest being the executable.;
}

shd_each () 
{ 
    report_notfunction $1 && return 1;
    report_notcalledby shdoc && return 2;
    trace_call $*;
    echo "function ${1}_doc {";
    declare -f $1 | awk '
       NR > 2 {
		if ( $1 !~ /^:/ ) exit
		else              print
	      }
	';
    echo "}"
}