Includes Argument Parser

Including within Awk script adds argument parsing functionality

---

• ⬆️ Top of Document

• 🏗️ Requirements

• ⚡ Quick Start (Option 1)

  • 💾 Clone
  • ➕ Install
  • 🔥 Uninstall
  • ⬆️ Upgrade
  • 🎩 Write an Awk script

• ⚡ Quick Start (Option 2)

  • 📝 Edit Your ReadMe File
  • 💾 Commit and Push
  • 🐚 Write a Bash wrapper script

• 🔣 API

• 🗒 Notes

• 📈 Contributing

  • 🔱 Forking
  • 💱 Sponsor

• 📇 Attribution

• ⚖️ Licensing

---

Requirements

GAwk should be installed for scripts to make use of this repository...

• Arch based Operating Systems

sudo packman -Syy

sudo packman -S gawk make

• Debian derived Distributions

sudo apt-get update

sudo apt-get install gawk make

---

Quick Start (Option 1)

Perhaps as easy as one, 2.0,...

---

Clone

Clone this project to a root owned directory...

cd /usr/local/etc

sudo git clone https://github.com/awk-utilities/includes-argument-parser.git

---

Install

Install via make...

cd /usr/local/etc/includes-argument-parser

sudo make install

---

Uninstall

Uninstall/unlink via make...

cd /usr/local/etc/includes-argument-parser

sudo make uninstall

---

Upgrade

Upgrading in the future may be done via upgrade Make target...

cd /usr/local/etc/includes-argument-parser

sudo make upgrade

---

Write an Awk Script

If this project was installed via make, then any Awk script should be able to include this project via @include "argument-parser" statement, eg...

include-installed.awk

#!/usr/bin/gawk -f


## For updates see -> https://github.com/awk-utilities/includes-argument-parser
@include "argument-parser"


BEGIN {
  delete parsed_arguments
  delete acceptable_arguments

  acceptable_arguments["string"] = "--string|-s:value"
  acceptable_arguments["boolean"] = "--boolean|-B:bool"
  acceptable_arguments["usage"] = "--usage:bool"
  acceptable_arguments["increment"] = "--increment|-I:increment"
  acceptable_arguments["array"] = "--array:array"

  argument_parser(acceptable_arguments, parsed_arguments)
  for (k in parsed_arguments) {
    if (k == "array") {
      for (i in parsed_arguments[k]) {
        print "parsed_arguments[\"" k "\"][" i "] ->", parsed_arguments[k][i]
      }
    } else {
      print "parsed_arguments[\"" k "\"] ->", parsed_arguments[k]
    }
  }
}

Provide executable permissions...

chmod u+x include-installed.awk

Then run the Awk script...

./include-installed.awk -t 'string like value' -f --increment -I -I
#> parsed_arguments["flag"] -> 1
#> parsed_arguments["increment"] -> 3
#> parsed_arguments["test"] -> string like value

---

Quick Start (Option 2)

Alternatively for individual scripts, this repository encourages the use of Git Submodules to track dependencies...

Bash Variables

_module_name='includes-argument-parser'
_module_https_url="https://github.com/awk-utilities/includes-argument-parser.git"
_module_base_dir='modules'
_module_path="${_module_base_dir}/${_module_name}"

Bash Submodule Commands

cd "<your-git-project-path>"

git checkout gh-pages
mkdir -vp "${_module_base_dir}"

git submodule add\
 -b main --name "${_module_name}"\
 "${_module_https_url}" "${_module_path}"

---

Your ReadMe File

Suggested additions for your ReadMe.md file so everyone has a good time with submodules

Clone with the following to avoid incomplete downloads


    git clone --recurse-submodules <url-for-your-project>


Update/upgrade submodules via


    git submodule update --init --merge --recursive

Commit and Push

git add .gitmodules
git add "${_module_path}"


## Add any changed files too


git commit -F- <<'EOF'
:heavy_plus_sign: Adds `awk-utilities/includes-argument-parser#1` submodule



**Additions**


- `.gitmodules`, tracks submodules AKA Git within Git _fanciness_

- `README.md`, updates installation and updating guidance

- `modules/includes-argument-parser`, Including within Awk script adds argument parsing functionality
EOF


git push origin gh-pages

---

Write a Bash wrapper script

If utilizing this project as a submodule, then it's less error-prone to use -i, or --include, option within a wrapper Bash script, eg...

#!/usr/bin/env bash


## Find true directory script resides in
__SOURCE__="${BASH_SOURCE[0]}"
while [[ -h "${__SOURCE__}" ]]; do
    __SOURCE__="$(find "${__SOURCE__}" -type l -ls | sed -n 's@^.* -> \(.*\)@\1@p')"
done
__DIR__="$(cd -P "$(dirname "${__SOURCE__}")" && pwd)"

__ARGS__=( "${@}" )


gwak --include="${__DIR__}/modules/includes-argument-parser/argument-parser.awk"\
     'BEGIN {
       delete parsed_arguments
       delete acceptable_arguments

       acceptable_arguments["string"] = "--string|-s:value"
       acceptable_arguments["boolean"] = "--boolean|-B:bool"
       acceptable_arguments["usage"] = "--usage:bool"
       acceptable_arguments["increment"] = "--increment|-I:increment"
       acceptable_arguments["array"] = "--array:array"

       argument_parser(acceptable_arguments, parsed_arguments)
       for (k in parsed_arguments) {
         if (k == "array") {
           for (i in parsed_arguments[k]) {
             print "parsed_arguments[\"" k "\"][" i "] ->", parsed_arguments[k][i]
           }
         } else {
           print "parsed_arguments[\"" k "\"] ->", parsed_arguments[k]
         }
       }
     }' "${__ARGS__[@]}"

🎉 Excellent 🎉 your project is now ready to begin unitizing code from this repository!

---

API

Types available for acceptable_arguments

• value default if type is undefined, reads left side of = or next ARGV as value

• bool, or boolean, sets 1 for true

• increment adds 1 to value of parsed_arguments array

• array, or list, appends read value to array within parsed_arguments array

_acceptable_arguments {ArrayReference}

  Array reference of acceptable arguments


_parsed_arguments     {ArrayReference}

  Array reference that parsed arguments should be saved to


__key__               {string}

  Associative array key that points to `_acceptable_arguments[__key__]` value


__acceptable_parts__  {string[]}

  Array split by `:` from `_acceptable_arguments[__key__]` value


__pattern__           {string}

  Regexp pattern from `_acceptable_arguments[__key__]` value


__type__              {string}

  Default `"value"` from `_acceptable_arguments[__key__]` value


__index__             {number}

  Index that points to value within `ARGC`


__argument_parts__    {string[]}

  Array split by `=` from `ARGC[__index__]` value


__parameter__         {string}

  Value from `__acceptable_parts__[1]`

API Notes

• Dunder variables are function scoped, and should not be assigned by caller.

• Use gawk -h to list parameters that parser may conflict with.

---

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

---

The @include option within GAwk scripts uses paths listed within AWKPATH environment variable...

gawk 'BEGIN { print ENVIRON["AWKPATH"]; }'
#> .:/usr/share/awk

... The path list is separated by : and generally includes only the current working directory (.), and /usr/share/awk paths. At this time modifying the AWKPATH environment variable within an Awk script seems not to be possible.

---

As of version 4.1.4 when including files via @include within an Awk script from /usr/share/awk path, GAwk will not explore sub-directories, eg...

/usr/share/awk/sub-directory/include-test.awk

#!/usr/bin/gawk -f

function bad_example() {
  print "You cannot import this!"
}

./bad-includes.awk

#!/usr/bin/gawk -f

@include "sub-directory/include-test"

BEGIN {
  bad_example
}

Example of running bad-includes.awk

chmod u+x ./bad-includes.awk

./bad-includes.awk
#> gawk: ./bad-includes.awk:3: error: can't open source file `sub-directory/include-test' for reading (No such file or directory)

---

Contributing

Options for contributing to includes-argument-parser and awk-utilities

---

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/awk-utilities/includes-argument-parser

git remote add fork git@github.com:<NAME>/includes-argument-parser.git

• Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/awk-utilities/includes-argument-parser


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

---

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as includes-argument-parser that awk-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

---

Attribution

• GitHub -- github-utilities/make-readme

• GNU Awk -- 2.7 -- Including Other Files into Your Program

• GNU Awk -- 2.5.1 -- The AWKPATH Environment Variable

• StackExchange -- Unix -- Command line argument in Awk

---

License

Including within Awk script adds argument parsing functionality
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.