xSHELL is a simple library system for bash/shell.

Index

• Index
• Install
• xshell Command
  • Example of Usage (libsExample script)
    • Code gerenated
    • Adding custom code
    • libsExample output
• Libraries
  • init
  • args
  • system
  • colors
  • utils
• TODO List

---

Install

Steps to install xSHELL library system

curl -sSL https://raw.githubusercontent.com/fbnmtz/xSHELL/master/install | bash 

After run install command, you will have xSHELL on your home and added to your system $PATH

• ~/bin/xSHELL

---

xshell Command

Within this library, comes xshell tool used create new scripts;

xshell -h

usage:
  xshell [-a <arguments>] [-e <editor>] [-f <name>] [-H] [-l] [-o <output>] [-h] [-v]

-> Available Options:
   -a,  --args <arguments> define <arguments> for new script
   -e,  --editor <editor>  define <editor> to open script
   -f,  --filename <name>  filename for new script
   -H,  --header           enable our default header on the new script
   -l,  --lib              define new script as a our LIB type (can be loaded with 'use' function)
   -o,  --output <output>  setup <output> directory for new script
   -h,  --help             show this help
   -v,  --version          print version and exit

v0.1.17-rc316 - writen by @fbnmtz 2020

Go Back

Example of Usage (libsExample script)

You can create your new script (default location $HOME/bin) using xshell tool:

xshell -f libsExample \
    -e nano \
    --args "
        -p,--print;code='echo.print.test';desc='print.some.code' 
        -n,--notify;var=title+r,text+r;desc='test.notify.system' 
        -m,--math;var=expression+r;desc='solve.math.expression'  
        -V,--volume;var=option+r;desc='volume.option.(up.or.down)'
    "

Code gerenated

xshell command above will generate this code below and open the new file on defined editor:

#!/usr/bin/env bash
# script: libsExample

_AUTHOR_="@fbnmtz"
_CREATED_AT_="2023"
_CURRENT_VERSION_="0.0.1"

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
# shellcheck disable=SC1090,SC2154
#   * SC1090: Can't follow non-constant source. Use a directive to specify location.
#       -> cant follow or source usage
#   * SC2154: var is referenced but not assigned.
#       -> variables will be created by or library system (don't worry)

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
source ~/bin/xSHELL/init
use args

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
xarg --id -p,--print --code 'echo print test' --desc 'print some code'
xarg --id -n,--notify --var title+r,text+r --desc 'test notify system'
xarg --id -m,--math --var expression+r --desc 'solve math expression'
xarg --id -V,--volume --var option+r --desc 'volume option (up or down)'
# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
# initilizae values before xrun (if you need to)

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
# arguments will be checked/validated here (use --xhelp arg for more info)
xrun --xreject-unknow --xrequire-one "$@"

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~
# now put your code below

Adding custom code

After it, you can create all your code using args defined earlier.

Example:

# code for -m/--math arg
if [ -n "$expression" ] ; then
    echo $(($expression))
fi

# test notification function on lib/system 
if [ -n "$title" ]; then
    xsys.notify "$title" "$text"
fi

# test volume function on lib/system
if [ -n "$option" ]; then
    xsys.vol "--$option"
    xsys.notify Volume "$option" # - $(xsys.vol "--status")"
fi

libsExample output

The code above will generate this output

# check help
libsExapmle -h

usage:
  libsExapmle [-p] [-n <title> <text>] [-m <expression>] [-V <option>] [-h] [-v]

-> Information Options:
   -p,  --print                 print some code
   -n,  --notify <title> <text> test notify system
   -m,  --math <expression>     solve math expression
   -V,  --volume <option>       volume option (up or down)
   -h,  --help                  show this help
   -v,  --version               print version and exit

v0.0.6-rc81 - writen by @fbnmtz 2023

# using --math option
libsExapmle --math "2*2"
4

Go Back

---

Libraries

init

Basic library to initialize our framework/system.

• Variables

  • $APP
    • Store current script name
  • $APP_DIR
    • Store current script path
  • $APP_HOME
    • Default location to script save configs and related files

• Functions

  • xsetHome {dir1, dir2}
    • Create $APP_HOME directory. Default localtion is $HOME/.fbnmtz/$APP
  • use lib1 lib2 lib3
    • function to easily load libraries into your script
  • xrequirements binary1 binary2
    • function to check if a binary exists on your system. Pass program names separeted by spaces. Throw an error and exit if not found.
    • you can test conditional binarys using this syntax: xrequirements bin1:bin2 (that means bin1 or bin2)

args

This library is used to manage/generate/validate the command line arguments of a script.

Functions

• xarg

  • used to define arguments:

  # params supported:
    * --id <shortflat,longflag>
      * should be used with '--var' or '--code' 
        1. --var <var1:varvalue,var2+r,+o>
          1.1. `var:value`: this arg will set a var `var=value`
          1.2. `var+r`: (+r=required) this arg will require a new arg and i (can't be null)
          1.3. `var+o`: (+o=optional) this arg accepts another argument (but can be null)
        2. --code <shell commands>
          2.1. this arg will run arg received with `eval` function
    * --desc <description>
      * define description for this argument (will be used in help/usage information)
  
  # Examples of usage of 'xarg' function:
  
  xarg --id "-h,--help"    --code "xusage --help"                      --desc "show this help"
  xarg --id "-v,--version" --code "echo "$_CURRENT_VERSION_"; exit" --desc "print version and exit"
  
  

• xrun

  • validates arguments

  # params to define validations:
    * --xrequire-one
    * --xreject-unknow
  
  # set version format to use release candidate version:
    * --xversionrc
  
  # help / information 
    * --xdebug 
    * --xhelp
  

• xhelp

  • set help information to the script. Mostly used internally but you can use it to set header and footer information.

  # usable argumnets
    * --header=<value>
    * --footer=<value>
  

• xusage

• xflag_require_value

• xrequire_one

system

Library to by an interface between your scritp and Operation System, providin some basic functions.

colors

This library set variables with ANSI codes allowing you to use colors on your script. 

• Variables

  # reset ansi escaping
  $RESET
  # styles
  $BOLD
  $DIM
  $UNDERLINED
  $BLINK
  $REVERSE
  $HIDDEN
  # foreground colors
  $BLACK
  $RED
  $GREEN
  $YELLOW
  $BLUE
  $MAGENTA
  $CYAN
  $WHITE
  # background colors
  $BGBLACK
  $BGRED
  $BGGREEN
  $BGYELLOW
  $BGBLUE
  $BGMAGENTA
  $BGCYAN
  $BGWHITE

utils

A collection of auxiliary functions.

Functions

• getPath

  • return full path of a first binary of all received via arguments

    # usage
    getPath nano vim micro emacs

• basePath

  • return base path of a file

  # return /etc
  basepath /etc/passwd

• tern

  • ternary command

    tern "expr" "true value" "false value"

• isROOT?

  • check if current user is root

• requireROOT

  • require root to continue script (non root users? exit)

Go Back

---

TODO List

• xshell: add support for define args for new scripts
• Implent color system (draft)
• lib/args: Implements joint flags (ex: -lsaf)
• Create/integrate some library or system for Objetc Orientation (OO)
• Adjust some libs and scripts to work on MacOs

Go Back

---

Contributions are welcome! <3

Made with ❤️ and shellscript.