Initial commit

.gitignore

@@ -0,0 +1 @@
+relics

LICENSE.md

@@ -0,0 +1,503 @@
+### GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 2.1, February 1999
+
+    Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+    51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+    
+    Everyone is permitted to copy and distribute verbatim copies
+    of this license document, but changing it is not allowed.
+
+    [This is the first released version of the Lesser GPL.  It also counts
+     as the successor of the GNU Library Public License, version 2, hence
+     the version number 2.1.]
+
+### Preamble
+
+The licenses for most software are designed to take away your freedom
+to share and change it. By contrast, the GNU General Public Licenses
+are intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.
+
+This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it. You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations
+below.
+
+When we speak of free software, we are referring to freedom of use,
+not price. Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights. These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you. You must make sure that they, too, receive or can get the source
+code. If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it. And you must show them these terms so they know their rights.
+
+We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+To protect each distributor, we want to make it very clear that there
+is no warranty for the free library. Also, if the library is modified
+by someone else and passed on, the recipients should know that what
+they have is not the original version, so that the original author's
+reputation will not be affected by problems that might be introduced
+by others.
+
+Finally, software patents pose a constant threat to the existence of
+any free program. We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder. Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License. This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License. We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+When a program is linked with a library, whether statically or using a
+shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library. The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom. The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License. It also provides other free software developers Less
+of an advantage over competing non-free programs. These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries. However, the Lesser license provides advantages in certain
+special circumstances.
+
+For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it
+becomes a de-facto standard. To achieve this, non-free programs must
+be allowed to use the library. A more frequent case is that a free
+library does the same job as widely used non-free libraries. In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software. For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+The precise terms and conditions for copying, distribution and
+modification follow. Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library". The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+**0.** This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License"). Each
+licensee is addressed as "you".
+
+A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+The "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language. (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+"Source code" for a work means the preferred form of the work for
+making modifications to it. For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control
+compilation and installation of the library.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it). Whether that is true depends on what the Library does and
+what the program that uses the Library does.
+
+**1.** You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a
+fee.
+
+**2.** You may modify your copy or copies of the Library or any
+portion of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+-   **a)** The modified work must itself be a software library.
+-   **b)** You must cause the files modified to carry prominent
+    notices stating that you changed the files and the date of
+    any change.
+-   **c)** You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+-   **d)** If a facility in the modified Library refers to a function
+    or a table of data to be supplied by an application program that
+    uses the facility, other than as an argument passed when the
+    facility is invoked, then you must make a good faith effort to
+    ensure that, in the event an application does not supply such
+    function or table, the facility still operates, and performs
+    whatever part of its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of
+    the application. Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+**3.** You may opt to apply the terms of the ordinary GNU General
+Public License instead of this License to a given copy of the Library.
+To do this, you must alter all the notices that refer to this License,
+so that they refer to the ordinary GNU General Public License, version
+2, instead of to this License. (If a newer version than version 2 of
+the ordinary GNU General Public License has appeared, then you can
+specify that version instead if you wish.) Do not make any other
+change in these notices.
+
+Once this change is made in a given copy, it is irreversible for that
+copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+This option is useful when you wish to copy part of the code of the
+Library into a program that is not a library.
+
+**4.** You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+If distribution of object code is made by offering access to copy from
+a designated place, then offering equivalent access to copy the source
+code from the same place satisfies the requirement to distribute the
+source code, even though third parties are not compelled to copy the
+source along with the object code.
+
+**5.** A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library". Such a work,
+in isolation, is not a derivative work of the Library, and therefore
+falls outside the scope of this License.
+
+However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License. Section
+6 states terms for distribution of such executables.
+
+When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library. The
+threshold for this to be true is not precisely defined by law.
+
+If such an object file uses only numerical parameters, data structure
+layouts and accessors, and small macros and small inline functions
+(ten lines or less in length), then the use of the object file is
+unrestricted, regardless of whether it is legally a derivative work.
+(Executables containing this object code plus portions of the Library
+will still fall under Section 6.)
+
+Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+**6.** As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a work
+containing portions of the Library, and distribute that work under
+terms of your choice, provided that the terms permit modification of
+the work for the customer's own use and reverse engineering for
+debugging such modifications.
+
+You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License. You must supply a copy of this License. If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License. Also, you must do one
+of these things:
+
+-   **a)** Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library. (It is understood that
+    the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+-   **b)** Use a suitable shared library mechanism for linking with
+    the Library. A suitable mechanism is one that (1) uses at run time
+    a copy of the library already present on the user's computer
+    system, rather than copying library functions into the executable,
+    and (2) will operate properly with a modified version of the
+    library, if the user installs one, as long as the modified version
+    is interface-compatible with the version that the work was
+    made with.
+-   **c)** Accompany the work with a written offer, valid for at least
+    three years, to give the same user the materials specified in
+    Subsection 6a, above, for a charge no more than the cost of
+    performing this distribution.
+-   **d)** If distribution of the work is made by offering access to
+    copy from a designated place, offer equivalent access to copy the
+    above specified materials from the same place.
+-   **e)** Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it. However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system. Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+**7.** You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+-   **a)** Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other
+    library facilities. This must be distributed under the terms of
+    the Sections above.
+-   **b)** Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+**8.** You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License. Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+**9.** You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Library or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+**10.** Each time you redistribute the Library (or any work based on
+the Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+**11.** If, as a consequence of a court judgment or allegation of
+patent infringement or for any other reason (not limited to patent
+issues), conditions are imposed on you (whether by court order,
+agreement or otherwise) that contradict the conditions of this
+License, they do not excuse you from the conditions of this License.
+If you cannot distribute so as to satisfy simultaneously your
+obligations under this License and any other pertinent obligations,
+then as a consequence you may not distribute the Library at all. For
+example, if a patent license would not permit royalty-free
+redistribution of the Library by all those who receive copies directly
+or indirectly through you, then the only way you could satisfy both it
+and this License would be to refrain entirely from distribution of the
+Library.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply, and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+**12.** If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+**13.** The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time. Such
+new versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation. If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+**14.** If you wish to incorporate parts of the Library into other
+free programs whose distribution conditions are incompatible with
+these, write to the author to ask for permission. For software which
+is copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this. Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+**NO WARRANTY**
+
+**15.** BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+**16.** IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+### END OF TERMS AND CONDITIONS
+
+### How to Apply These Terms to Your New Libraries
+
+If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change. You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms
+of the ordinary General Public License).
+
+To apply these terms, attach the following notices to the library. It
+is safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should
+have at least the "copyright" line and a pointer to where the full
+notice is found.
+
+    one line to give the library's name and an idea of what it does.
+    Copyright (C) year  name of author
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Also add information on how to contact you by electronic and paper
+mail.
+
+You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the library,
+if necessary. Here is a sample; alter the names:
+
+    Yoyodyne, Inc., hereby disclaims all copyright interest in
+    the library `Frob' (a library for tweaking knobs) written
+    by James Random Hacker.
+
+    signature of Ty Coon, 1 April 1990
+    Ty Coon, President of Vice
+
+That's all there is to it!

Makefile

@@ -0,0 +1,8 @@
+# JaT - Just A[nother] Testing library
+# See LICENSE.md file for copyright and license details.
+
+MKIT_DIR=utils/mkit
+include $(MKIT_DIR)/mkit.mk
+
+TF_DIR=utils/tfkit
+include $(TF_DIR)/tfkit.mk

README.md

@@ -0,0 +1,4 @@
+JaT
+===
+
+Just A[nother] Testing library

mkit.ini

@@ -0,0 +1,39 @@
+[project]
+    version     = 0.0.0
+    name        = JaT
+    tagline     = Just A[nother] Testing library
+    pkgname     = shellfu-bash-jat
+    maintainer  = Alois Mahdal <netvor+jat@vornet.cz>
+    vcs_browser = https://github.com/AloisMahdal/shellfu-bash-jat
+    relsrc      = master
+    reldst      = last
+
+[dist]
+    tarball  = LICENSE.md
+    tarball  = Makefile
+    tarball  = README.md
+    tarball  = mkit.ini
+    tarball  = packaging
+    tarball  = src
+    tarball  = tests
+    tarball  = utils
+    rpmstuff = packaging/template.spec
+    debstuff = packaging/debian
+
+[ENV]
+    PREFIX = /usr/local
+
+[roots]
+    doc   = [ENV:PREFIX]/share/doc/shellfu-bash-jat
+    sfmod = [ENV:PREFIX]/share/shellfu/include-bash
+
+[macros]
+    __SHELLFU_MODNAME__ = jat
+    __SHELLFU_MODDESC__ = Just A[nother] Testing library
+
+[files]
+    doc   = README.md
+    sfmod = src/jat.sh
+    sfmod = src/jat_dump.sh
+
+#mkit version=0.0.32

notes/TODO.md

@@ -0,0 +1,21 @@
+TODO
+====
+
+ *  Add way to pass:
+     *  test name, etc.
+     *  env info,
+     *  sut info.
+
+ *  think hard about promises
+
+ *  do YAML more right
+
+ *  wait, are phases preserved across sessions?
+
+ *  WAIT, are phases preserved into subshell (logging..)?
+
+ *  jat__lsummary()
+
+ *  add .j2 for HTML/text/whatever (separate module?)
+
+ *  fortify against running from within test

notes/jattest

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+if ! test -f /var/tmp/jat/rebooted; then
+
+    jat__cmp 0 eq 1
+
+    jat__pstarts init
+        jat__cmp -h "math works" \
+            0 eq 0
+    jat__pend
+
+    jat__pstartt
+        jat__cmd true
+        jat__cmd false
+        jat__cmd -e 1 true
+        jat__cmd -e 1 false
+        jat__cmp 5 eq 3
+        jat__cmp 5 gt 3
+        jat__cmp foo re oo
+        jat__cmp foo re '.*oo'
+        jat__pass -h "so it looks fine"
+        jat__fail -h "it still looks fine"
+        jat__fail
+        jat__pass
+        jat__log_info "this is normal"
+    jat__pend
+
+    jat__pstartt beidz
+        jat__cmd -b foo true
+        jat__cmd -b foo2 false
+    jat__pend
+
+    jat__pstartt pre-reboot
+        jat__cmd true
+        touch /var/tmp/jat/rebooted
+    jat__pend
+
+    jat__log_info "rebooting"
+    exit
+
+else
+
+    jat__log_info "rebooted"
+    jat__pstartt post-reboot
+        rm /var/tmp/jat/rebooted
+        jat__cmd true
+    jat__pend
+
+fi
+
+# jat__pstartt "torture"
+#     jat__cmd
+#     jat__cmd -z zaza
+#     jat__cmp foo bar baz
+#     jat__cmp foo eq baz
+#     jat__fail "heya"
+#     jat__pass "hoya"
+#     jat__log_error "this is not normal"
+# jat__pend

packaging/debian/changelog

@@ -0,0 +1,5 @@
+__MKIT_PROJ_PKGNAME__ (__MKIT_PROJ_VERSION__-1) UNRELEASED; urgency=medium
+
+  * Initial release. (Closes: #XXXXXX)
+
+ -- __MKIT_PROJ_MAINTAINER__  Thu, 03 May 2018 00:29:14 +0200

packaging/debian/compat

@@ -0,0 +1 @@
+9

packaging/debian/control

@@ -0,0 +1,28 @@
+Source: __MKIT_PROJ_PKGNAME__
+Maintainer: __MKIT_PROJ_MAINTAINER__
+Vcs-Browser: __MKIT_PROJ_VCS_BROWSER__
+Section: misc
+Priority: extra
+Standards-Version: 3.9.2
+Build-Depends:
+ debhelper (>= 9),
+ shellfu (>= 0.10.7),
+ shellfu (<< 0.11),
+ shellfu-bash,
+ shellfu-bash-pretty,
+ shellfu-sh-isa,
+ shellfu-sh-termcolors,
+
+Package: __MKIT_PROJ_PKGNAME__
+Architecture: all
+Depends:
+ shellfu (>= 0.10.7),
+ shellfu (<< 0.11),
+ shellfu-bash,
+ shellfu-bash-pretty,
+ shellfu-sh-isa,
+ shellfu-sh-termcolors,
+Description: __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__
+ __SHELLFU_MODDESC__
+
+# control file built with MKit __MKIT_SELF_VERSION__

packaging/debian/copyright

@@ -0,0 +1 @@
+

packaging/debian/install

@@ -0,0 +1,2 @@
+/usr/share/shellfu/include-bash/__SHELLFU_MODNAME__.sh
+/usr/share/shellfu/include-bash/jat_dump.sh

packaging/debian/rules

@@ -0,0 +1,14 @@
+#!/usr/bin/make -f
+
+%:
+
+	dh $@
+
+override_dh_auto_install:
+
+	make install PREFIX=/usr DESTDIR=debian/tmp
+
+override_dh_auto_test:
+	make install PREFIX=/usr DESTDIR=debian/tmp
+	make test \
+		SHELLFU_PATH=$(shell pwd)/debian/tmp/usr/share/shellfu/include-bash

packaging/debian/source/format

@@ -0,0 +1 @@
+3.0 (quilt)

packaging/template.spec

@@ -0,0 +1,47 @@
+%global sfincb %{_datadir}/shellfu/include-bash
+%global sfmodn __SHELLFU_MODNAME__
+%global shellfu_req shellfu >= 0.10.7, shellfu < 0.11
+
+Name:       __MKIT_PROJ_PKGNAME__
+Version:    __MKIT_PROJ_VERSION__
+Release:    1%{?dist}
+Summary:    __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__
+URL:        __MKIT_PROJ_VCS_BROWSER__
+License:    LGPLv2
+Source0:    %{name}-%{version}.tar.gz
+BuildArch:  noarch
+BuildRequires: %shellfu_req
+BuildRequires: shellfu-bash-pretty
+BuildRequires: shellfu-sh-isa
+BuildRequires: shellfu-sh-termcolors
+
+Requires: %shellfu_req
+Requires: shellfu-bash
+Requires: shellfu-bash-pretty
+Requires: shellfu-sh-isa
+Requires: shellfu-sh-termcolors
+%description
+__SHELLFU_MODDESC__
+
+%prep
+%setup -q
+
+%build
+make %{?_smp_mflags} PREFIX=/usr
+
+%install
+%make_install PREFIX=/usr
+
+%check
+make test \
+    SHELLFU_PATH=%{buildroot}/%{_datadir}/shellfu/include-bash
+
+%files
+%doc %{_docdir}/%{name}/README.md
+%{sfincb}/%{sfmodn}.sh
+%{sfincb}/%{sfmodn}_dump.sh
+
+
+%changelog
+
+# specfile built with MKit __MKIT_SELF_VERSION__

src/_pretty_jat.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+shellfu import jat
+
+_pretty__debug() {
+    local decor="()"
+    local caller_is_main=${caller_is_main:-false}
+    local caller=${caller:-UNKNOWN}
+    $caller_is_main && decor=
+    while IFS= read -r line;
+    do jat__log_info "debug:$caller$decor:"
+       jat__log_info "$line"; done
+}
+
+
+_pretty__die() {
+    while IFS= read -r line;
+    do jat__log_error "$line"; done
+}
+
+
+_pretty__mkhelp() {
+    while IFS= read -r line;
+    do jat__log_info "$line"; done
+}
+
+
+_pretty__mkusage() {
+    while IFS= read -r line;
+    do jat__log_info "$line"; done
+}
+
+
+_pretty__think() {
+    while IFS= read -r line;
+    do jat__log_info "$line"; done
+}
+
+
+_pretty__warn() {
+    while IFS= read -r line;
+    do jat__log_warning "$line"; done
+}

src/jat_dump.sh.skel

@@ -0,0 +1,387 @@
+#!/bin/bash
+
+shellfu import jat
+shellfu import pretty
+
+#
+# Helpers for dumping files to log
+#
+# This module provides several functions to enable showing
+# contents of (supposedly small) files or command outputs directly
+# inside JAT log.
+#
+# This can be very helpful, especially if you know you are dealing
+# with relatively small files or to provide generic diagnostic
+# data.
+#
+# For example:
+#
+#     some_command >out 2>err
+#     jat__eval "grep foo out"
+#     jat__eval "grep bar out" 1
+#     jat__eval "test -s err" 1
+#     jat_dump__file out err
+#
+# Here, if your asserts fail, it will be very useful to see the content
+# right in the log.
+#
+# Another example (from real life):
+#
+#     rlPhaseStartTest infodump
+#         ps -C cimserver -o euser,ruser,suser,fuser,f,comm,label \
+#           | jat_dump__pipe PS_SECINFO
+#         ps -C cimserver -f \
+#           | jat_dump__pipe PS_F
+#         ps -C cimserver -Lf \
+#           | jat_dump__pipe PS_THREADS
+#         ps -ef \
+#           | jat_dump__pipe PS_EF
+#         jat_dump__file /etc/passwd /etc/group
+#     rlPhaseEnd
+#
+# Here, in one phase -- without getting in the way of other code
+# we can get reasonable profile of the cimserver process and
+# basic system setup.
+#
+
+#
+# Pipe via hexdump before printing?
+#
+# `always` to enforce all files through hexdump, `never` to disable
+# hexdump, `auto` to have the filetype detected.
+#
+JAT_DUMP__HEXMODE=${JAT_DUMP__HEXMODE:-auto}
+
+
+#
+# Command to use for hex dumping
+#
+JAT_DUMP__HEXCMD=${JAT_DUMP__HEXCMD:-hexdump -C}
+
+
+#
+# Limit in lines before rlFileSubmit is used instead of printing
+#
+JAT_DUMP__LIMIT_L=${JAT_DUMP__LIMIT_L:-100}
+
+
+#
+# Limit in bytes before rlFileSubmit is used instead of printing
+#
+JAT_DUMP__LIMIT_B=${JAT_DUMP__LIMIT_B:-10000}
+
+
+#
+# Function to use for logging
+#
+JAT_DUMP__DMPFUN=${JAT_DUMP__DMPFUN:-jat__log_info}
+
+
+jat_dump__file() {
+    #
+    # Dump contents of given file(s) using jat__log_info
+    #
+    # Usage:
+    #
+    #     jat_dump__file [options] FILE...
+    #
+    # Description:
+    #
+    # Print contents of given file(s) to the main TESTOUT.log
+    # using jat_log* functions and adding BEGIN/END delimiters.
+    # If a file is too big, use rlFileSubmit instead.  If a file
+    # is binary, pipe it through `hexdump -C`.
+    #
+    # Options:
+    #
+    #   *  -h, --hex
+    #   *  -H, --no-hex
+    #               enforce or ban hexdump for all files
+    #   *  -b BYTES, --max-bytes BYTES
+    #   *  -l LINES, --max-lines LINES
+    #               set limit to lines or bytes; if file is bigger,
+    #               use rlFileSubmit instead
+    #   *  -I, --info
+    #   *  -E, --error
+    #   *  -D, --debug
+    #               use different level of jat_log* (Info by default)
+    #   *  -s, --skip-empty
+    #               do not do anything if file is empty
+    #   *  -S, --skip-missing
+    #               do not do anything if file is missing
+    #
+    local hexmode=$JAT_DUMP__HEXMODE
+    local limit_b=$JAT_DUMP__LIMIT_B
+    local limit_l=$JAT_DUMP__LIMIT_L
+    local dmpfun="$JAT_DUMP__DMPFUN"
+    local skip_empty=false
+    local skip_missing=false
+    while true; do case "$1" in
+        -h|--hex)        hexmode=always;      shift 1 ;;
+        -H|--no-hex)     hexmode=never;       shift 1 ;;
+        -b|--max-bytes)  limit_b=$2;          shift 2 ;;
+        -l|--max-lines)  limit_l=$2;          shift 2 ;;
+        -I|--info)       dmpfun=jat__log_info; shift 1 ;;
+        -E|--error)      dmpfun=jat__log_error;     shift 1 ;;
+        -D|--debug)      dmpfun=debug;          shift 1 ;;
+        -s|--skip-empty) skip_empty=true;     shift 1 ;;
+        -S|--skip-missing) skip_missing=true; shift 1 ;;
+        *) break ;;
+    esac done
+
+    local fpath     # path to original file
+    local hexdump   # path to hexdumped file, if needed
+
+    for fpath in "$@";
+    do
+
+        # skipping logic
+        ! test -e "$fpath" && $skip_missing && continue
+        test -e "$fpath" || { jat__log_error "no such file: $fpath"; continue; }
+        test -f "$fpath" || { jat__log_error "not a file: $fpath"; continue; }
+        ! test -s "$fpath" && $skip_empty && continue
+
+        if __jat_dump__use_hex "$hexmode" "$fpath";
+        then
+            hexdump=$(__jat_dump__mkhexdump < "$fpath")
+            __jat_dump__logobj HEXDUMP "$hexdump" "$fpath" "$fpath"
+            rm "$hexdump"
+        else
+            __jat_dump__logobj FILE "$fpath" "$fpath"
+        fi
+
+    done
+}
+
+jat_dump__mkphase() {
+    #
+    # Make a dump phase incl. JAT formalities
+    #
+    # Usage:
+    #     jat_dump__mkphase [-n NAME] FILE...
+    #
+    # Create a separate diag phase called NAME ('dump' by
+    # default) and dump all listed files there.
+    #
+    local name="dump"           # phase name, should you not like dump
+    while true; do case "$1" in
+        -n|--name) name=$2; shift 2 ;;
+        *) break ;;
+    esac done
+    jat__pstartd "$name"
+        jat_dump__file "$@"
+    jat__pend
+}
+
+jat_dump__pipe() {
+    #
+    # Dump contents passed to stdin using jat__log_info
+    #
+    # Usage:
+    #
+    #     some_command | jat_dump__pipe [options] [NAME]
+    #
+    # Description:
+    #
+    # Cache contents of stream given on STDIN and print them to
+    # the main TESTOUT.log using jat__log* functions and adding
+    # BEGIN/END delimiters.  If the content is too big, use
+    # rlFileSubmit instead.  If the content is binary, pipe it
+    # through `hexdump -C`.
+    #
+    # NAME will appear along with pipe content delimiters,  and
+    # if a limit is reached, will be used as name for file to
+    # store using rlFileSubmit.  NAME will be generated if
+    # omitted.
+    #
+    # Options:
+    #
+    #   *  -h, --hex
+    #   *  -H, --no-hex
+    #               enforce or ban hexdump for all files
+    #   *  -b BYTES, --max-bytes BYTES
+    #   *  -l LINES, --max-lines LINES
+    #               set limit to lines or bytes; if file is bigger,
+    #               use rlFileSubmit instead
+    #   *  -I, --info
+    #   *  -E, --error
+    #   *  -D, --debug
+    #               use different level of jat__log* (Info by default)
+    #
+    local hexmode=$JAT_DUMP__HEXMODE
+    local limit_b=$JAT_DUMP__LIMIT_B
+    local limit_l=$JAT_DUMP__LIMIT_L
+    local dmpfun="$JAT_DUMP__DMPFUN"
+    local cache
+    while true; do case "$1" in
+        -h|--hex)        hexmode=always;      shift 1 ;;
+        -H|--no-hex)     hexmode=never;       shift 1 ;;
+        -b|--max-bytes)  limit_b=$2;          shift 2 ;;
+        -l|--max-lines)  limit_l=$2;          shift 2 ;;
+        -I|--info)       dmpfun=jat__log_info;    shift 1 ;;
+        -E|--error)      dmpfun=jat__log_error;   shift 1 ;;
+        -D|--debug)      dmpfun=debug;        shift 1 ;;
+        *) break ;;
+    esac done
+    local name="$1"
+
+    # cache the stream
+    cache=$(mktemp -t jat_dump-cache.XXXXXXXXXX)
+    cat > "$cache"
+
+    # make up name if not given (re-use XXXXXXXXXX from $cache)
+    test -n "$name" || name="ANONYMOUS.$$.${cache##*.}"
+
+    if __jat_dump__use_hex "$hexmode" "$cache";
+    then
+        hexdump=$(__jat_dump__mkhexdump < "$cache")
+        __jat_dump__logobj HEXDUMP "$hexdump" "$name" "$cache"
+        rm "$hexdump"
+    else
+        __jat_dump__logobj PIPE "$cache" "$name"
+    fi
+
+    rm "$cache"
+}
+
+
+##                    ## starts behind this strip                           ##
+## museum of INTERNAL ## ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ##
+##           '''''''' ## no admission; you can steal but not touch anything ##
+
+__jat_dump__count() {
+    #
+    # Count sizes, compare to limits and print problem report if any
+    #
+    #inherits: limit_l limit_b
+    local file="$1"
+    local sizes size_b size_l
+    local over_b over_l many
+    sizes="$(wc -lc <"$file")"      # [newline] [bytes]
+    sizes="$(eval "echo $sizes")"   # squash + trim whites
+    size_b="${sizes##* }"
+    size_l="${sizes%% *}"
+    test "$size_b" -gt "$limit_b"; over_b=$?
+    test "$size_l" -gt "$limit_l"; over_l=$?
+    case "$over_b:$over_l" in
+        1:1) many=""                                    ;;
+        1:0) many="lines ($size_l)"                     ;;
+        0:1) many="bytes ($size_b)"                     ;;
+        0:0) many="lines ($size_l) and bytes ($size_b)" ;;
+        *)   jat__log_error "panic: $FUNCNAME"         ;;
+    esac
+    echo "$many"
+    test -z "$many"
+}
+
+__jat_dump__is_binary() {
+    #
+    # Check if file is binary
+    #
+    local path="$1"
+    test -s "$path"     || return 1
+    grep -qI . "$path"  && return 1
+    return 0
+}
+
+__jat_dump__logobj() {
+    #
+    # Dump the object type $1 from $2, or save it under name $3
+    #
+    # Type can be FILE, HEXDUMP or PIPE.  If object is too big to dump
+    # to log, it will be submitted using rlFileSubmit. in that case
+    # $3 may be specified as alternative name.
+    #
+    # In case of HEXDUMP, path to original file must be specified
+    # as $4, since in case file is too big, we want to submitt *both*
+    # the original and the hexdump (suffixed with .hex).
+    #
+    # FIXME: no way of dumping HEXDUMP without supplying alternate name
+    #
+    # In case of PIPE that needs to be submitted, suffiix ".pipe" is added
+    # to the filename.
+    #
+    # FIXME: Account for PIPE that gets HEXDUMPed (now be treated as file)
+    #
+    local otype=$1              # PIPE|HEXDUMP|FILE
+    local opath=$2              # printable data
+    local oname=${3:-$opath}    # chosen name
+    local oorig=$4              # original file in case of HEXDUMP
+    local bloat=""              # human description of limit excess; empty
+                                # .. means OK to dump to log; else use rlFileSubmit
+    local lline=""              # logged line
+
+    oname="$(tr / - <<<"$oname")"
+    bloat="$(__jat_dump__count "$opath")"
+
+    debug "$FUNCNAME:otype='$otype'"
+    debug "$FUNCNAME:opath='$opath'"
+    debug "$FUNCNAME:oname='$oname'"
+    debug "$FUNCNAME:oorig='$oorig'"
+    debug "$FUNCNAME:bloat='$bloat'"
+
+    # start outputting
+    if test -z "$bloat";
+    then
+        test -s "$opath" || {
+            case $dmpfun in
+                debug) debug "=====EMPTY $otype $oname=====" ;;
+                *)     jat__log_info  "=====EMPTY $otype $oname=====" ;;
+            esac
+            return
+        }
+        {
+            echo "=====BEGIN $otype $oname====="
+            cat "$opath"
+            test -n "$(tail -c 1 "$opath")" \
+             && echo "=====NO_NEWLINE_AT_EOF====="
+            echo  "=====END $otype $oname====="
+        } \
+          | while IFS= read -r lline; do
+                $dmpfun "$lline"
+            done
+    else
+        case $otype in
+            FILE)
+                jat__log_info "not dumping, file has too many $bloat: $opath"
+                rlFileSubmit -- "$opath" "$oname"
+                ;;
+            PIPE)
+                jat__log_info "not dumping, pipe has too many $bloat: $oname"
+                rlFileSubmit -- "$opath" "$oname.pipe"
+                ;;
+            HEXDUMP)
+                jat__log_info "not dumping, hexdump is too long for: $oorig"
+                rlFileSubmit -- "$opath" "$oname.hex"
+                rlFileSubmit -- "$oorig" "$oname"
+                ;;
+        esac
+    fi
+
+}
+
+__jat_dump__mkhexdump() {
+    #
+    # Create hexdump (as tempfile) from stdin and echo path to it
+    #
+    local hdtmp
+    hdtmp=$(mktemp -t jat_dump-hex.XXXXXXXXXX)
+    $JAT_DUMP__HEXCMD > "$hdtmp"
+    echo "$hdtmp"
+}
+
+__jat_dump__use_hex() {
+    #
+    # True if we need to use hexdump
+    #
+    local hexmode="$1"
+    local fpath="$2"
+    case "$hexmode" in
+        always) return 0 ;;
+        never)  return 1 ;;
+        auto)   __jat_dump__is_binary "$fpath"; return $? ;;
+        *)      rlFail "bad value of JAT_DUMP__HEXMODE: $hexmode" ;;
+    esac
+}
+
+#shellfu module-version=__MKIT_PROJ_VERSION__

tests/TF_HEADER

@@ -0,0 +1,3 @@
+#!/bin/bash
+. "$(sfpath)" || exit 3
+echo "version: $(shellfu version jat)"

tests/basic/TF_RUN

@@ -0,0 +1,104 @@
+#!/bin/bash
+#shellcheck disable=SC2016,SC1090
+
+. "$TF_DIR/include/subtest.sh"
+. "$TF_DIR/include/tools.sh"
+
+. "$(sfpath)" || tf_exit_error "failed to init shellfu"
+shellfu import jat  || tf_exit_error "failed to import jat"
+
+tf_enum_subtests() {
+    echo ylog_pass
+    echo ylog_fail
+    echo ylog_both
+}
+
+rndtoken() {
+    head -c 100 /dev/urandom | md5sum | head -c 7
+}
+
+mkhacks() {
+    echo '__JAT__SELF_VERSION=0.0.0+TESTED_VERSION'
+    echo '__JAT__DETERMINISTIC=true'
+    echo ''
+}
+
+mkhead() {
+    echo '#!/bin/bash'
+    echo ''
+    echo '. "$(sfpath)" || exit 3'
+    echo 'shellfu import jat'
+    echo ''
+    mkhacks
+    echo ''
+    echo "JAT__DIR=$PWD/result/$name/dir"
+    echo "JAT__YLOG=$PWD/result/$name/ylog"
+    echo ''
+    echo 'jat__sinit'
+    echo ''
+}
+
+mkbody() {
+    #shellcheck disable=SC1003
+    case $name in
+        ylog_pass)
+            echo '    jat__pstartt'
+            echo '        jat__cmd -h "true is true" \'
+            echo '            true'
+            echo '        jat__cmd -h "false is false" -S 1 \'
+            echo '            false'
+            echo '    jat__pend'
+            ;;
+        ylog_fail)
+            echo '    jat__pstartt'
+            echo '        jat__cmd -h "true is false" -S 1 \'
+            echo '            true'
+            echo '        jat__cmd -h "false is true" -S 0 \'
+            echo '            false'
+            echo '    jat__pend'
+            ;;
+        ylog_both)
+            echo '    jat__pstartt'
+            echo '        jat__cmd -h "true is true" -S 0 \'
+            echo '            true'
+            echo '        jat__cmd -h "false is true" -S 0 \'
+            echo '            false'
+            echo '    jat__pend'
+            ;;
+    esac
+}
+
+mktail() {
+    echo ''
+    echo 'jat__sfinish'
+}
+
+unveil() {
+    #
+    # Remove arbitrary values
+    #
+    sed "
+        s/^jat_version: .*$/jat_version: JAT_VERSION/
+    "
+}
+
+runtest() {
+    mkdir -p "test" "result/$name"
+    {
+        mkhead
+        mkbody
+        mktail
+    } > "test/$name.sh"
+    bash "test/$name.sh" 2>/dev/null
+    < "result/$name/ylog" unveil
+}
+
+
+tf_do_subtest() {
+    local name=$1
+    local o_out=oracle/$name.stdout
+    local o_err=oracle/$name.stderr
+    tf_testflt -n "$name" -E "$o_err" -O "$o_out" runtest
+}
+
+tf_do_subtests

tests/basic/oracle/ylog_both.stdout

@@ -0,0 +1,115 @@
+---
+format: jat/0.0
+jat_version: JAT_VERSION
+test:
+    id: _jat_anon_test_
+start: time-1
+events:
+    -
+        origin: jat__sinit
+        etype: SINFO
+        stamp: time-2
+        hint: |-
+            started new session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: __jat__pstart
+        etype: SINFO
+        stamp: time-3
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-4
+        hint: |-
+            CMD: true
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: PASS
+        stamp: time-5
+        hint: |-
+            true is true
+        beids: []
+        data:
+            CMDLINE: |
+                true
+            ES_EXPR: |
+                0
+            ES: |
+                0
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-6
+        hint: |-
+            CMD: false
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: FAIL
+        stamp: time-7
+        hint: |-
+            false is true
+        beids: []
+        data:
+            CMDLINE: |
+                false
+            ES_EXPR: |
+                0
+            ES: |
+                1
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__pend
+        etype: SINFO
+        stamp: time-8
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: jat__sfinish
+        etype: SINFO
+        stamp: time-9
+        hint: |-
+            finishing session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+finalized: true
+end: time-10

tests/basic/oracle/ylog_fail.stdout

@@ -0,0 +1,115 @@
+---
+format: jat/0.0
+jat_version: JAT_VERSION
+test:
+    id: _jat_anon_test_
+start: time-1
+events:
+    -
+        origin: jat__sinit
+        etype: SINFO
+        stamp: time-2
+        hint: |-
+            started new session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: __jat__pstart
+        etype: SINFO
+        stamp: time-3
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-4
+        hint: |-
+            CMD: true
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: FAIL
+        stamp: time-5
+        hint: |-
+            true is false
+        beids: []
+        data:
+            CMDLINE: |
+                true
+            ES_EXPR: |
+                1
+            ES: |
+                0
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-6
+        hint: |-
+            CMD: false
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: FAIL
+        stamp: time-7
+        hint: |-
+            false is true
+        beids: []
+        data:
+            CMDLINE: |
+                false
+            ES_EXPR: |
+                0
+            ES: |
+                1
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__pend
+        etype: SINFO
+        stamp: time-8
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: jat__sfinish
+        etype: SINFO
+        stamp: time-9
+        hint: |-
+            finishing session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+finalized: true
+end: time-10

tests/basic/oracle/ylog_pass.stdout

@@ -0,0 +1,115 @@
+---
+format: jat/0.0
+jat_version: JAT_VERSION
+test:
+    id: _jat_anon_test_
+start: time-1
+events:
+    -
+        origin: jat__sinit
+        etype: SINFO
+        stamp: time-2
+        hint: |-
+            started new session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: __jat__pstart
+        etype: SINFO
+        stamp: time-3
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-4
+        hint: |-
+            CMD: true
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: PASS
+        stamp: time-5
+        hint: |-
+            true is true
+        beids: []
+        data:
+            CMDLINE: |
+                true
+            ES_EXPR: |
+                0
+            ES: |
+                0
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__log_info
+        etype: SINFO
+        stamp: time-6
+        hint: |-
+            CMD: false
+        beids: []
+        data: {}
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: __jat__assert
+        etype: PASS
+        stamp: time-7
+        hint: |-
+            false is false
+        beids: []
+        data:
+            CMDLINE: |
+                false
+            ES_EXPR: |
+                1
+            ES: |
+                1
+        phase:
+            id: phasid-1
+            name: _jat_anon_phase_
+            type: test
+    -
+        origin: jat__pend
+        etype: SINFO
+        stamp: time-8
+        hint: ~
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+    -
+        origin: jat__sfinish
+        etype: SINFO
+        stamp: time-9
+        hint: |-
+            finishing session
+        beids: []
+        data: {}
+        phase:
+            id: dummy
+            name: _jat_dummy_phase_
+            type: none
+finalized: true
+end: time-10

utils/mkit/include/build.sh

@@ -0,0 +1,290 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+mkit_import facts
+
+
+__build1() {
+    #
+    # Process one skeleton $1 of type $3 (or guessed) to path $2
+    #
+    local srcpath=$1    # skeleton path
+    local dstpath=$2    # destination meaty animal path
+    local ftype=$3      # file/builder type
+    test -n "$dstpath"  || dstpath=${srcpath%.skel}
+    test -n "$ftype"    || ftype=$(__guess_ftype "$dstpath")
+    debug_var srcpath dstpath ftype
+    <"$srcpath" __build1_ftype "$ftype" >"$dstpath"
+    __rec_built "$dstpath"
+}
+
+__build1_ftype() {
+    #
+    # Build a file of type $1; fom stdin to stdout
+    #
+    local ftype=$1      # file/builder type
+    case $ftype in
+        MKIT_COMMON)    __expand_macros "macros" ;;
+        rpmstuff)       __expand_macros "macros" "rpmstuff:macros" ;;
+        debstuff)       __expand_macros "macros" "debstuff:macros" ;;
+        *)              die "unknown file type: $ftype" ;;
+    esac
+}
+
+__expand_line() {
+    #
+    # Expand macro from $MacroMap in single line $1
+    #
+    # If macro value has multiple lines, repeat original line with
+    # different substitution.
+    #
+    # E.g. if macro value is "foo\nbar" and macro name is __FOO__,
+    # line `see: "__FOO__"` will expand to two lines: `see: "foo"`
+    # and `see: "bar"`.
+    #
+    local line=$1   # line to process
+    local mname     # macro name
+    local mvline    # line of macro value
+    local xline     # expanded line
+    xline=$line
+    for mname in "${!MacroMap[@]}"; do
+        if ! test "${line//$mname}" == "$line"; then
+            xline=$(
+                while IFS= read -r mvline; do
+                    echo "${line//$mname/$mvline}"
+                done <<<"${MacroMap[$mname]}"
+            )
+        fi
+        line=$xline
+    done
+    echo "$xline"
+    return 1
+}
+
+__expand_macros() {
+    #
+    # Read stdin, expanding macros from sections $@
+    #
+    local section       # each section to expand macros from
+    local line          # each line on stdin
+    local mname         # each macro name
+    local -A MacroMap   # macro value map
+    MacroMap[__MKIT_PROJ_NAME__]=$(ini 1value project:name)
+    MacroMap[__MKIT_PROJ_CODENAME__]=$(ini 1value project:codename)
+    MacroMap[__MKIT_PROJ_LICENSE__]=$(ini 1value project:license)
+    MacroMap[__MKIT_PROJ_PKGNAME__]=$(ini 1value project:pkgname)
+    MacroMap[__MKIT_PROJ_TAGLINE__]=$(ini 1value project:tagline)
+    MacroMap[__MKIT_PROJ_MAINTAINER__]=$(ini 1value project:maintainer)
+    MacroMap[__MKIT_PROJ_VCS_BROWSER__]=$(ini 1value project:vcs_browser)
+    MacroMap[__MKIT_PROJ_GIT_LASTHASH__]=$(__cached git_lasthash)
+    MacroMap[__MKIT_PROJ_VERSION__]=$(__cached semver)
+    MacroMap[__MKIT_SELF_VERSION__]=$MKIT_VERSION
+    for section in "$@"; do
+        for mname in $(ini lskeys "$section"); do
+            MacroMap[$mname]=$(ini values "$section:$mname")
+        done
+    done
+    debug_var MacroMap
+    while IFS= read -r line; do
+        __expand_line "$line"
+    done
+}
+
+__guess_ftype() {
+    #
+    # Guess file type from destination path $1
+    #
+    local dstpath=$1    # destination path
+    case $dstpath in
+        *)    echo MKIT_COMMON ;;
+    esac
+}
+
+__qfs() {
+    #
+    # Quote for our sed scipt's RHS
+    #
+    sed '
+        s:\\:\\\\:g
+        s:|:\\|:g
+    '
+}
+
+__cached() {
+    #
+    # Cached value $1 of function $1()
+    #
+    # In order to support git-less builds, some values might be cached
+    # in $MKIT_LOCAL.  This function gets file $1 from that cache (cache
+    # hit) or re-creates it (cache miss), but prints its body in either
+    # case.
+    #
+    # The command to re-create file is the same as the key (ie. no
+    # arguments).
+    #
+    local name=$1
+    __local_get "$name" && return 0
+    "$name" | __local_putb "$name"
+    __local_get "$name"
+}
+
+__local_putb() {
+    #
+    # Make file $1 in $MKIT_LOCAL from stdin and mark as built
+    #
+    local fpath=$1
+    __local_put "$fpath" && __rec_built "$MKIT_LOCAL/$fpath"
+}
+
+__local_put() {
+    #
+    # Make file $1 in $MKIT_LOCAL from stdin
+    #
+    local fpath="$MKIT_LOCAL/$1"
+    { mkdir -p "${fpath%/*}" && cat >"$fpath"; } \
+     || die "cannot write to local cache: $fpath"
+}
+
+__local_get() {
+    #
+    # Read file $1 in $MKIT_LOCAL
+    #
+    local fpath="$MKIT_LOCAL/$1"
+    cat "$fpath" 2>/dev/null
+}
+
+__rec_built() {
+    #
+    # Record file $1 for deletion on `clean`
+    #
+    local file=$1
+    mkdir -p "$MKIT_LOCAL"
+    echo "$file" >> "$MKIT_LOCAL/built.lst"
+}
+
+_mkit_data() {
+    #
+    # Build sampler showing all macro values
+    #
+    local macro
+    local section
+    local sections
+    sections=()
+    ini lskeys macros | grep -q . && sections=(macros)
+    sections+=( $(ini lssect | grep ':macros$') )
+    {
+        echo "(builtin):"
+        echo "  x_MKIT_PROJ_NAME__ => '__MKIT_PROJ_NAME__'"
+        echo "  x_MKIT_PROJ_CODENAME__ => '__MKIT_PROJ_CODENAME__'"
+        echo "  x_MKIT_PROJ_LICENSE__ => '__MKIT_PROJ_LICENSE__'"
+        echo "  x_MKIT_PROJ_PKGNAME__ => '__MKIT_PROJ_PKGNAME__'"
+        echo "  x_MKIT_PROJ_TAGLINE__ => '__MKIT_PROJ_TAGLINE__'"
+        echo "  x_MKIT_PROJ_MAINTAINER__ => '__MKIT_PROJ_MAINTAINER__'"
+        echo "  x_MKIT_PROJ_VCS_BROWSER__ => '__MKIT_PROJ_VCS_BROWSER__'"
+        echo "  x_MKIT_PROJ_GIT_LASTHASH__ => '__MKIT_PROJ_GIT_LASTHASH__'"
+        echo "  x_MKIT_PROJ_VERSION__ => '__MKIT_PROJ_VERSION__'"
+        echo "  x_MKIT_SELF_VERSION__ => '__MKIT_SELF_VERSION__'"
+        for section in "${sections[@]}"; do
+            echo "$section:"
+            for macro in $(ini lskeys "$section"); do
+                echo "  x${macro:1} => '$macro'"
+            done
+        done
+    } \
+      | __expand_macros "MKIT_BUILTIN" "${sections[@]}" \
+      | sed '/^  x/ s|x|_|'
+}
+
+build() {
+    #
+    # Add meat to all skeletons
+    #
+    local srcpath   # each source path
+    find . -type f -name '*.skel' \
+     | while read -r srcpath; do
+           __build1 "$srcpath"
+       done
+}
+
+clean() {
+    #
+    # Clean up tree after building
+    #
+    test -f "$MKIT_LOCAL/built.lst" && {
+        <"$MKIT_LOCAL/built.lst" grep -v -e '\.\.' -e ^/ \
+          | xargs -r rm -rf
+        rm -f "$MKIT_LOCAL/built.lst"
+        rmdir --ignore-fail-on-non-empty "$MKIT_LOCAL"
+    }
+    true
+}
+
+debstuff() {
+    #
+    # Build Debian stuff (eamed tarball, debian dir)
+    #
+    local version       # package version
+    local debian_skel   # 'debian' folder skeleton
+    local dfsrc         # each source file from ^^
+    local dftgt         # each built packaging file
+    version=$(__cached semver)
+
+    # tarball - we should already have by means of 'dist'
+    #
+    mv "${MKIT_PROJ_PKGNAME}-$version.tar.gz" \
+       "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz" \
+     || die "could not rename tarball"
+    __rec_built "${MKIT_PROJ_PKGNAME}_$version.orig.tar.gz"
+
+    # read content of each mandatory file from debian_skel
+    #
+    debian_skel=$(ini 1value dist:debstuff)
+    test -n "$debian_skel" || die "dist:debstuff not specified"
+    test -d "$debian_skel" || die "debian directory template found: $debian_skel"
+    mkdir -p debian/source
+    find "$debian_skel" -type f \
+      | while read -r dfsrc; do
+            dftgt="debian/${dfsrc#$debian_skel}"
+            mkdir -p "$(dirname "$dftgt")"
+            __build1 "$dfsrc" "$dftgt" debstuff
+        done
+    __rec_built debian
+}
+
+dist() {
+    #
+    # Create distributable tarball
+    #
+    #FIXME: lacking Makefile skills, we do this step twice for
+    #       rpmstuff, hence -f hack for gzip
+    #
+    local version           # tarball version
+    local git_lasthash      # last git commit hash
+    local dirname           # directory and tarball name
+    version=$(semver)
+    dirname=$MKIT_PROJ_PKGNAME-$version
+    git_lasthash=$(git_lasthash)
+    mkdir -p "$dirname"
+    ini values "dist:tarball" | xargs -I DIST_ITEM cp -R DIST_ITEM "$dirname"
+    mkdir -p "$dirname/.mkit"
+    echo -n "$version" > "$dirname/.mkit/semver"
+    echo -n "$git_lasthash" > "$dirname/.mkit/git_lasthash"
+    tar -cf "$dirname.tar" "$dirname"
+    gzip -f "$dirname.tar"      # see above FIXME
+    __rec_built "$dirname.tar.gz"
+    rm -rf "$dirname"
+}
+
+rpmstuff() {
+    #
+    # Build specfile
+    #
+    local specname=$MKIT_PROJ_PKGNAME.spec      # .spec filename
+    local specsrc                               # source of specfile
+    specsrc="$(ini 1value "dist:rpmstuff")"
+    test -n "$specsrc" || die "dist:rpmstuff not specified"
+    test -f "$specsrc" || die "specfile template not found: $specsrc"
+    __build1 "$specsrc" "$specname" rpmstuff
+}

utils/mkit/include/deploy.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+
+__deploy_item() {
+    #
+    # Deploy item and make it look like wanted
+    #
+    # usage: __deploy_item src dst [mode]
+    #
+    # Both src and dst must be names of actual items[1],
+    # whereas dst must not exist.  On update, dst is
+    # usually to be replaced but that is uninstall's
+    # job!
+    #
+    #  [1] Ie. src=foo and dst=/foo/bar does *always*
+    #      mean that foo will become 'bar'.  This is
+    #      different than traditional `cp` behavior,
+    #      when this depends if 'bar' already exists
+    #      as a directory.
+    #
+    # If mode is omitted or empty, MKIT_DEFAULT_MODE is
+    # used instead.
+    #
+    # Directories are copied recursively, and mode is
+    # applied only to files.
+    #
+    local src=$1                            # source path
+    local dst=$2                            # destination path
+    local mode=${3:-$MKIT_DEFAULT_MODE}     # mode
+    local item                              # each in directory
+    if test -d "$src"; then
+        find "$src" -type f \
+          | while read -r item; do
+                [[ $item =~ .skel$ ]] \
+                 && grep -q "${item%.skel}" "$MKIT_LOCAL/built.lst" \
+                 && continue
+                __deploy_item "$item" "$dst${item#$src}" "$mode"
+            done
+    else
+        test "$mode" == "SRC" && mode=$(stat -c "%a" "$src")
+        __maybe install -DTvm "$mode" "$src" "$dst"
+    fi
+}
+
+__get_dst() {
+    #
+    # Find out target path for src file $2 of group $1
+    #
+    local grp=$1        # deploy group
+    local src=$2        # each source
+    local dst=$3        # alternative destination name
+    test -n "$dst" || dst=${src##*/}
+    echo "$(__get_root "$grp")/$dst"
+}
+
+__get_root() {
+    #
+    # Find out target root for group $1
+    #
+    local grp=$1        # deploy group
+    local root          # root for this group
+    local destdir       # value of DESTDIR
+    root=$(ini 1value "roots:$grp")
+    destdir=$(ini 1value ENV:DESTDIR)
+    destdir=${destdir%/}
+    case $destdir:$root in
+        *:)     die "missing in config.ini: roots:$grp" ;;
+        :*)     echo "$root" ;;
+        *:*)    echo "$destdir/$root" ;;
+    esac
+}
+
+__maybe() {
+    #
+    # Call the deploy command $1 $@ unless in dry mode
+    #
+    debug "$@"
+    local cmd="$1"; shift
+    $MKIT_DRY && return
+    case "$cmd" in
+        cp|rm|rmdir|chmod|mkdir) $cmd "$@" ;;
+        install)                 command -p install "$@" ;;
+        *)                       die "bad command called";;
+    esac
+}
+
+install() {
+    #
+    # Install product
+    #
+    local group     # each deploy group
+    local mode      # mode (group-specific)
+    local src       # each source path
+    local dst       # each (final absolute) destination path
+    ini lskeys "files" \
+      | sort \
+      | uniq \
+      | while read -r group; do
+            mode=$(ini 1value "modes:$group")
+            ini values "files:$group" \
+              | while read -r src dst; do
+                    dst=$(__get_dst "$group" "$src" "$dst")
+                    __deploy_item "$src" "$dst" "$mode"
+                done
+        done
+    test -f "$MKIT_LOCAL/autoclean" && clean
+    true
+}
+
+uninstall() {
+    #
+    # Uninstall product
+    #
+    local group     # each deploy group
+    local src       # each source path
+    local dst       # each (final absolute) destination path
+    ini lskeys "files" \
+      | sort \
+      | uniq \
+      | while read -r group; do
+            ini values "files:$group" \
+              | while read -r src dst; do
+                    dst=$(__get_dst "$group" "$src" "$dst")
+                    __maybe rm -vrf "$dst"
+                done
+        done
+}

utils/mkit/include/facts.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+
+git_bool() {
+    #
+    # Get git bool (ie. exit status counts) $1
+    #
+    local bool_name=$1      # name of boolean to get
+    git_present || warn "can't give bool outside git repo: $bool_name"
+    case "$bool_name" in
+        dirty_files)
+            git diff-files | grep -qm 1 .
+            ;;
+        dirty_index)
+            git diff-index HEAD | grep -qm 1 .
+            ;;
+        dirty)
+            git_bool dirty_files || git_bool dirty_index
+            ;;
+        *)
+            warn "unknown git bool asked: $bool_name"
+            return 2
+            ;;
+    esac
+}
+
+git_fact() {
+    #
+    # Get git fact $1
+    #
+    local fact_name=$1      # name of fact to get
+    git_present || warn "can't give fact outside git repo: $fact_name"
+    case "$fact_name" in
+        latest_tag)
+            git log --format="%d" \
+              | sed 's/,/\n/g' \
+              | sed 's/^[[:blank:]]*//' \
+              | grep -E '^\(?tag' \
+              | tr -cd '[[:digit:]].v\n' \
+              | grep . -m 1
+            ;;
+        latest_version)
+            git_fact latest_tag | git_tag2ver
+            ;;
+        current_branch)
+            git rev-parse --abbrev-ref HEAD
+            ;;
+        reldiff)
+            git log --oneline "$(git_fact latest_tag)..HEAD" --name-only
+            ;;
+        latest_sha)
+            git log -1 --pretty=format:%h HEAD
+            ;;
+        *)
+            warn "unknown git fact asked: $fact_name"
+            ;;
+    esac
+}
+
+git_present() {
+    #
+    # True if we're in a git repo
+    #
+    git rev-parse HEAD >&/dev/null
+}
+
+git_tag2ver() {
+    #
+    # Convert tag to version
+    #
+    sed s/^v//
+}
+
+git_ver2tag() {
+    #
+    # Convert version to tag
+    #
+    sed s/^/v/
+}
+
+git_lasthash() {
+    #
+    # Show last commit hash (with .dirty suffix if needed)
+    #
+    # We can't do it outside git repo (or without git) but we should
+    # not be asked to; targets that don't require git should make use
+    # of cache built by dist target.
+    #
+    local last_hash     # last commit hash
+    git_present || {
+        echo UNKNOWN_HASH
+        warn "no git present; could not determine last hash"
+        return 3
+    }
+    last_hash=$(git rev-parse HEAD)
+    echo -n "$last_hash"
+    git_bool dirty && echo -n ".dirty"
+}
+
+semver() {
+    #
+    # Build proper SemVer version string
+    #
+    # Build version string from available info using following
+    # logic:
+    #
+    #  1. Use version from last git tag (or mkit.ini if there is no
+    #     tag, which is possible on new project)
+    #  2. if set, add project:prerl (from mkit.ini) as pre-release ID
+    #     (afer dash)
+    #  3. if we are at a later commit than the last tag, add branch
+    #     name and commit sha1 to build metadata (after plus sign)
+    #  4. if the tree is "dirty", i.e. has uncommited changes,
+    #     add "dirty" to build metadata
+    #
+    # The version is compatible with SemVer 2.0.0.
+    #
+    # Examples:
+    #
+    #     foo v1.0.7                            # all clear; proper release
+    #     foo v1.0.7-beta                       # mkit.ini: project:prerl="beta"
+    #     foo v1.0.7-beta+g1aef811.master       # ^^ + some commits after
+    #     foo v1.0.7-beta+gf14fc4f.api2         # ^^ + on a feature branch
+    #     foo v1.0.7-beta+gf14fc4f.api2.dirty   # ^^ + tree edited
+    #     foo v1.0.7-beta+dirty                 # tag OK but tree edited
+    #     foo v1.0.7+dirty                      # ^^ but no pre-release id
+    #
+    # Note that versions with "dirty" should be perceived as kind of
+    # dangerous outside developer's own machine.  Versions with sha1 are
+    # safer but must not be released.
+    #
+    # FIXME:  Using project:prerl for release IDs may not be compatible with
+    #         release strategy implemented in release.sh
+    #
+    local xyz           # base version string
+    local prerl         # pre-release keyword (from mkit.ini, eg. 'beta')
+    local latest_tag    # latest git tag
+    local commit        # commit indicator (CURRENT_BRANCH.gHASH)
+    local dirty         # 0 if dirty, 1 if clean
+    local suffix        # version suffix
+    prerl=$(ini 1value project:prerl)
+    grep ":" <<<"$prerl" \
+     && warn "colon in project:prerl may corrupt version data: $prerl"
+    git_present || {
+        echo UNKNOWN_VERSION
+        warn "no git present; could not determine SemVer"
+        return 3
+    }
+    latest_tag=$(git_fact latest_tag)
+    case $latest_tag in
+        v*) xyz=${latest_tag:1} ;;
+        "") warn "no tags, using base version from mkit.ini (ok for new project)"
+            xyz=$(ini 1value project:version) ;;
+        *)  warn "bad form of last tag, using base version from mkit.ini: tag is '$latest_tag'"
+            xyz=$(ini 1value project:version) ;;
+    esac
+    if ! git describe --tags --exact-match HEAD >&/dev/null;
+    then    # we are at a later commit than the last tag
+        commit="$(git_fact current_branch).g$(git_fact latest_sha)"
+    fi
+    git_bool dirty; dirty=$?
+    case "$dirty:$commit" in
+        1:)  suffix=""               ;;
+        0:)  suffix="+dirty"         ;;
+        1:*) suffix="+$commit"       ;;
+        0:*) suffix="+$commit.dirty" ;;
+        *)   suffix=MKIT_BUG
+             warn "MKIT_BUG: bad dirt/commit detection" ;;
+    esac
+    test -n "$prerl" && suffix="-$prerl$suffix"
+    echo "$xyz$suffix"
+}

utils/mkit/include/ini.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+__ini_cat() {
+    #
+    # A no-op for text stream
+    #
+    local line      # each line
+    while read -r line; do
+        printf -- "%s\n" "$line"
+    done
+}
+
+__ini_expand() {
+    #
+    # Expand reference value (prefix only)
+    #
+    local line      # each input line
+    local suffix    # tail of the line
+    local ref       # reference
+    local value     # value if reference
+    while read -r line; do                  # [foo:bar]/path
+        suffix="${line#\[*\]}"              # /path
+        ref="${line%$suffix}"               # [foo:bar]
+        ref="${ref%\]}"                     # [foo:bar
+        ref="${ref#\[}"                     # foo:bar
+        value="$(ini 1value "$ref")"        # foo_bar_value
+        printf -- "%s\n" "$value$suffix"    # foo_bar_value/path
+    done
+}
+
+__ini_grepcmt() {
+    #
+    # Remove comments from INI file on stdin
+    #
+    grep -v '^[[:space:]]*#'
+}
+
+__ini_grepkey() {
+    #
+    # Read key from a section
+    #
+    local wnt=$1    # wanted key
+    grep '.' \
+      | sed -e 's/ *= */=/; s/ +$//; s/^//;' \
+      | grep -e "^$wnt=" \
+      | cut -d= -f2- \
+      | __ini_maybe_expand
+}
+
+__ini_greppath() {
+    #
+    # Read key from the right section
+    #
+    # E.g. `files:share:my/lib.sh` should read
+    #
+    #     [files:share]
+    #         my/lib.sh   = proj/my/lib.sh
+    #
+    local wnt=$1                    # wanted path
+    local wntkey=${wnt##*:}         # ^^ key part
+    local wntsec=${wnt%:$wntkey}    # ^^ section part
+    local override                  # ENV override (only ENV section)
+    if test "$wntsec" = 'ENV'; then
+        override=${!wntkey}
+        test -n "$override" \
+         && echo "$override" \
+         && return
+    fi
+    __ini_grepsec "$wntsec" | __ini_grepkey "$wntkey"
+}
+
+__ini_grepsec() {
+    #
+    # Read one INI section
+    #
+    local wnt=$1        # wanted section name
+    local ok=false      # are we in the section?
+    local line          # each input line
+    grep '.' \
+      | while read -r line; do
+            case "$line" in
+                \[$wnt\]) ok=true;  continue ;;
+                \[*\])    ok=false; continue ;;
+            esac
+            $ok || continue
+            printf -- "%s\n" "$line"
+        done \
+      | sed -e 's/ *= */=/; s/ +$//; s/^//;'
+}
+
+__ini_lskeys() {
+    #
+    # List keys from a section
+    #
+    local sct=$1    # section of interest
+    __ini_grepsec "$sct" | cut -d= -f1 | awk '!x[$0]++'
+}
+
+__ini_lssect() {
+    #
+    # List all section names
+    #
+    local arg=$1    # unused argument
+    grep -x '\[.*\]' | sed 's/^.//; s/.$//'
+}
+
+__ini_maybe_expand() {
+    #
+    # Decide whether or not to expand
+    #
+    if test "$MKIT_INI_EXPAND" -gt 0; then
+        MKIT_INI_EXPAND=$(( --MKIT_INI_EXPAND )) __ini_expand
+    else
+        __ini_cat
+    fi
+}
+
+__ini_body() {
+    #
+    # Produce mkit.ini body including INCLUDE
+    #
+    # Note: recursive includes are not supported.
+    #
+    local inc                       # file to include
+    local incre='\[INCLUDE:.*\]'    # include directive regex
+    local iline                     # include directive line
+    if iline=$(grep -m1 -x "$incre" "$MKIT_INI"); then
+        inc=${iline#*:}; inc=${inc%]}
+        grep -vx "$incre" "$inc"
+        grep -vx "$incre" "$MKIT_INI"
+    else
+        cat "$MKIT_INI"
+    fi | __ini_grepcmt
+}
+
+ini() {
+    #
+    # do ini operation
+    #
+    local op=$1             # operator
+    local arg=$2            # argument
+    local fn                # internal function implementing $op
+    local limit=__ini_cat    # limiting internal function
+    case $op in
+        lskeys) fn=__ini_lskeys   ;;
+        lssect) fn=__ini_lssect   ;;
+        sec)    fn=__ini_grepsec  ;;
+        values) fn=__ini_greppath ;;
+        1value) fn=__ini_greppath; limit="tail -1" ;;
+        *)      die "incorrect use of \`ini()\`"
+    esac
+    __ini_body | $fn "$arg" | $limit
+}
+
+update_version() {
+    #
+    # Change project:version in mkit.ini at path $2 to value $1
+    #
+    local version=$1    # new version
+    local inifile=$2    # mkit.ini path
+    local tmp           # mkit.ini cache
+    tmp=$(mktemp -t mkit.update_version.XXXXXXXX)
+    <"$inifile" perl -e '
+        my $hit = 0;
+        my $done = 0;
+        foreach (<STDIN>) {
+            if      ($done) { print; next; }
+            elsif   (m/\[project\]/) { $hit++; print; next; }
+            elsif   (m/\[/) { $hit = 0; print; next; }
+            elsif   ($hit) { s/\bversion\b( *)=( *).*/version$1=$2$ARGV[0]/ and $done++; print; }
+            else { print; next; }
+        }
+    ' "$version" >"$tmp" || die "failed to update version in mkit.ini"
+    mv "$tmp" "$inifile"
+}

utils/mkit/include/mkit.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+die() {
+    #
+    # Exit with message and non-zero exit status
+    #
+    echo "fatal: $*" >&2
+    exit 4
+}
+
+mkit_import() {
+    #
+    # Import mkit module $1.sh
+    #
+    # Check for module, source it and die with reasonable message if needed.
+    #
+    local modname=$1
+    local modpath
+    modpath="$MKIT_DIR/include/$modname.sh"
+    test -f "$modpath" || die "no such module: $modpath"
+    bash -n "$modpath" || die "bad syntax: $modpath"
+    #shellcheck disable=SC1090
+    . "$modpath" || die "failed to import: $modname"
+}
+
+mkit_import build
+mkit_import deploy
+mkit_import release
+mkit_import ini
+
+__valid_targets() {
+    #
+    # List valid routes
+    #
+    echo _mkit_data
+    echo build
+    echo clean
+    echo debstuff
+    echo dist
+    echo install
+    echo release
+    echo release_x
+    echo release_y
+    echo release_z
+    echo rpmstuff
+    echo uninstall
+    echo vbump
+    echo vbump_x
+    echo vbump_y
+    echo vbump_z
+}
+
+debug() {
+    #
+    # Print debug message
+    #
+    $MKIT_DEBUG || return 0
+    echo "MKIT_DEBUG: ${FUNCNAME[1]}()" "$@" >&2
+}
+
+debug_var() {
+    #
+    # Print debug message
+    #
+    $MKIT_DEBUG || return 0
+    local __mkit_debug_var_name__       # variable name to debug
+    local decl                          # declare string
+    for __mkit_debug_var_name__ in "$@"; do
+        {
+            decl=$(declare -p "$__mkit_debug_var_name__")
+            decl=${decl#declare ?? }
+            echo "MKIT_DEBUG: ${FUNCNAME[1]}(): $decl"
+        } >&2
+    done
+}
+
+__compver() {
+    #
+    # True if version $1 matches our version
+    #
+    # If our x is 0, check first two fragments, otherwise check just
+    # the x.  Fragments must equal.
+    #
+    local their_ver=$1      # their version
+    local our_x             # our X
+    local our_y             # our Y
+    local their_x           # their X
+    local their_y           # their Y
+    their_x=${their_ver%%.*}
+    their_y=${their_ver##$their_x.}
+    their_y=${their_y%%.*}
+    our_x=${MKIT_VERSION%%.*}
+    our_y=${MKIT_VERSION##$our_x.}
+    our_y=${our_y%%.*}
+    debug_var MKIT_VERSION our_x our_y their_ver their_x their_y
+    test "$their_x" -eq "$our_x" || return 1
+    test "$our_x" -eq 0 && {
+        test "$their_y" = "$our_y"
+        return $?
+    }
+    return 0
+}
+
+__chkiniversion() {
+    #
+    # Check if ini version is supported
+    #
+    # Look for "#mkit version=0.0.0" or similar in first or last
+    # 3 lines of the file; then check if the version is supported.
+    #
+    local ver_line      # line declaring version
+    local their_ver     # the declared version
+    ver_line=$(
+        {
+            head -3 "$MKIT_INI"
+            tail -3 "$MKIT_INI"
+        } | grep -m 1 -E '^# *mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
+    )
+    test -n "$ver_line" \
+     || die "version mark ('#mkit version=x.y.z') not found in: $MKIT_INI"
+    their_ver="$(tr -d '[:blank:]v' <<<"${ver_line##*=}")"
+    __compver "$their_ver" \
+     || die "bad mkit.ini version: $their_ver does not match $MKIT_VERSION"
+}
+
+mkit_init() {
+    #
+    # Do basic initialization
+    #
+    # Check for ini file and some variables
+    #
+    $MKIT_DRY && MKIT_DEBUG=true
+    #shellcheck disable=SC2034
+    MKIT_PROJ_PKGNAME=$(ini 1value "project:pkgname")
+    test -f "$MKIT_INI" || die "cannot find mkit.ini: $MKIT_INI"
+    __chkiniversion
+}
+
+route() {
+    #
+    # Call correct function based on $1
+    #
+    if __valid_targets | grep -qwx "^$1"; then
+        "$1"
+    else
+        {
+            echo "usage: $(basename "$0") TARGET"
+            echo
+            echo "valid targets:"
+            __valid_targets | sed 's/^/    /'
+        } >&2
+    fi
+}
+
+warn() {
+    #
+    # Print warning message
+    #
+    echo "$@" >&2
+}

utils/mkit/include/release.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+mkit_import ini
+mkit_import facts
+
+__bump_version() {
+    #
+    # Bump version on stdin by level $1 (x, y or z)
+    #
+    local rlevel=$1     # release level
+    local old           # old version
+    local oldx          # ... X
+    local oldz          # ... Z
+    local oldy          # ... Y
+    local tmpy          # Y parsing cache
+    local new           # bumped version
+    read -r old
+    oldx=${old%.*.*}
+    oldz=${old#*.*.}
+    tmpy=${old%.*}
+    oldy=${tmpy#*.}
+    case $rlevel in
+        x) new="$((oldx+MKIT_BUMPSIZE)).0.0"            ;;
+        y) new="$oldx.$((oldy+MKIT_BUMPSIZE)).0"        ;;
+        z) new="$oldx.$oldy.$((oldz+MKIT_BUMPSIZE))"    ;;
+        *) die "invalid release level: $1"  ;;
+    esac
+    echo "$new"
+}
+
+__relck() {
+    #
+    # Die if blocking condition $1 is detected
+    #
+    local condition=$1      # condition name
+    local oracle            # expected value
+    case "$condition" in
+        git_present)
+            git rev-parse HEAD >&/dev/null\
+             || die "cannot do this outside git repo"
+            ;;
+        at_relsrc)
+            oracle=$(ini 1value project:relsrc)
+            git_fact current_branch \
+              | grep -qFx "$oracle" \
+             || die "you are not on release source branch: $oracle"
+            ;;
+        not_dirty)
+            git diff --shortstat 2>/dev/null \
+              | grep -q . \
+             && die "tree is dirty!"
+            ;;
+        tags_ok)
+            git_fact latest_tag \
+              | grep -q . \
+             || die "cannot find latest tag"
+            ;;
+        vbump_hot)
+            git diff-tree --no-commit-id --name-only -r HEAD \
+              | grep -qFx mkit.ini \
+             || die "last change must be version bump in mkit.ini"
+            ;;
+        no_wip)
+            git_fact reldiff \
+              | grep '^....... WIP ' \
+             && die "WIP commit since $(git_fact latest_tag)"
+            ;;
+        ini_version)
+            oracle=$(git_fact latest_version | __bump_version "$rlevel")
+            ini 1value project:version  \
+              | grep -qFx "$oracle" \
+             || die "new version not in mkit.ini: $oracle"
+            ;;
+        *)
+            die "unknown release check: $condition"
+            ;;
+    esac
+}
+
+__release() {
+    #
+    # Prepare release
+    #
+    # Span release routines: make a signed tag, check branch
+    # and update release branch
+    #
+    # FIXME: Using project:prerl as build.sh:semver() does may not be
+    #        compatible with this release strategy
+    #
+    local rlevel=$1     # release level (x, y or z)
+    local newtag        # new tag
+    local relsrc        # release source branch (if any)
+    local reldst        # release destination branch (if any)
+
+    __relck git_present
+    __relck at_relsrc
+    __relck not_dirty
+    __relck tags_ok
+    __relck vbump_hot
+    __relck no_wip
+    __relck ini_version
+
+    newtag=$(git_fact latest_version | __bump_version "$rlevel" | git_ver2tag )
+    set -e
+    debug_var newtag
+    $MKIT_DRY && return
+    git tag -m "$(__release_msg)" "$newtag"
+
+    relsrc=$(ini 1value project:relsrc)
+    reldst=$(ini 1value project:reldst)
+    debug_var relsrc reldst
+    if test -n "$reldst" && test "$reldst" != "$relsrc"; then
+        git branch -f "$reldst" "$newtag"
+    fi
+}
+
+__release_msg() {
+    #
+    # Generate message for annotated tag
+    #
+    # The last commit before issuing a release must be "Bump version" commit
+    # suggested by _vbump_gitmsg() and  manually edited by user.  Since the
+    # commit contains changelog, this function just uses the message body.
+    #
+    # The sort message (first line) is replaced with a nicer one (with project
+    # name, codename and version).
+    #
+    echo "$(ini 1value project:name) $newtag - $(ini 1value project:codename)"
+    echo
+    git show -s --format=%B \
+      | tail -n +3
+}
+
+__vbump() {
+    #
+    # Do version bump at level $1
+    #
+    # Perform checks, compute new version, update mkit.ini and initiate
+    # 'Bump version' commit with changelog template.
+    #
+    local rlevel=$1     # bump level (x, y or z)
+    local nextver       # version after the bump
+    local cache         # cache for the message
+    __relck git_present
+    __relck at_relsrc
+    __relck not_dirty
+    nextver=$(ini 1value project:version | __bump_version "$rlevel")
+    debug_var nextver
+    $MKIT_DRY && return
+    update_version "$nextver" mkit.ini \
+      || die "failed to update version in mkit.ini"
+    git add mkit.ini \
+      || die "failed to add mkit.ini to the index"
+    cache=$(mktemp -t "mkit._vbump_gitmsg.XXXXXXXX")
+    _vbump_gitmsg > "$cache"
+    git commit -e -F "$cache"   # note: reading from stdin will break vim
+    rm "$cache"
+}
+
+_vbump_gitmsg() {
+    #
+    # Compose git message template for 'Bump version' commit
+    #
+    echo "Bump version"
+    echo ""
+    echo "Overview of changes:"
+    echo ""
+    git_fact reldiff \
+      | sed '
+            s/^[a-f0-9]\{7\} /\n *  &/; t PATHS
+            s/^/        /
+            :PATHS
+        '
+}
+
+release() {
+    #
+    # Perform release on Z level
+    #
+    __release z
+}
+
+release_x() {
+    #
+    # Perform release on X level
+    #
+    __release x
+}
+
+release_y() {
+    #
+    # Perform release on Y level
+    #
+    __release y
+}
+
+release_z() {
+    #
+    # Perform release on Z level
+    #
+    __release z
+}
+
+vbump() {
+    #
+    # Perform version bump on Z level
+    #
+    __vbump z
+}
+
+vbump_x() {
+    #
+    # Perform version bump on X level
+    #
+    __vbump x
+}
+
+vbump_y() {
+    #
+    # Perform version bump on Y level
+    #
+    __vbump y
+}
+
+vbump_z() {
+    #
+    # Perform version bump on Z level
+    #
+    __vbump z
+}

utils/mkit/include/vars.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+#shellcheck disable=SC2034
+# MKit - simple install helper
+# See LICENSE file for copyright and license details.
+
+
+#
+# Bump size (for vbump_? and release_?)
+#
+MKIT_BUMPSIZE=${MKIT_BUMPSIZE:-1}
+
+#
+# Debug mode (true|false)
+#
+MKIT_DEBUG=${MKIT_DEBUG:-false}
+
+#
+# Default deploy mode for files
+#
+MKIT_DEFAULT_MODE="644"
+
+#
+# Dry mode (true|false)
+#
+# Set to true to not install anything. Implies MKIT_DEBUG.
+#
+MKIT_DRY=${MKIT_DRY:-false}
+
+#
+# Path to mkit.ini
+#
+MKIT_INI=${MKIT_INI:-mkit.ini}
+
+#
+# Limit ini expansion depth
+#
+# To avoid endless loops, this value is subtracted each
+# time ini() expands a reference; when zero is reached,
+# no more expansions happen.
+#
+MKIT_INI_EXPAND=2
+
+#
+# Path to MKit local config and temp
+#
+# Typically hidden in project root, here MKit can
+# save its temporary lists.
+#
+MKIT_LOCAL=${MKIT_LOCAL:-.mkit}
+
+#
+# Package name
+#
+# Used as base for tarball and in some default macros.
+#
+MKIT_PROJ_PKGNAME=""
+
+#
+# This MKit version
+#
+MKIT_VERSION=0.0.32

utils/mkit/make

@@ -0,0 +1,34 @@
+#!/bin/bash
+#shellcheck disable=SC2034
+# mkit - simple install helper
+# See LICENSE file for copyright and license details.
+
+init_core() {
+    #
+    # Load core module (or die)
+    #
+    #shellcheck disable=SC1090
+    . "$MKIT_DIR/include/mkit.sh" \
+     && . "$MKIT_DIR/include/vars.sh" \
+     && return 0
+    echo "failed to load core; check if MKIT_DIR is set properly: $MKIT_DIR" >&2
+    exit 9
+}
+
+#
+# Path to MKit dir (where 'include' is)
+#
+MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
+
+
+init_core
+
+case "$1" in
+    -V|--version-semver)    echo "$MKIT_VERSION"; exit 0 ;;
+    --version)              echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
+                            exit 0 ;;
+esac
+
+mkit_init
+
+route "$@"

utils/mkit/mkit.mk

@@ -0,0 +1,56 @@
+# mkit - Simple Makefile target helper
+# See LICENSE file for copyright and license details.
+
+export MKIT_DIR
+
+all: build
+
+_mkit_data:
+	@"$(MKIT_DIR)"/make _mkit_data
+
+build:
+	@"$(MKIT_DIR)"/make build
+
+clean:
+	@"$(MKIT_DIR)"/make clean
+
+debstuff: dist
+	@"$(MKIT_DIR)"/make debstuff
+
+dist: clean
+	@"$(MKIT_DIR)"/make dist
+
+rpmstuff: dist
+	@"$(MKIT_DIR)"/make rpmstuff
+
+install: all
+	@"$(MKIT_DIR)"/make install
+
+release:
+	@"$(MKIT_DIR)"/make release
+
+release_x:
+	@"$(MKIT_DIR)"/make release_x
+
+release_y:
+	@"$(MKIT_DIR)"/make release_y
+
+release_z:
+	@"$(MKIT_DIR)"/make release_z
+
+uninstall:
+	@"$(MKIT_DIR)"/make uninstall
+
+vbump:
+	@"$(MKIT_DIR)"/make vbump
+
+vbump_x:
+	@"$(MKIT_DIR)"/make vbump_x
+
+vbump_y:
+	@"$(MKIT_DIR)"/make vbump_y
+
+vbump_z:
+	@"$(MKIT_DIR)"/make vbump_z
+
+.PHONY: all _mkit_data clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z

utils/mkit/stub

@@ -0,0 +1,715 @@
+#!/bin/bash
+# mkit - simple install helper
+# See LICENSE file for copyright and license details.
+
+init_core() {
+    #
+    # Load core modules (or die)
+    #
+    #shellcheck disable=SC1090
+    . "$MKIT_DIR/include/mkit.sh" \
+     && . "$MKIT_DIR/include/vars.sh" \
+     && return 0
+    echo "failed to load core; check if MKIT_DIR is set properly: $MKIT_DIR" >&2
+    exit 9
+}
+
+#
+# Path to MKit dir (where 'include' is)
+#
+MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
+
+init_core
+
+mkit_import ini
+
+declare -A MKIT_STUB_LICENSES
+MKIT_STUB_LICENSES[GPLv1]="http://www.gnu.org/licenses/old-licenses/gpl-1.0.md"
+MKIT_STUB_LICENSES[GPLv2]="http://www.gnu.org/licenses/old-licenses/gpl-2.0.md"
+MKIT_STUB_LICENSES[GPLv3]="http://www.gnu.org/licenses/gpl-3.0.md"
+MKIT_STUB_LICENSES[LGPLv2]="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.md"
+MKIT_STUB_LICENSES[LGPLv3]="http://www.gnu.org/licenses/lgpl-3.0.md"
+MKIT_STUB_LICENSES[AGPLv3]="http://www.gnu.org/licenses/agpl-3.0.md"
+MKIT_STUB_LICENSES[FDLv1.3]="http://www.gnu.org/licenses/fdl-1.3.md"
+MKIT_STUB_LICENSES[FDLv1.2]="http://www.gnu.org/licenses/old-licenses/fdl-1.2.md"
+MKIT_STUB_LICENSES[FDLv1.1]="http://www.gnu.org/licenses/old-licenses/fdl-1.1.md"
+
+
+deploy() {
+    local file=$1       # which known file?
+    local any_name=${NiceName:-$PackageName}
+    local tmp
+    tmp=$(mktemp -t mkit.stub.deploy.XXXXXXX)
+    mkdir -p "$(dirname "$file")"
+    case $file in
+
+        Makefile)
+            echo -n "# $any_name"
+            test -n "$Tagline" && echo -n " - $Tagline"
+            echo
+            $MkLicense && echo '# See LICENSE.md file for copyright and license details.'
+            echo ''
+            echo 'MKIT_DIR=utils/mkit'
+            #shellcheck disable=SC2016
+            echo 'include $(MKIT_DIR)/mkit.mk'
+            ;;
+
+        README.md)
+            echo "$any_name"
+            tr -c '=\n' '=' <<<"$any_name"
+            echo ''
+            if test -n "$Tagline"; then
+                echo "$Tagline"
+            else
+                echo "(Nothing to say about this project.)"
+            fi
+            ;;
+
+        */mkit.ini|mkit.ini)
+            echo "[project]"
+            {
+                echo "version = $Version"
+                test -n "$Codename"     && echo "codename    = $Codename"
+                test -n "$NiceName"     && echo "name        = $NiceName"
+                test -n "$Tagline"      && echo "tagline     = $Tagline"
+                test -n "$PackageName"  && echo "pkgname     = $PackageName"
+                test -n "$Maintainer"   && echo "maintainer  = $Maintainer"
+                test -n "$VcsBrowser"   && echo "vcs_browser = $VcsBrowser"
+                test -n "$RelSrc"       && echo "relsrc      = $RelSrc"
+                test -n "$RelDst"       && echo "reldst      = $RelDst"
+            } | reformat_section
+            if updating; then
+                remake_section dist
+                remake_section ENV
+                remake_section roots
+                remake_section macros
+                remake_section modes
+                remake_section files
+            else
+                echo ""
+                echo "[dist]"
+                {
+                    $MkLicense  && echo "tarball = LICENSE.md"
+                    $MkMakefile && echo "tarball = Makefile"
+                    $MkReadme   && echo "tarball = README.md"
+                    echo "tarball = mkit.ini"
+                    $MkPackaging && echo "tarball = packaging"
+                    echo "tarball = src"
+                    echo "tarball = tests"
+                    echo "tarball = utils"
+                    $MkPackaging && echo "rpmstuff = packaging/template.spec"
+                    $MkPackaging && echo "debstuff = packaging/debian"
+                } | reformat_section
+                echo ""
+                echo "[ENV]"
+                {
+                    echo "    PREFIX = /usr/local"
+                } | reformat_section
+                echo ""
+                echo "[roots]"
+                {
+                    echo "bin = [ENV:PREFIX]/bin"
+                    echo "doc = [ENV:PREFIX]/share/doc/$PackageName"
+                } | reformat_section
+                echo ""
+                echo "[macros]"
+                {
+                    echo "__${PackageName^^}_FOO__ = Barr.."
+                } | reformat_section
+                echo ""
+                echo "[modes]"
+                {
+                    echo "bin = 755"
+                    echo "doc = 644"
+                } | reformat_section
+                echo ""
+                echo "[files]"
+                {
+                    echo "bin = src/$PackageName"
+                    $MkLicense && echo "doc = LICENSE.md"
+                    $MkReadme  && echo "doc = README.md"
+                } | reformat_section
+            fi
+            echo ""
+            echo "#mkit version=$MKIT_VERSION"
+            ;;
+
+        packaging/template.spec)
+            echo 'Name:       __MKIT_PROJ_PKGNAME__'
+            echo 'Version:    __MKIT_PROJ_VERSION__'
+            echo 'Release:    1%{?dist}'
+            echo 'Summary:    __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
+            test -n "$VcsBrowser" && echo 'URL:        __MKIT_PROJ_VCS_BROWSER__'
+            $MkLicense && echo "License:    $License"
+            echo 'Source0:    %{name}-%{version}.tar.gz'
+            echo 'BuildArch:  noarch'
+            echo ''
+            echo 'Requires: MKIT_STUB_REQUIRES'
+            echo '%description'
+            echo 'MKIT_STUB_DESCRIPTION'
+            echo ''
+            echo '%prep'
+            echo '%setup -q'
+            echo ''
+            echo '%build'
+            echo 'make %{?_smp_mflags} PREFIX=/usr'
+            echo ''
+            echo '%install'
+            echo '%make_install PREFIX=/usr'
+            echo ''
+            echo '%files'
+            echo 'MKIT_STUB_FILELIST'
+            echo ''
+            echo '%changelog'
+            echo ''
+            echo '# specfile built with MKit __MKIT_SELF_VERSION__'
+            ;;
+
+        packaging/debian/copyright)
+            echo ""
+            ;;
+
+        packaging/debian/control)
+            echo 'Source: __MKIT_PROJ_PKGNAME__'
+            echo 'Maintainer: __MKIT_PROJ_MAINTAINER__'
+            test -n "$VcsBrowser" && echo 'Vcs-Browser: __MKIT_PROJ_VCS_BROWSER__'
+            echo 'Section: misc'
+            echo 'Priority: extra'
+            echo 'Standards-Version: 3.9.2'
+            echo 'Build-Depends:'
+            echo ' debhelper (>= 9),'
+            echo ''
+            echo 'Package: __MKIT_PROJ_PKGNAME__'
+            echo 'Architecture: all'
+            echo 'Depends: MKIT_STUB_REQUIRES'
+            echo 'Description: __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
+            echo ' MKIT_STUB_DESCRIPTION'
+            echo ''
+            echo '# control file built with MKit __MKIT_SELF_VERSION__'
+            ;;
+
+        packaging/debian/changelog)
+            echo '__MKIT_PROJ_PKGNAME__ (__MKIT_PROJ_VERSION__-1) UNRELEASED; urgency=medium'
+            echo ''
+            echo '  * Initial release. (Closes: #XXXXXX)'
+            echo ''
+            echo " -- __MKIT_PROJ_MAINTAINER__  $(date -R)"
+            ;;
+
+        packaging/debian/compat)
+            echo 9
+            ;;
+
+        packaging/debian/rules)
+            echo '#!/usr/bin/make -f'
+            echo ''
+            echo '%:'
+            echo ''
+            echo '	dh $@'
+            echo ''
+            echo 'override_dh_auto_install:'
+            echo ''
+            echo '	make install PREFIX=/usr DESTDIR=debian/tmp'
+            ;;
+
+        packaging/debian/source/format)
+            echo '3.0 (quilt)'
+            ;;
+
+        packaging/debian/install)
+            echo MKIT_STUB_FILELIST
+            ;;
+
+        src/*.skel)
+            echo 'echo "my version is: __MKIT_PROJ_VERSION__"'
+            echo 'echo "And that'"'"'s all, folks!"'
+            ;;
+
+        LICENSE.md)
+            local url   # license URL
+            url="${MKIT_STUB_LICENSES[$License]}"
+            curl -sf "$url" \
+             || die "failed to download license: $url"
+            ;;
+
+        .mkit/autoclean)
+            ;;
+
+        MKIT_STUB_README.md)
+            echo "FINISHING MKIT CONFIGURATION"
+            echo "============================"
+            echo ""
+            echo "Congratulations, your new project has been configured!"
+            echo ""
+            echo "However, the *stub* script is not able to figure out"
+            echo "everything, so few things still need to be done manually."
+            echo "This document will guide you throught the rest of the"
+            echo "process."
+            echo ""
+            echo ""
+            echo "Structure"
+            echo "---------"
+            echo ""
+            echo "First, let's go through the directory structure:"
+            echo ""
+            echo " *  *src* directory - here is your main place to store"
+            echo "    source files.  This includes also documents like user"
+            echo "    manuals---IOW, anything intended to end up on user's"
+            echo "    machine should be uder 'src'."
+            echo ""
+            echo "    Note that during build time, files named ending with"
+            echo "    '.skel' are subject to macro expansion, see mkit.ini"
+            echo "    section below for details."
+            echo ""
+            echo " *  *notes* directory - here you shall store notes"
+            echo "    intended for people contributing to your project,"
+            echo "    for instance, guidelines, coding style documents,"
+            echo "    TODOs, ideas, plans..."
+            echo ""
+            echo " *  *utils* directory - here you shall store utilities"
+            echo "    and scripts that will help you with project maintenance,"
+            echo "    and that, unlike software like compilers or versioning"
+            echo "    systems, can (and should) be embedded inside the"
+            echo "    repository."
+            echo ""
+            echo "    MKit itself is one nice example. :)"
+
+            if $MkPackaging; then
+            echo ""
+            echo " *  *packaging* directory contains templates that enable"
+            echo "    MKit create raw stuffs used to create DEB or RPM"
+            echo "    packages.  Similar to '.skel' files in 'src', all files"
+            echo "    here are automatically considered for macro expansion,"
+            echo "    no matter how they are named (see mkit.ini section"
+            echo "    below)."
+            echo ""
+            echo "    NOTE: these templates, as well as any packages created by"
+            echo "    them are intended only for experimental, private use and"
+            echo "    testing."
+            echo ""
+            echo "    Should you have ambition to create 'real' packages for"
+            echo "    OS distribution such as Debian or Fedora (what a great"
+            echo "    idea!), be prepared that you will need to follow their"
+            echo "    guidelines.  This will most probably mean huge changes"
+            echo "    to these packages or even changes to your workflow."
+            echo ""
+            echo ""
+            echo "Placeholders"
+            echo "------------"
+            echo ""
+            echo "At places where *stub* script did not have way to get all"
+            echo "information automatically, it has inserted placeholders."
+            echo "You will need to go through all of these placeholders and"
+            echo "replace them with proper data."
+            echo ""
+            echo "Please follow instructions:"
+            echo ""
+            echo " 1. Look for placeholders starting with \`MKIT_STUB_\`"
+            echo "    prefix by calling this command:"
+            echo ""
+            echo "        grep -l MKIT_STUB_ -r"
+            echo ""
+            echo " 2. Go through each file and locate the placeholder.  (You"
+            echo "    will also see placeholders like \`__MKIT_*__\`, you can"
+            echo "    ignore those."
+            echo ""
+            echo " 3. Replace placeholder with appropriate information:"
+            echo ""
+            echo "     *  \`MKIT_STUB_REQUIRES\` - Requirements of your"
+            echo "        project."
+            echo ""
+            echo "     *  \`MKIT_STUB_DESCRIPTION\` - Description of your"
+            echo "        project (few sentences to paragraphs)."
+            echo ""
+            echo "     *  \`MKIT_STUB_FILELIST\` - List of full paths to"
+            echo "        your files after installation."
+            echo ""
+            echo "        Note that in case of debian/install files, PREFIX"
+            echo "        based paths (eg. /usr/bin) in this file should be as"
+            echo "        if PREFIX was /usr."
+            echo ""
+            echo "        In case of Fedora-based distro, you should make use"
+            echo "        of RPM macros:"
+            echo ""
+            echo "            https://fedoraproject.org/wiki/Packaging:RPMMacros"
+            echo ""
+            echo "    Refer to these documents for further details:"
+            echo ""
+            echo "        http://rpm-guide.readthedocs.io/"
+            echo "        https://www.debian.org/doc/manuals/maint-guide/"
+            fi
+
+            echo ""
+            echo ""
+            echo "mkit.ini"
+            echo "--------"
+            echo ""
+            echo "Most sections still need to be reviewed. In order to do"
+            echo "that, you will need to understand how MKit works:"
+            echo ""
+            echo " 1. First, you need to define *roles* your files will play"
+            echo "    when they are installed on user's file systems.  These"
+            echo "    roles then imply where and how the files should be"
+            echo "    deployed."
+            echo ""
+            echo "    Typical example of a role is e.g. 'bin' for commands"
+            echo "    (normally under '/usr/bin' or '/usr/local/bin'), 'doc'"
+            echo "    for documents or 'lib' for libraries."
+            echo ""
+            echo " 2. Next, in \`[roots]\` section, you have to set target"
+            echo "    root directory for each role.  However, in order to"
+            echo "    enable people to implement local conventions, it is"
+            echo "    considered a good manner to also respect PREFIX"
+            echo "    environment variable.  For this reason, most paths"
+            echo "    need to start with \`[ENV:PREFIX]\`."
+            echo ""
+            echo " 3. \`[files]\` section is where you assign actual files"
+            echo "    from your repository to their final paths.  The format"
+            echo "    is \`ROLE = REPOPATH [RENAMED]\`, where ROLE is file's"
+            echo "    role, REPOPATH is relative path to the file."
+            echo ""
+            echo "    Final path is then composed by taking path assigned to"
+            echo "    ROLE and appending file's name.  However, if you need"
+            echo "    the deployed file to have different name than in the"
+            echo "    codebase, you can specify the other name as RENAMED."
+            echo ""
+            echo "    Note that you don't need to address every single file"
+            echo "    individually, if in your repo you have a directory with"
+            echo "    100 files of the same role, you can add just path to the"
+            echo "    directory itself."
+            echo ""
+            echo " 4. If some roles require special permissions on your files,"
+            echo "    \`[modes]\` section is your friend.  Permissions here"
+            echo "    should be in UNIX octal format."
+            echo ""
+            echo " 5. Next, \`[macros]\` section allows you to define own"
+            echo "    placeholders that will be replaced when your scripts are"
+            echo "    built.  Each file in 'src' directory that is named with"
+            echo "    '.skel' suffix, and each file from 'packaging' directory"
+            echo "    (no matter its name), can contain one or more of macros"
+            echo "    defined here, plus range of macros automatically defined"
+            echo "    by MKit.  During build, these macros are replaced with"
+            echo "    their actual values."
+            echo ""
+            echo " 6. Less interesting, but important section is \`[dist]\`,"
+            echo "    which lists files in your codebase that will be added"
+            echo "    to distribution tarball (part of \"stuffs\" mentioned"
+            echo "    above).  Listing directory here will include all its"
+            echo "    contents, and normally it's OK to be very inclusive, so"
+            echo "    most of the time this section should be OK."
+            echo ""
+            echo " 7. Even less interesting is section \`[ENV]\`.  It is"
+            echo "    special in that it provides *default* value for an"
+            echo "    environment variable.  You almost never need to touch"
+            echo "    this."
+            echo ""
+            echo " 8. Finally, the most interesting section!  \`[project]\`,"
+            echo "    provides most general information for your project such"
+            echo "    as name and version."
+            echo ""
+            echo "    Note that the \`version\` key is another \"special"
+            echo "    snowflake\" -- it is now set to 0.0.0, and you **should"
+            echo "    not need** to change  it manually.  When you feel you"
+            echo "    a are ready to release next version of your evolving"
+            echo "    project, simply call \`make vbump\` and MKit will take"
+            echo "    care of everything!"
+
+            if $MkMakefile; then
+            echo ""
+            echo ""
+            echo "Makefile"
+            echo "--------"
+            echo ""
+            echo "*stub* script also created a Makefile for you, but all"
+            echo "it really does is include MKit's own mkit.mk, which in turn"
+            echo "only maps \`make\` targets to actual mkit script calls."
+            echo "Unless your project already uses GNU Make, you should not"
+            echo "need to change this file."
+            fi
+
+            if $MkReadme; then
+            echo ""
+            echo ""
+            echo "README.md"
+            echo "---------"
+            echo ""
+            echo "Each serious project needs a serious README.  Which is why"
+            echo "*stub* has created a 'stub' of one for you."
+            fi
+
+            echo ""
+            echo ""
+            echo "The final touch"
+            echo "---------------"
+            echo ""
+            echo "Once you have reviewed everything, just delete this file!"
+            ;;
+
+    esac >"$tmp"
+    cat "$tmp" > "$file"
+    rm "$tmp"
+}
+
+known_licenses() {
+    local key
+    local first=true
+    for key in "${!MKIT_STUB_LICENSES[@]}"; do
+        $first && echo "$key"  && continue
+        echo ", $key"
+    done
+}
+
+usage() {
+    {
+        echo "Usage:"
+        echo "   stub [options] new PKGNAME"
+        echo "   stub [options] update"
+        echo "   stub -L"
+        echo ""
+        echo "Options:"
+        echo ""
+        echo "    -c CODENAME   your project codename"
+        echo "    -t TAGLINE    your project tagline"
+        echo "    -b RELSRC     pre-release branch"
+        echo "    -B RELDST     post-release branch"
+        echo "    -n NICENAME   your project's 'nice' name"
+        echo "    -l LICENSE    your options's license (see -L)"
+        echo "    -m MAINT      project maintainer's name and e-mail"
+        echo "    -v URL        URL to public code browser"
+        echo "    -V VERSION    initial version (default: 0.0.0)"
+        echo "    -a            enable autoclean ('make clean' after"
+        echo "                  each 'make install')"
+        echo "    -g            make git commits before and adter"
+        echo "                  (implies -y)"
+        echo "    -y            don't ask, just do it"
+        echo "    -R            skip creating README.md"
+        echo "    -M            skip creating Makefile"
+        echo "    -P            skip creating packaging templates"
+        echo "    -L            list known licenses and exit"
+        echo ""
+        echo "PKGNAME should be packaging-friendly name, ie. consist"
+        echo "only of small letters, numbers, underscore and dash."
+        echo "For your 'real' name, use NICENAME, which can be any"
+        echo "string."
+    } >&2
+    exit 2
+}
+
+confirm() {
+    local response      # user's response to our warning
+    $Force && return 0
+    {
+        echo "Warning: This operation can be destructive for your"
+        echo "current codebase.  At least following files will be"
+        echo "created or overwritten:"
+        echo ""
+        $MkPackaging    && echo " *  'packaging' directory (pass -P to avoid)"
+        $MkMakefile     && echo " *  'Makefile' (pass -M to avoid)"
+        $MkReadme       && echo " *  'README.md' (pass -R to avoid)"
+        $MkLicense      && echo " *  'LICENSE.md' (omit -l to avoid)"
+        echo " *  'mkit.ini'"
+        echo ""
+        read -p "Type 'yes' to proceed: " -r response
+    } >&2
+    test "$response" == "yes" && return 0
+    warn "Aborting."
+    return 1
+}
+
+mkcommit_backup() {
+    git ls-files --others \
+      | grep -qv -e '^utils/mkit$' -e '^utils/mkit/' \
+     || { warn "nothing to back up"; return 0; }
+    git add .                           || return
+    git rm -r --cached utils/mkit       || return
+    git commit -m "WIP [mkit/stub] backup" || return
+}
+
+mkcommit_mkit_code() {
+    git ls-files --others \
+      | grep -q -e '^utils/mkit$' -e '^utils/mkit/' \
+     || return 0
+    git add utils/mkit || return
+    git commit -m "WIP [mkit/stub] Add MKit version v$MKIT_VERSION" || return
+}
+
+mkcommit_mkit_conf() {
+    local msg       # commit message (the important art
+    git add . || return
+    case $Action in
+        new)    msg="Add MKit configuration stub" ;;
+        update) msg="Update MKit configuration"   ;;
+    esac
+    git commit -m "WIP [mkit/stub] $msg" || return
+}
+
+deploy_packaging() {
+    rm -rf packaging
+    deploy packaging/template.spec
+    deploy packaging/debian/copyright
+    deploy packaging/debian/control
+    deploy packaging/debian/changelog
+    deploy packaging/debian/compat
+    deploy packaging/debian/install
+    deploy packaging/debian/rules
+    deploy packaging/debian/source/format
+}
+
+init_from_existing() {
+    #
+    # Initialize variables from old mkit.ini
+    #
+    test -f "$MKIT_INI" \
+     || die "mkit.ini not found; aborting update: $MKIT_INI"
+    user_gave Codename    || Codename=$(ini_raw1v project:codename)
+    user_gave License     || License=$(ini_raw1v project:license)
+    user_gave Maintainer  || Maintainer=$(ini_raw1v project:maintainer)
+    user_gave NiceName    || NiceName=$(ini_raw1v project:name)
+    user_gave PackageName || PackageName=$(ini_raw1v project:pkgname)
+    user_gave RelDst      || RelDst=$(ini_raw1v project:reldst)
+    user_gave RelSrc      || RelSrc=$(ini_raw1v project:relsrc)
+    user_gave Tagline     || Tagline=$(ini_raw1v project:tagline)
+    user_gave VcsBrowser  || VcsBrowser=$(ini_raw1v project:vcs_browser)
+    user_gave Version     || Version=$(ini_raw1v project:version)
+}
+
+ini_raw1v() {
+    #
+    # Read raw scalar from mkit.ini
+    #
+    local path=$1
+    MKIT_INI_EXPAND=0 ini 1value "$path"
+}
+
+user_gave() {
+    #
+    # True if user gave value to variable $1
+    #
+    local var=$1    # name of the variable
+    { test "${UserGave[$var]}" == 1; } 2>/dev/null
+}
+
+updating() {
+    #
+    # Are we updating?
+    #
+    test "$Action" == update
+}
+
+remake_section() {
+    #
+    # Re-compose mkit.ini section $1
+    #
+    local section=$1
+    local key
+    local value
+    ini lskeys "$section" | grep -q . \
+     || return 1
+    echo ""
+    echo "[$section]"
+    ini lskeys "$section" \
+      | while read -r key; do
+            MKIT_INI_EXPAND=0 ini values "$section:$key" \
+              | while read -r value; do
+                    echo "$key = $value"
+                done
+        done \
+      | reformat_section
+}
+
+reformat_section() {
+    #
+    # Re-format "k = v" on stdin as "nice" ini section
+    #
+    local key
+    local eq
+    local value
+    while read -r key eq value; do
+        test "$eq" == "=" || {
+            warn "ignoring malformed ini line: $key $eq $value"
+            continue
+        }
+        echo "$key = $value"
+    done \
+      | sed 's/ *= */=/; s/^ *//; s/ *$//' \
+      | column -t -s= -o' = ' \
+      | sed 's/^/    /'
+}
+
+main() {
+    local NiceName          # human-readable project name
+    local PackageName       # machine-safe project (package) name
+    local RelSrc            # pre-release branch
+    local RelDst            # post-release branch
+    local Codename          # release codename
+    local Tagline           # project tagline
+    local Maintainer        # project maintainer (Name + e-mail)
+    local VcsBrowser        # VCS browser (eg. GitHub URL)
+    local Version=0.0.0     # project version
+    local AutoClean=false   # touch .mkit/autoclean?
+    local MkCommits=false   # create pre/post git commits?
+    local Force=false       # go without asking?
+    local MkReadme=true     # create README.md?
+    local MkMakefile=true   # create Makefile?
+    local MkPackaging=true  # create packaging templates?
+    local MkLicense=false   # create LICENSE.md file
+    local Action            # 'update' to respect existing, 'new' to force
+                            # rewrite incl. MKIT_STUB_* placeholders
+    declare -A UserGave
+    while true; do case $1 in
+        -n) NiceName=$2;   UserGave[NiceName]=1;   shift 2 || usage ;;
+        -b) RelSrc=$2;     UserGave[RelSrc]=1;     shift 2 || usage ;;
+        -B) RelDst=$2;     UserGave[RelDst]=1;     shift 2 || usage ;;
+        -c) Codename=$2;   UserGave[Codename]=1;   shift 2 || usage ;;
+        -t) Tagline=$2;    UserGave[Tagline]=1;    shift 2 || usage ;;
+        -l) License=$2;    UserGave[License]=1;    shift 2 || usage ;;
+        -m) Maintainer=$2; UserGave[Maintainer]=1; shift 2 || usage ;;
+        -v) VcsBrowser=$2; UserGave[VcsBrowser]=1; shift 2 || usage ;;
+        -V) Version=$2;    UserGave[Version]=1;    shift 2 || usage ;;
+        -M) MkMakefile=false;   shift ;;
+        -R) MkReadme=false;     shift ;;
+        -a) AutoClean=true;     shift ;;
+        -y) Force=true;         shift ;;
+        -g) MkCommits=true;     shift ;;
+        -P) MkPackaging=false;  shift ;;
+        -L) known_licenses | tr , '\n'; exit 0 ;;
+        -*) usage ;;
+        *)  break ;;
+    esac done
+    Action=$1; PackageName=$2
+    case $Action:$PackageName in
+        new:)     usage ;;
+        new:*)    :     ;;
+        update:)  :     ;;
+        update:*) usage ;;
+        *)        usage ;;
+    esac
+    updating && init_from_existing
+    if test -n "$License"; then
+        known_licenses | grep -qxF "$License" \
+         || die "unknown license (use -L to get list): $License"
+        MkLicense=true
+    fi
+    if $MkCommits; then
+        mkcommit_backup || die "failed creating backup commit"
+        Force=true
+    fi
+    confirm            || return 1
+    deploy "$MKIT_INI"
+    deploy src/"$PackageName".skel
+    $MkMakefile     && deploy Makefile
+    $MkReadme       && deploy README.md
+    $MkLicense      && deploy LICENSE.md
+    $AutoClean      && deploy .mkit/autoclean
+    $MkPackaging    && deploy_packaging
+    if $MkCommits; then
+        mkcommit_mkit_code || die "failed creating post-commit"
+        mkcommit_mkit_conf || die "failed creating post-commit"
+    fi
+    deploy MKIT_STUB_README.md
+    warn "Configuration stub built, follow instructions in"
+    warn "MKIT_STUB_README.md to finish configuration."
+    return 0
+}
+
+main "$@"

utils/tfkit/doc/README.md

@@ -0,0 +1,399 @@
+TFKit
+=====
+
+
+Installation
+------------
+
+The easiest way is to embed TFKit within your repo, ie. clone TFKit and
+install it using:
+
+    make install DESTDIR=/path/to/your/repo
+
+Now you can run your test suite using *runtests* binary:
+
+    $ cd /path/to/your/repo
+    $ utils/tfkit/runtest
+
+Note that the above probably won't return any useful results as you still
+don't have any tests.
+
+
+Writing tests
+-------------
+
+Tests can be written in any scripting language, although the built-in
+framework, written in Bash, provides some useful features for writing
+certain kind of relatively simple tests.
+
+The harness, though, assumes that:
+
+ *  Any direct sub-directory of `$TF_SUITE` directory ("tests" by default)
+    that contains at least *TF_RUN* executable becomes a test,
+
+ *  basename of this directory becomes the name of the test,
+
+ *  and return code from running the executable is reported
+    as result of the test, according to "Exit status" section below.
+
+
+Naming
+------
+
+Test name should start with name of the module that is tested and
+underscore.  If module name contains dots, they should be replaced with
+underscores as well.
+
+    core_sanity
+    mod_submod_function
+    ini_iniread
+
+are valid test names.
+
+
+Data
+----
+
+Should the test need any data, just leave it around in the test directory
+along with *TF_RUN*.
+
+Note that before running, the whole test directory is automatically
+copied to a temporary location (one per test), and should the test fail,
+copied back as a debugging relic.  For this reason, *do not store
+huge amounts of data here*.  If you really need huge data, consider
+obtaining it (and throwing it away) within runtime of *TF_RUN*.
+
+
+Exit status
+-----------
+
+We try hard to follow this semantic:
+
+ *  *Zero* means *OK* -- test has been run and passed.
+
+ *  *One* means *Failure* -- test has been run but failed (e.g. found
+     a bug).
+
+ *  *Two* means *Bailout* --  test has decided not to run at all.
+
+ *  *Three* means *Error* -- there was error detected during execution,
+     but script was able to clean up properly.
+
+ *  *Four* means *Panic* -- there was other error but script *was not*
+     able to clean up properly.
+
+ *  Anything else should indicate other uncaught errors, including those
+    outside control of the program such as segfaults in the test code
+    or test being SIGKILLed.
+
+Notice that the higher the value is, the worse situation it indicates.
+Thus, if a test is composed of several sub-tests, you need to make sure
+to always **exit with the highest value** (subtest.sh does take care
+of this).
+
+See *common.sh* for functions and variables to help with handling exit
+statuses with this semantic.
+
+Also see Notes section for more details on exit statuses, including
+cheat sheet and dscussuion.
+
+
+Framework
+---------
+
+
+### harness.sh ###
+
+This part is not intended to be used in tests, but rather contains
+functions that help govern test discovery, preparation and execution as
+is described in previous sections.  Feel free to poke around, of course.
+
+
+### subtest.sh ###
+
+As name suggests, this file defines few functions to handle subtests
+in *TF_RUN*.
+
+In order to make use of the subtests functionality, you will need to
+define two functions yourself:  `tf_enum_subtests` to enumerate names of
+tests you want to run, and `tf_do_subtest` with actual test
+implementation.
+
+The minimal *TF_RUN* with two subtests could look like this:
+
+    #!/bin/bash
+
+    . $TF_DIR/include/subtest.sh
+
+    tf_enum_subtests() {
+        echo test1
+        echo test2
+        something && echo test3
+    }
+
+    tf_do_subtest() {
+        case $1 in
+            test1)  myprog foo ;;
+            test2)  myprog bar ;;
+            test3)  myprog baz ;;
+        esac
+    }
+
+    tf_do_subtests
+
+At the end, `tf_do_subtests` acts as a launcher of the actual test.
+In short, it will
+
+ 1. run `tf_enum_subtests`, taking each line as name of a subtest;
+    for each subtest:
+
+     1. source *TF_SETUP*, if such file is found,
+     2. launch the `tf_do_subtest()` function with subtest name as
+        the only argument,
+     3. source *TF_CLEANUP*, if such file is found,
+
+ 2. and finally, report "worst" exit status encountered.
+
+Note that subtest names need to be single words (`[a-zA-Z0-9_]`).
+
+
+### tools.sh ###
+
+This file contains various tools and utilities to help with testing.
+
+Curently there is only one function, `tf_testflt` designed to help write
+tests for simple unix filters.
+
+
+#### tf_testflt ####
+
+The idea is that tester specifies
+
+ *  test name,
+ *  command to launch the system under test,
+ *  a data stream to use as STDIN,
+ *  and expected STDOUT, STDERR, and exit status.
+
+and tf_testflt launches the command, collects tha data and evaluates
+and reports the result using unified diff.
+
+In its simplest form:
+
+    tf_testflt -n foo my_command arg
+
+the function will run `my_command arg` (not piping anything to it),
+and will expect it to finish with exit status 0 and empty both STDERR
+and STDOUT.
+
+Example of full form,
+
+    tf_testflt -n foo -i foo.in -O foo.stdout -E foo.stderr -S 2 myprog
+
+will pipe foo.in into `myprog`, expecting exit status of 2, and STDOUT and
+STDERR as above.  Notice that parameters specifying expected values are
+uppercase, and those specifying input values are lowercase.
+
+Specifying name is mandatory, because it's used in reporting messages,
+and as a basis for naming temporary result files: these are saved in
+*results* subdirectory and kept for further reference.
+
+
+### common.sh ###
+
+This includes simple functions and variables shared between both mentioned
+libraries.
+
+First group is designed to help support the exit status semantic:
+
+ *  The functions are `tf_exit_pass`, `tf_exit_fail`, `tf_exit_bailout`,
+    `tf_exit_error` and `tf_exit_panic` and each take any number of
+    parameters that are printed on stderr.
+
+ *  The variables are `TF_ES_OK`, `TF_ES_FAIL`, `TF_ES_BAILOUT`,
+    `TF_ES_ERROR` and `TF_ES_PANIC` and are supposed to be used with
+    `return` builtin, e.g. to return from `tf_exit_error`.
+
+Second group is useful to better control output:  functions `tf_warn`,
+`tf_debug` and `tf_think` are used to print stuff on STDERR.  Use of
+`tf_warn` is apparent, just as `tf_debug`, the latter being muted if
+`TF_DEBUG` is set to `false` (set it to `true` to turn on debugging).
+
+`tf_think` is used for progress info, and is muted unless `TF_VERBOSE`
+is set to `true`, which is by default.
+
+
+### Setup and cleanup ###
+
+Special files *TF_SETUP* and *TF_CLEANUP* (one of them or both) can be
+added along with *TF_RUN*.  These will be sourced before (*TF_SETUP*)
+and after every subtest (*TF_CLEANUP*).
+
+First, if any of these files are missing, it is considered as if the
+respective phase succeeded.  Second, if setup phase fails, test will
+be skipped and subtest exit status will be *TF_ES_BAILOUT*.   Last,
+if cleanup fails (no matter result of setup), subtests aborts with
+*TF_ES_PANIC* returned.  Be aware that in this case the actual test
+status, albeit useful, is lost.
+
+When coming from other test frameworks, this may feel harsh, but note
+that this has been designed with the idea that if a cleanup fails,
+it may render all further tests are automatically unsafe, because the
+environment is not as expected.
+
+To cope with this behavior, try to bear in mind following advice:
+
+ 1. Make sure you write setup/cleanup procedures with extreme care and
+    test them well.
+
+ 2. Do not do complicated and risky things in the setup/cleanup phases.
+
+ 3. If you need to do such things, consider doing them in the *TF_RUN*
+    instead of doing them for all subtests.
+
+ 4. You don't need to clean up everything, the contents of the testing dir
+    will be moved out from the test system.
+
+ 5. If there are scenarios you can safely fix or ignore, handle them in
+    a robust manner.
+
+
+Notes
+-----
+
+
+### bailout vs. `tf_enum_subtests` ###
+
+One more note to claify relation of bailout and `tf_enum_subtests`.
+As you may have noticed, there are two ways how to skip a test:
+return prematurely with `TF_ES_BAILOUT`, or suppress enumeration in
+`tf_enum_subtests`.  The problem is that the latter does not do anything
+to inform upper in the stack that a test has been skipped, which seems to
+break the principle described in previous sections.
+
+Don't confuse these mechanisms, though. Each is supposed to be used
+for distinct purpose.  Compare: by using the `tf_enum_subtests` you are
+saying that you actually **did not even want** to run the test in the
+first place.  By using `TF_ES_BAILOUT`, you are saying that you **wanted**
+to run the test but could not.
+
+A few common cases if that helps you:
+
+ *  If during the test you find out that for some reason it can't be
+    carried out (e.g. an external resource is not available, or
+    something outside the SUT is broken), use `TF_ES_BAILOUT`.
+
+        tf_enum_subtests() {
+            echo test1
+            echo test2
+            echo test3
+        }
+
+        tf_do_subtest() {
+            case $1 in
+                test1) do_stuff  ;;
+                test2) do_other_stuff ;;
+                test3) curl -s http://www.example.com/ >file \
+                        || return $TF_ES_BAILOUT
+                       do_stuff_with file ;;
+            esac
+        }
+
+ *  If you want to filter out some sub-tests for some platforms, e.g. a
+    test for only 64-bit architectures, or a test only for Mac OS (IOW,
+    you can safely say that running this sub-test would be totally
+    pointless on this box), use `tf_enum_subtests`--just omit this test
+    from enumeration.
+
+        tf_enum_subtests() {
+            echo test1
+            echo test2
+            if this_is_macos_x; then
+                echo test3
+            fi
+        }
+
+ *  If you want to disable (comment out test) that you might not have
+    implemented yet or is broken (and for some reason you still want
+    it to haunt the test code) or something else outside SUT is broken
+    and prevents you from running the test, use `tf_enum_subtests` and
+    properly comment the reasons in code.
+
+        tf_enum_subtests() {
+            echo test1
+            echo test2
+        #   echo test3      #FIXME: implement after bz1234
+        }
+
+ *  If in doubt, use `TF_ES_BAILOUT`.
+
+
+### On exit statuses: three and above ###
+
+The difference in *error*, *panic* and higher values is subtle but
+important.  Follow me as I try to explain:
+
+ 1. If script has changed something on the system outside the working
+    directory, it is apparently expected to revert that change.
+
+ 2. Now if an error occurs, but the code responsible for cleaning up is
+    safely run, you can say there was *error but we have recovered*.
+
+ 3. But if the change can't be reverted safely, we know that we have
+    broken something and latter code may lead to weird results (including
+    masking bugs(!)), it's time to *panic* (in the code, not in real
+    life ;))
+
+ 4. And then there are corner cases like a bug in the script, OOM kill
+    or timeout when the status will be different and not really controlled
+    by the script.  Such cases will have to be treated the same way as
+    the "panic" case, but...
+
+ 5. the use of *panic* adds hint that the status has been set consciously
+    by the script, albeit exiting "in a hurry"--without proper clean up.
+
+Unfortunately there will be cases like above but with the error code less
+than four.   Example is a Bash script syntax error, which returns 2, or
+Python exception which returns 1.  Yes, in such cases the information
+conveyed by the exit status is wrong and you should do everything to
+avoid it.
+
+Possibilities like "test has passed but then something blew up" exist,
+but conveying this information is responsibility of the test output.
+
+Following table can be used as a cheat-sheet:
+
+    .---------------------------------------------------------------.
+    | e |    state of         |                                     |
+    | s |---------------------| script says                         |
+    |   | SUT   | environment |                                     |
+    |---|-------|-------------|-------------------------------------|
+    | 0 | OK    | safe        | test passed, everything worked fine |
+    | 1 | buggy | safe        | test failed, everything worked fine |
+    | 2 | ???   | safe        | I decided not to run the test       |
+    | 3 | ???   | safe        | Something blew up but I managed to  |
+    |   |       |             | clean up (I promise!)               |
+    | 4 | ???   | broken      | Something blew up and I rushed out  |
+    |   |       |             | in panic                            |
+    | * | ???   | broken      | ...nothing (is dead)                |
+    '---------------------------------------------------------------'
+
+As you can see, following this semantic allows us to see both the state
+of the system under test (SUT) *and* the environment.
+
+Following table illustrates how different statuses map to different
+scenarios with regard to test result as well as state of the environment:
+
+    .--------------------------------------------------.
+    | environment |  test result   |  test result      |
+    |             | pass fail unkn | pass fail unkn    |
+    |-------------|----------------|-------------------|
+    | clean(ed)   |  0    1    3   |  OK  FAIL ERROR   |
+    | untouched   |  ~    ~    2   |  ~    ~   BAILOUT |
+    | mess        |  ~    ~    4   |  ~    ~   PANIC   |
+    | ?! (trap)   |  ~    ~    5   |  ~    ~   ~       |
+    | ?! (sig 9)  |  ~    ~    137 |  ~    ~   ~       |
+    | ?! (aliens) |  ~    ~    ?   |  ~    ~   ~       |
+    '-------------|----------------|-------------------|
+                  |  exit status   |  human-readable   |
+                  |                |  name (TF_ES_*)   |
+                  '------------------------------------'

utils/tfkit/doc/templates/grep_engine/TF_RUN

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+. "$TF_DIR/include/subtest.sh"
+. "$TF_DIR/include/tools.sh"
+
+tf_enum_subtests() {
+    echo fixed
+    echo basic
+    echo extended
+#   echo perl       # TODO: write test
+}
+
+tf_name2cmd() {
+    local name=$1
+    local t_in="test/ALL.stdin"
+    local o_out="oracle/$name.stdout"
+    local args
+    case $name in
+        fixed)       args="-F 'The mask *.* matches all.'" ;;
+        basic)       args="-G 'he.*'" ;;
+        extended)    args="-P '.*og?g'" ;;
+    esac
+    echo "tf_testflt -n $name -i $t_in -O $o_out grep $args"
+}
+
+tf_do_subtests

utils/tfkit/doc/templates/grep_engine/oracle/basic.stdout

@@ -0,0 +1,3 @@
+Linda and Nina work together.
+The mask *.* matches all.
+The mask *.docx matches Word documents.

utils/tfkit/doc/templates/grep_engine/oracle/extended.stdout

@@ -0,0 +1,3 @@
+Alice uses Google.
+Bob wears goggles.
+Linda and Nina work together.

utils/tfkit/doc/templates/grep_engine/oracle/fixed.stdout

@@ -0,0 +1 @@
+The mask *.* matches all.

utils/tfkit/doc/templates/grep_engine/test/ALL.stdin

@@ -0,0 +1,6 @@
+Alice uses Google.
+Bob wears goggles.
+Joe and John are friends.
+Linda and Nina work together.
+The mask *.* matches all.
+The mask *.docx matches Word documents.

utils/tfkit/doc/templates/simple/TF_RUN

@@ -0,0 +1,37 @@
+#!/bin/bash
+#shellcheck disable=SC1090
+
+. "$TF_DIR/include/subtest.sh"
+. "$TF_DIR/include/tools.sh"
+
+tf_enum_subtests() {
+    echo one
+    echo two
+    echo three
+}
+
+my_sut() {
+    local word=$1
+    declare -A map
+    map[one]=1
+    map[two]=2
+    map[three]=33
+    echo "${map[$word]}"
+}
+
+mkoracle() {
+    mkdir -p oracle
+    case $subtest in
+        one)    echo 1 ;;
+        two)    echo 2 ;;
+        three)  echo 3 ;;
+    esac > "oracle/$subtest.stdout"
+}
+
+tf_do_subtest() {
+    local subtest=$1
+    mkoracle
+    tf_testflt -n "$subtest" -O "oracle/$subtest.stdout" "my_sut $subtest"
+}
+
+tf_do_subtests

utils/tfkit/include/common.sh

@@ -0,0 +1,142 @@
+#
+# Variables to hold exit status semantic
+#
+TF_ES_OK=0
+TF_ES_FAIL=1
+TF_ES_BAILOUT=2
+TF_ES_ERROR=3
+TF_ES_PANIC=4
+
+#
+# Color definition variables
+#
+TF_COLOR_BLACK="\033[0;30m"
+TF_COLOR_RED="\033[0;31m"
+TF_COLOR_GREEN="\033[0;32m"
+TF_COLOR_YELLOW="\033[0;33m"
+TF_COLOR_BLUE="\033[0;34m"
+TF_COLOR_MAGENTA="\033[0;35m"
+TF_COLOR_CYAN="\033[0;36m"
+TF_COLOR_WHITE="\033[0;37m"
+TF_COLOR_LBLACK="\033[1;30m"
+TF_COLOR_LRED="\033[1;31m"
+TF_COLOR_LGREEN="\033[1;32m"
+TF_COLOR_LYELLOW="\033[1;33m"
+TF_COLOR_LBLUE="\033[1;34m"
+TF_COLOR_LMAGENTA="\033[1;35m"
+TF_COLOR_LCYAN="\033[1;36m"
+TF_COLOR_LWHITE="\033[1;37m"
+TF_COLOR_NONE="\033[1;0m"
+
+
+_tf__is_word() {
+    #
+    # Check if $1 contains only alphanumeric chars or _
+    #
+    local tainted=$1    # "dirty" version
+    local clean         # clean version
+    clean=$(tr -c -d '_[:alnum:]' <<< "$tainted")
+    test "$tainted" = "$clean"
+}
+
+tf_exit_ok() {
+    #
+    # Exit with OK status
+    #
+    exit $TF_ES_OK
+}
+
+tf_exit_fail() {
+    #
+    # Warn $1 and exit with status FAIL
+    #
+    tf_warn "$@"
+    exit $TF_ES_FAIL
+}
+
+tf_exit_bailout() {
+    #
+    # Warn $1 and exit with status FAIL
+    #
+    tf_warn "$@"
+    exit $TF_ES_BAILOUT
+}
+
+tf_exit_error() {
+    #
+    # Warn $1 and exit with status FAIL
+    #
+    tf_warn "$@"
+    exit $TF_ES_ERROR
+}
+
+tf_exit_panic() {
+    #
+    # Warn $1 and exit with status FAIL
+    #
+    tf_warn "$@"
+    exit $TF_ES_PANIC
+}
+
+tf_debug() {
+    #
+    # Emit debug message
+    #
+    $TF_DEBUG || return 0
+    local msg
+    for msg in "$@";
+    do
+        $TF_COLOR && echo -ne "$TF_COLOR_CYAN" >&2
+        echo "||| $msg" >&2;
+        $TF_COLOR && echo -ne "$TF_COLOR_NONE" >&2
+    done
+}
+
+tf_debugv() {
+    #
+    # Emit debug message showing value of each named variable
+    #
+    local varname
+    local declare_str
+    for varname in "$@";
+    do
+        if ! _tf__is_word "$varname";
+        then
+            tf_warn "tf_debugv: unsafe value skipped: $varname";
+            continue
+        fi
+        if declare_str=$(declare -p "$varname" 2>/dev/null);
+        then
+            tf_debug "${declare_str#declare ?? }"
+        else
+            tf_debug "$varname #Unset"
+        fi
+    done
+}
+
+tf_think() {
+    #
+    # Emit status/progress message
+    #
+    $TF_VERBOSE || return 0
+    local msg
+    for msg in "$@";
+    do
+        $TF_COLOR && echo -ne "$TF_COLOR_LBLACK" >&2
+        echo "$pfx$msg$sfx" >&2;
+        $TF_COLOR && echo -ne "$TF_COLOR_NONE" >&2
+    done
+}
+
+tf_warn() {
+    #
+    # Emit warning
+    #
+    local msg
+    for msg in "$@";
+    do
+        $TF_COLOR && echo -ne "$TF_COLOR_LRED" >&2
+        echo "$msg" >&2;
+        $TF_COLOR && echo -ne "$TF_COLOR_NONE" >&2
+    done
+}

utils/tfkit/include/harness.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# tfkit - Shellfu's movable test framework
+# See LICENSE file for copyright and license details.
+
+. "$TF_DIR/include/common.sh"
+
+
+__tf_collect_if_needed() {
+    #
+    # Collect relic if exit status suggests it
+    #
+    # Use test exit status $1 to help decide if relics are
+    # needed, and collect them if so.
+    #
+    # If TF_COLLECT is set to "always", collect regardless of
+    # the status.  If set to "never", do not collect anything.
+    # The default setting, "auto" collects unless status is 0
+    # or 1 (pass or bailout); in that case do nothing.
+    #
+    local tes=$1    # test exit status
+    local will      # should we collect relics?
+    case "$TF_COLLECT:$tes" in
+        always:*)   will=true ;;
+        never:*)    will=false ;;
+        auto:0)     will=false ;;
+        auto:2)     will=false ;;
+        auto:*)     will=true ;;
+        *)          tf_exit_bailout "bad value of TF_COLLECT: $TF_COLLECT" ;;
+    esac
+    $will || return 0
+    mkdir -p "$relic_dir/$stamp"
+    cp -r "$tmpdir"/* "$relic_dir/$stamp"
+}
+
+__tf_header() {
+    #
+    # create header to add to output before test
+    #
+    local hdrline                       # each line from generator
+    local hdrgen="$TF_SUITE/TF_HEADER"  # header generator script
+    tf_think "#"
+    tf_think "# ---"
+    tf_think "# tfkit:"
+    if test -x "$hdrgen";
+    then
+        tf_think "#     sut:"
+        $hdrgen \
+          | while IFS= read -r hdrline;
+            do
+                test -n "$hdrline" || break
+                tf_think "#         $hdrline"
+            done
+    else
+        tf_think "#     hint: >"
+        tf_think "#         Add $hdrgen executable for own header."
+        tf_think "#         It should output YAML (\"key: value\" pairs) about"
+        tf_think "#         your SUT ('version' at least')."
+    fi
+    tf_think "#     run:"
+    tf_think "#         start_time: $(date -Iseconds)"
+    test -n "$TF_FILTER_TEST" \
+     && tf_think "#         TF_FILTER_TEST: $TF_FILTER_TEST"
+    test -n "$TF_FILTER_SUBTEST" \
+     && tf_think "#         TF_FILTER_SUBTEST: $TF_FILTER_SUBTEST"
+    tf_think "#"
+    tf_think ""
+}
+
+tf_enum_tests() {
+    #
+    # List what looks like test; relative to $TF_SUITE
+    #
+    tf_debug "TF_SUITE='$TF_SUITE'"
+    test -d "$TF_SUITE" || return 0
+    find -L \
+        "$TF_SUITE" \
+        -mindepth 2 \
+        -maxdepth 2 \
+        -type f \
+        -perm /111 \
+        -name TF_RUN \
+      | cut -d/ -f2
+}
+
+tf_run_tests() {
+    #
+    # Discover and run tests
+    #
+    local es=0          # overall exit status
+    local tmpdir=""     # test temporary dir
+    local tname=""      # test name
+    local tes=0         # test result
+    local stamp=""      # test stamp to use as relic name
+    local tf_dir        # to keep absolute path for TF_RUN
+    local relic_dir     # where to keep relics
+    relic_dir="$(readlink -f "$TF_RELICS")"
+    __tf_header
+    tf_debug "TF_VERSION='$TF_VERSION'"
+    tf_dir="$(readlink -f "$TF_DIR")"
+    es=0
+    for tname in $(tf_enum_tests | grep -e "$TF_FILTER_TEST");
+    do
+        tf_think "... $tname"
+        tmpdir=$(mktemp -d)
+        stamp=$(date "+relics-$tname-%Y%m%d-%H%M%S")
+        cp -r "$TF_SUITE/$tname/"* "$tmpdir"
+        pushd "$tmpdir" >/dev/null
+            TF_DEBUG=$TF_DEBUG TF_VERBOSE=$TF_VERBOSE \
+            TF_DIR="$tf_dir" TF_TEST="$tname" \
+            TF_FILTER_SUBTEST=$TF_FILTER_SUBTEST \
+                ./TF_RUN
+            tes=$?
+            __tf_collect_if_needed $tes
+            test $tes -gt $es && es=$tes
+        popd >/dev/null
+        rm -rf "$tmpdir"
+        if test $tes -eq 0;
+        then
+            tf_think "''' $tname ($tes)"
+        else
+            tf_warn "??? $tname ($tes)"
+        fi
+    done
+    return $es
+}

utils/tfkit/include/subtest.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+. "$TF_DIR/include/common.sh"
+
+tf_enum_subtests() {
+    #
+    # Stub: enumerate subtests
+    #
+    tf_warn "implement tf_enum_subtests()!"
+    return "$TF_ES_ERROR"
+}
+
+tf_do_subtest() {
+    #
+    # Stub: perform test named $1
+    #
+    tf_warn "implement tf_do_subtest()!"
+    return "$TF_ES_ERROR"
+}
+
+_tf_do_subtest() {
+    #
+    # Run single subtest inc. setup/cleanup if present
+    #
+    local subtname="$1"     # this subtest name
+    local ses=0             # subtest exit status
+    local setup=true        # setup command
+    local cleanup=true      # cleanup command
+    if test -f TF_SETUP;
+    then
+        setup=". TF_SETUP"
+        bash -n TF_SETUP || {
+            tf_warn "synax errors in TF_SETUP, skipping"
+            return "$TF_ES_ERROR"
+        }
+    fi
+    if test -f TF_CLEANUP;
+    then
+        setup=". TF_CLEANUP"
+        bash -n TF_CLEANUP || {
+            tf_warn "synax errors in TF_CLEANUP, skipping"
+            return "$TF_ES_ERROR"
+        }
+    fi
+    if $setup;
+    then
+        tf_do_subtest "$subtname"; ses=$?
+    else
+        tf_warn "setup phase failed, skipping: $subtname"
+        ses=$TF_ES_ERROR
+    fi
+    if ! $cleanup;
+    then
+        tf_warn "cleanup phase failed: $subtname"
+        ses=$TF_ES_PANIC
+    fi
+    return "$ses"
+}
+
+tf_do_subtests() {
+    #
+    # Run all subtests and return highest status
+    #
+    local es=0              # final exit status ("worst" of subtests)
+    local subtname=""       # one subtest name
+    local tes=""            # one subtest exit status
+    local enumd=TF_ENUMERATED_SUBTESTS
+    local fltrd=TF_FILTERED_SUBTESTS
+    tf_enum_subtests >$enumd    || { tf_warn "error enumerating subtests"; return "$TF_ES_BAILOUT"; }
+    test -s $enumd              || { tf_warn "no subtests enumerated";     return "$TF_ES_BAILOUT"; }
+    grep -e "$TF_FILTER_SUBTEST" $enumd > $fltrd
+    test -s $fltrd  || tf_debug "TF_FILTER_SUBTEST ate everything: $TF_FILTER_SUBTEST"
+
+    for subtname in $(<$fltrd);
+    do
+        tf_think "::: $TF_TEST::$subtname"
+        TF_SUBTEST=$subtname _tf_do_subtest "$subtname";
+        tes=$?
+        test $tes -gt $es              && es=$tes
+        test $tes -gt "$TF_ES_OK"      && tf_warn "!!! $TF_TEST::$subtname ($tes)"
+        test $tes -gt "$TF_ES_BAILOUT" && break
+    done
+    return $es
+}

utils/tfkit/include/tools.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+. "$TF_DIR/include/common.sh"
+
+# 1. exec: [test] -> [result]
+# 2. eval:           [result] == [oracle]
+
+tf_testflt() {
+    #
+    # Run a simple test for a unix filter
+    #
+    #     tf_testflt -n foo [-i foo.stdin] \
+    #                [-O foo.stdout] [-E foo.stderr] [-S 3] \
+    #                cmd arg...
+    #
+    # Will drop *result/NAME.stdout* and *result/NAME.stderr* (intentionally
+    # not cleaning up).
+    #
+
+    # defaults
+    #
+    local t_in="/dev/null"      # test: stdin
+    local t_name=""             # test: name
+                                # command is "$@" after arg parsing
+    local t_es="0"              # final test exit status
+    local o_out="/dev/null"     # oracle: stdout
+    local o_err="/dev/null"     # oracle: stderr
+    local o_es="0"              # oralce: exit status
+    local r_out r_err r_es      # result: ^ ^ ^ those 3
+
+    local diff=diff
+    type colordiff >/dev/null 2>/dev/null && diff=colordiff
+
+    # get args
+    #
+    local orig_args="$0 $*"
+    tf_debug "orig_args=$orig_args"
+    local arg_err=false
+    while true; do case "$1" in
+        -i) t_in="$2";          shift 2 || { arg_err=true; break; } ;;
+        -n) t_name="$2";        shift 2 || { arg_err=true; break; } ;;
+        -O) o_out="$2";         shift 2 || { arg_err=true; break; } ;;
+        -E) o_err="$2";         shift 2 || { arg_err=true; break; } ;;
+        -S) o_es="$2";          shift 2 || { arg_err=true; break; } ;;
+        --)                     shift; break ;;
+        "")                            break ;;
+        -*) tf_warn "wrong testcli arg: $1"; return $TF_ES_BAILOUT ;;
+        *)                             break ;;
+    esac done
+    $arg_err && { tf_warn "error parsing arguments: $orig_args"; return $TF_ES_BAILOUT; }
+    tf_debug "t_in='$t_in'"
+    tf_debug "t_name='$t_name'"
+    tf_debug "o_out='$o_out'"
+    tf_debug "o_err='$o_err'"
+    tf_debug "o_es='$o_es'"
+    tf_debug "test command: $*"
+    test "$t_in" = "-" && t_in=/dev/stdin   # works better for check below
+    test -z "$t_name"  && { tf_warn "missing test name"             ; return $TF_ES_BAILOUT; }
+    test -z "$1"       && { tf_warn "missing test command"          ; return $TF_ES_BAILOUT; }
+    test -r "$t_in"    || { tf_warn "missing input file: $t_in"     ; return $TF_ES_BAILOUT; }
+    test -e "$o_out"   || { tf_warn "missing oracle stdout: $o_out" ; return $TF_ES_BAILOUT; }
+    test -e "$o_err"   || { tf_warn "missing oracle stderr: $o_err" ; return $TF_ES_BAILOUT; }
+    test "$o_es" -ge 0 || { tf_warn "invalid oracle status: $o_es"  ; return $TF_ES_BAILOUT; }
+
+    # prepare
+    #
+    mkdir -p result
+    r_out="result/$t_name.stdout"
+    r_err="result/$t_name.stderr"
+    tf_debug "r_out='$r_out'"
+    tf_debug "r_err='$r_err'"
+    touch "$r_out" || { tf_warn "cannot create tmp file: $r_out" ; return $TF_ES_BAILOUT; }
+    touch "$r_err" || { tf_warn "cannot create tmp file: $r_err" ; return $TF_ES_PANIC; }
+
+    # run
+    #
+    ( <"$t_in" eval "$@" >"$r_out" 2>"$r_err" ); r_es=$?
+    tf_debug "r_es='$r_es'"
+
+    # eval/report/exit
+    #
+    test $r_es = $o_es || { tf_warn "bad exit status: $r_es (need $o_es)" ; t_es=$TF_ES_FAIL; }
+    $diff -u "$o_err" "$r_err" || t_es=$TF_ES_FAIL
+    $diff -u "$o_out" "$r_out" || t_es=$TF_ES_FAIL
+    return $t_es
+}

utils/tfkit/runtests

@@ -0,0 +1,92 @@
+#!/bin/bash
+# tfkit - Shellfu's movable test framework
+# See LICENSE file for copyright and license details.
+
+TF_VERSION="0.0.16"
+
+die() {
+    echo "$@" && exit 9
+}
+
+usage() {
+    echo "usage: $(basename "$0") [-c|-C] [-t tests_re] [-s subtest_re] [-p binpath] [-v] [-d]" >&2
+    exit 2
+}
+
+version() {
+    echo "TFKit (A trivial test kit) $TF_VERSION"
+    exit 0
+}
+
+#
+# Relic directory path
+#
+TF_RELICS="${TF_RELICS:-relics}"
+
+#
+# Relic collection mode
+#
+# 'always' to always collect, 'never` to never collect and 'auto'
+# to collect only on failed tests.
+#
+TF_COLLECT="${TF_COLLECT:-auto}"
+
+#
+# Enable color?
+#
+TF_COLOR=${TF_COLOR:-true}
+
+#
+# Turn on debug mode?
+#
+TF_DEBUG="${TF_DEBUG:-false}"
+
+#
+# Location of own directory
+#
+TF_DIR=${TF_DIR:-$(dirname "$0")}
+
+#
+# Regex (BRE) to filter subtests based on name
+#
+TF_FILTER_SUBTEST=${TF_FILTER_SUBTEST:-}
+
+#
+# Regex (BRE) to filter tests based on name
+#
+TF_FILTER_TEST=${TF_FILTER_TEST:-}
+
+#
+# Location of test suite
+#
+TF_SUITE="${TF_SUITE:-tests}"
+
+#
+# Turn on verbosity?
+#
+TF_VERBOSE=${TF_VERBOSE:-true}
+
+
+. "$TF_DIR/include/harness.sh" \
+ || die "cannot import harness; is TF_DIR set properly?: $TF_DIR"
+
+main() {
+    while true; do case "$1" in
+        -c|--collect)           TF_COLLECT=always;          shift ;;
+        -C|--no-collect)        TF_COLLECT=never;           shift ;;
+        -d|--debug)             TF_DEBUG=true;              shift ;;
+        -p|--prefix)            export PATH="$(readlink -f "$2")/bin:$PATH"
+                                                            shift 2 || usage ;;
+        -s|--filter-subtest)    TF_FILTER_SUBTEST="$2";     shift 2 || usage ;;
+        -t|--filter-test)       TF_FILTER_TEST="$2";        shift 2 || usage ;;
+        -v|--verbose)           TF_VERBOSE=true;            shift ;;
+        --version-semver)       echo "$TF_VERSION"; exit 0 ;;
+        --version)              version ;;
+        "") break ;;
+        *)  usage ;;
+    esac done
+    export LC_ALL=C
+    time tf_run_tests
+}
+
+main "$@"

utils/tfkit/tfkit.mk

@@ -0,0 +1,18 @@
+# tfkit - Shellfu's movable test framework
+# See LICENSE file for copyright and license details.
+#
+# To use, set TF_DIR (make macro) in your Makefile and
+# include this file.
+#
+# Adds `test` target.
+#
+# Note that running "runtests" directly should have the same
+# effect but you will need to set TF_DIR and/or TF_SUITE properly
+# unless they are default (see README)
+
+export TF_DIR
+
+test:
+	@$(TF_DIR)/runtests
+
+.PHONY: test