update(README):Clarify `user` directory

It is a directory meant to contain scripts regularly called directly
by user.

diff --git a/README.org b/README.org
index 261cdf568eeba261211eb5914884154b60aa269d..943649e18de07fd2f4186673d2aecf166b39cfdf 100644 (file)
--- a/README.org
+++ b/README.org
@@ -1,19 +1,23 @@
-* Baltakatei Executable Development
-
-The purpose of this project is to create and maintain executables
-produced by Steven Baltakatei Sandoval.
-
-** Contents
-
+* Baltakatei Executables Development
+#+TITLE: Baltakatei Executables Development
+#+AUTHOR: Steven Baltakatei Sandoval
+#+DATE:2021-03-04
+#+EMAIL:baltakatei@gmail.com
+#+LANGUAGE: en
+#+OPTIONS: toc:nil
+
+** Summary
+This repository contains publicly-sharable executables used by Steven
+Baltakatei Sandoval.  produced by Steven Baltakatei Sandoval.
+
+** Directory Structure
 *** ~archive~
 This directory contains files not actively used but useful for
 understanding long-term history of this project.
 
-
 *** ~doc~
 This directory contains documentation about files in this project.
 
-
 *** ~sysutils~
 This directory contains executable utilities meant to change operating
 system settings.
@@ -22,9 +26,6 @@ An example executable to be stored here may include:
 
 - A bash script that runs ~apt~ to configure a Debian GNU/Linux
   machine to compile executable binaries from source.
-- A bash script that appends the last modification date to a file name
-  would go here.
-
 
 *** ~unitproc~
 This directory contains executables meant to process data produced by
@@ -42,3 +43,18 @@ Example executables to be stored here may include:
 - A bash script that uses ~inotifywait~ to hash files immediately
   after they are modified and log the hashes to an option-specified
   path on disk.
+
+*** ~user~
+This directory contains executables meant to be regularly called
+directly by the user to perform one-off tasks.
+
+Examples may include:
+
+- A bash script that appends the last modification date to a file name
+  would go here.
+- A bash script that compresses a file with custom compression
+  settings.
+- A bash script that generates a random passphrase with a custom
+  alphabet and adjustable entropy.
+- A bash script that initializes a multiwindow terminal emulator
+  (i.e. ~tilix~) with custom initial working directories.

diff --git a/prvt b/prvt
index 6f119fd840e2cfc0b45f76e2afb1f7b9cdc35d9b..7805afe3ed275beedcd6928d1b97cf194fe7766a 160000 (submodule)
--- a/prvt
+++ b/prvt
@@ -1 +1 @@
-Subproject commit 6f119fd840e2cfc0b45f76e2afb1f7b9cdc35d9b
+Subproject commit 7805afe3ed275beedcd6928d1b97cf194fe7766a

diff --git a/user/bknpass b/user/bknpass
new file mode 100755 (executable)
index 0000000..c1c1d1a
--- /dev/null
+++ b/user/bknpass
@@ -0,0 +1,211 @@
+#!/bin/bash
+
+# Author: Steven Baltakatei Sandoval (baltakatei.com)
+#
+# License: This bash script, `bknpass`, is licensed under GPLv3 or
+# later by Steven Baltakatei Sandoval:
+#
+#    `bknpass`, an alphanumeric password generator
+#    Copyright (C) 2021  Steven Baltakatei Sandoval (baltakatei.com)
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    any later version.
+#
+#    This program 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 General Public License for more details.
+#
+#    A copy of the GNU General Public License may be found at
+#    <https://www.gnu.org/licenses/>.
+#
+# Description: This bash script generates alphanumeric passphrases
+# with a char-count determined by a user-provided number of bits of
+# entropy. The passphrase is then outputted to stdout with a trailing
+# newline. It works as follows:
+# 
+#   - Prompt user for an integer. This integer is the number of bits
+#     of entropy that the generated password should have.
+#
+#   - Check if user-provided string is an integer using `bash` regular
+#     expression test.
+#
+#   - Calculate the minimum number of bech32 base32 characters
+#     required to encode the specified number of bits of entropy.
+#
+#       - This step uses `bc` to calculate a logarithm float string
+#         and `awk` to convert the float into an integer, rounding up.
+#
+#   - Use `tr`, `/dev/urandom`, and `head` to generate a random
+#     alphanumeric string with the length calculated in the previous
+#     step.
+#
+#   - Use `echo` to display the passphrase in stdout with a trailing
+#     newline.
+#
+# Usage: bknpass [int]
+#
+# Example: bknpass 256
+#
+# Dependencies: bash, echo, bc, awk, tr, head. See end of file
+#
+# Tested on:
+#
+#   - GNU/Linux Debian 10
+
+
+#==Initialization==
+
+let ALPHABET_SIZE="32" # number of unique chars in bech32 base32 charset
+LOG_BASE=2 # Set logarithm base to 2
+
+# Define `echoerr` function which outputs text to stderr
+    # Note: function copied from https://stackoverflow.com/a/2990533
+function echoerr {
+    echo "$@" 1>&2;
+}
+
+# Define `rpass` function which generates a base32 passphrase of length $1 (ex: `rpass 20` generates a 20-char string)
+#   Note: function adapted from https://www.thegeekstuff.com/2010/04/unix-bash-function-examples/
+#   Note: base32 charset uses bech32 charset
+function rpass {
+    cat /dev/urandom | LC_ALL=C tr -cd "qpzry9x8gf2tvdw0s3jn54khce6mua7l" | head -c ${1:-22}
+}
+
+
+#==Main Program==
+
+# Define $ENTROPY_BIT_COUNT1 as argument $1 or prompt user if $1 is not defined.
+#     Note: argument test adapted from https://stackoverflow.com/a/6482403
+if [ -z "$1" ]
+then
+    echo "Entropy bit count argument (\$1) not supplied."
+    # Get from user the number of bits of entropy.
+    echoerr -n "Please specify the required strength of the password in bits of entropy (ex: 256):" # prompt via stderr
+    read ENTROPY_BIT_COUNT1
+else
+    ENTROPY_BIT_COUNT1="$1"
+fi
+
+# Check if $ENTROPY_BIT_COUNT1 is an non-negative integer
+#     Note: Regular expression test is adapted from https://stackoverflow.com/a/806923
+RETEST1='^[0-9]+$'
+if ! [[ $ENTROPY_BIT_COUNT1 =~ $RETEST1 ]] ; then
+   echo "error: Not an integer." >&2; exit 1    
+fi
+
+# Calculate minimum count of chars needed to encode $ENTROPY_BIT_COUNT1 with alphabet size of $ALPHABET_SIZE as float
+#     Solve ln(a^n)/ln(2)=b for n using `bc` where
+#       a=$ALPHABET_SIZE
+#       n=$CHAR_COUNT1_FLOAT
+#       b=$ENTROPY_BIT_COUNT1
+#     Note: `bc` logarithm usage adapted from http://phodd.net/gnu-bc/bcfaq.html#bashlog
+CHAR_COUNT1_FLOAT=$(echo "$ENTROPY_BIT_COUNT1*l($LOG_BASE)/l($ALPHABET_SIZE)" | bc -l)
+#     Note: Float will be of form "21.49744370650136860806".
+#     Note: This particular example float should be rounded to "22" later.
+
+# Round $CHAR_COUNT1_FLOAT1 up to next highest integer for use as argument in later bash functions.
+#     Note: awk expression from https://bits.mdminhazulhaque.io/linux/round-number-in-bash-script.html
+CHAR_COUNT1=$(echo "$CHAR_COUNT1_FLOAT" | awk '{print ($0-int($0)>0)?int($0)+1:int($0)}') 
+
+# Generate passphrase
+PASS1=$(rpass "$CHAR_COUNT1")
+echo -e "$PASS1"
+
+
+#==References==
+#
+# - How to echo a string as stderr instead of stdout.
+#   https://stackoverflow.com/a/2990533
+#   Author: James Roth
+#   Date: 2010-06-07T14:52Z
+#   Date Accessed: 2020-01-20
+#
+# - How to check if script argument exists or not.
+#   https://stackoverflow.com/a/6482403
+#   Author: phoxix
+#   Date: 2011-06-26T05:55Z
+#   Date Accessed: 2020-01-20
+#
+# - How to check that a string is an integer using regular expression test.
+#   https://stackoverflow.com/a/806923
+#   Author: Charles Duffy
+#   Date: 2009-04-30T13:32Z
+#   Date Accessed: 2020-01-20
+#
+# - How to use `bc` to calculate logarithms in Bash
+#   http://phodd.net/gnu-bc/bcfaq.html#bashlog
+#   Author: unknown
+#   Date Accessed: 2020-01-20
+#
+# - How to use `awk` to convert and round up a float to an integer.
+#   https://bits.mdminhazulhaque.io/linux/round-number-in-bash-script.html
+#   Author: Md. Minhazul Haque
+#   Date: 2015-01-09
+#   Date Accessed: 2020-01-20
+#
+# - How to use `/dev/urandom`, `tr`, and `head` to generate a random password in Bash.
+#   https://www.thegeekstuff.com/2010/04/unix-bash-function-examples/
+#   Author: SASIKALA, Ramesh Natarajan
+#   Date: 2010-04-21
+#   Date Accessed: 2020-01-20
+#
+# - Bech32 base32 charset
+#   https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
+#   Author: Pieter Wuille <pieter.wuille@gmail.com>
+#   Date: 2017-03-20
+#   License: BSD-2-Clause
+#   Date: Accessed: 2021-01-23
+#
+# - Dependencies: bash, echo, bc, awk, tr, head.
+#
+#     - GNU bash, version 5.0.3(1)-release (x86_64-pc-linux-gnu)
+#       Copyright (C) 2019 Free Software Foundation, Inc.
+#       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+#       This is free software; you are free to change and redistribute it.
+#       There is NO WARRANTY, to the extent permitted by law.
+#    
+#     - echo (GNU coreutils) 8.30
+#       Copyright (C) 2018 Free Software Foundation, Inc.
+#       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+#       This is free software: you are free to change and redistribute it.
+#       There is NO WARRANTY, to the extent permitted by law.
+#
+#       Written by Brian Fox and Chet Ramey.
+#    
+#     - bc 1.07.1
+#       Copyright 1991-1994, 1997, 1998, 2000, 2004, 2006, 2008, 2012-2017 Free Software Foundation, Inc.
+#    
+#     - GNU Awk 4.2.1, API: 2.0 (GNU MPFR 4.0.2, GNU MP 6.1.2)
+#       Copyright (C) 1989, 1991-2018 Free Software Foundation.
+#    
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#    
+#       This program 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 General Public License for more details.
+#    
+#       You should have received a copy of the GNU General Public License
+#       along with this program. If not, see http://www.gnu.org/licenses/.
+#    
+#     - tr (GNU coreutils) 8.30
+#       Copyright (C) 2018 Free Software Foundation, Inc.
+#       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+#       This is free software: you are free to change and redistribute it.
+#       There is NO WARRANTY, to the extent permitted by law.
+#    
+#       Written by Jim Meyering.
+#    
+#     - head (GNU coreutils) 8.30
+#       Copyright (C) 2018 Free Software Foundation, Inc.
+#       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+#       This is free software: you are free to change and redistribute it.
+#       There is NO WARRANTY, to the extent permitted by law.
+#    
+#       Written by David MacKenzie and Jim Meyering.

diff --git a/user/bkxz b/user/bkxz
new file mode 100755 (executable)
index 0000000..465369a
--- /dev/null
+++ b/user/bkxz
@@ -0,0 +1,39 @@
+#!/bin/bash
+
+# Date: 2020-04-09T00:09Z
+
+# Author: Steven Baltakatei Sandoval
+
+# Description: Compresses a file or directory using xz at max
+# settings. Saves compressed .tar.xz file in the same directory as the
+# original file.
+
+# Usage: bkxz [ file or dir ]
+
+echoerr() { echo "$@" 1>&2; } # Define error display function.
+
+TARGET="$1" # Identify first argument as target file or directory.
+
+if ! command -v tar >/dev/null 2>&1; then # Check that 'tar' command exists.
+    echoerr "ERROR: Command doesn't exist: tar";
+fi
+
+if ! command -v xz >/dev/null 2>&1; then # check that 'xz' command exist.
+    echoerr "ERROR: Command doesn't exist: xz. Suggestion: Install 'xz-utils' package.";
+    exit 1;
+fi
+
+if ! ( [ -f "$TARGET" ] || [ -d "$TARGET" ] ); then # check that TARGET is a file or dir.
+    echoerr "ERROR: Target is not a file or dir."; exit 1;
+fi
+
+
+TARGET_BASENAME="$(basename "$TARGET")" # Save name of target's basename (ex: 'input.txt' from '/tmp/input.txt').
+TARGET_DIRNAME="$(dirname "$TARGET")" # Save name of target's directory (ex: '/tmp' from '/tmp/input.txt').
+
+OUTPUT="$TARGET_DIRNAME"/"$TARGET_BASENAME".tar.xz # Define output file to be in same location as target but with .tar.xz extension.
+
+pushd "$TARGET_DIRNAME" 1>/dev/null 2>&1 # Temporarily navigate to directory holding TARGET.
+tar cf - "$TARGET_BASENAME" | xz -9e --lzma2=dict=1536MiB,mf=bt4,nice=273,depth=1000 > "$OUTPUT"
+echoerr "Archive saved at: $OUTPUT"
+popd 1>/dev/null 2>&1 # Return to original working directory.