Package: ahd
Ad-Hoc DispatcherCreate ad-hoc macros to be dispatched within their own namespace.Table of contentsWhat does ahd do?Features & RoadmapPath ExpansionCross PlatformDynamic Execution & OrganizationRoadmapExample use casesWhy should I use ahd?Who is ahd for?Quick StartDependenciesInstallationFrom PyPiFrom SourceUsageRegisterUsing a Registered CommandListDocsConfigContact/ContributeGlossaryAdditional DocumentationThis readme will give you enough information to get up and running with ahd. If you are confused about terminology used then take a look at theglossary sectionof the docs. If you are looking for more in-depth documentation:Additional user and development/contribution documentation will be available athttps://ahd.readthedocs.io/en/latest/API documentation is available athttps://kieranwood.ca/ahdWhat does ahd do?ahd allows you to take annoying to remember commands and organize them into easy to re-use macros.Features & RoadmapPath ExpansionMacros can take full advantage of wildcards + regex to match directories.
For example if you wanted to delete all PDFs in all folders on the desktop you can usesudo ahd register no-pdfs "rm *.pdf" "~/Desktop/*".*nix and windows path adages are cross-platform. For example~is converted to%USERPROFILE%on windows,\paths are converted to/on *nix systems and vice-versa.Cross platformahd natively supports windows and any *nix systems (including Mac OS).Supports copy-paste cross platform configurations (assuming the same commands and file structure are on both)
For example if you want to write a command that git pulls in a folder called/developmenton your desktop using the *nix standard~/Desktop/development/*works on both *nix and windows.Dynamic Execution & OrganizationOne YAML file contains the configuration for all your macros instead of being all over the place.Macros can be updated manually (editing the YAML file), or simply re-registered.The defined Paths and commands can be overwritten on each use (seeoverridingfor details).RoadmapA full roadmap for each project version can be found here:https://github.com/Descent098/ahd/projectsExample use casesReally the possibilities are only limited to what you can type in your regular terminal, but here are some good examples:Update every git repo in a directoryOrganize your downloads folder by various filetypesMulti-stage project compilation/build in various directoriesWhy should I use ahd?The easiest way to understand why this project is useful is with an example. Let's say you want to write a simple script to take all the PDF's in a directory and put them in a.7zarchive and then remove them. Well all you need is this simple command7za a -t7z PDFs.7z *.pdf && rm *.pdf...Yeah, pretty awful to remember. Assuming we want to do this every so often let's make a script we can call. Currently with bash you need to drop the script inusr/bin(and try to remember what you called it), or add it to your bash/fish/zsh aliases (assuming you use the alias file, or.bashrcetc. if you don't), and on windows it's just not even worth it.Enter ahd, you can register a macro (lets call it zip-pdfs) using the same annoying command, in this casesudo ahd register zip-pdfs "7za a -t7z PDFs.7z *.pdf && rm *.pdf" ".". Now when we want to re-use this macro in the directory we're in you just typeahd zip-pdfs.If you forget the name there's a list command, and if you use a longer name there's bash autocomplete (fish and zsh support coming later).Who is ahd for?The primary audience is developers looking to speed up annoying workflows. However there are a number of other people it could benefit, such as:devops specialists; can use ahd to create a common set of macros across servers .dual booters; people who want one common config for multiple OS's.testers; if you need to execute multiple tests on various systems you can write one macro to run them all.etc; people who are sick of having a bunch of random scripts everywhere and want one config file for complex commands.Quick-startDependenciesPython 3.6+ (or is at least only tested and officially supported for 3.6+)pip for pythonInstallationOnce you have python3 and pip you have a few installation options.From PypiRunpip install ahdorsudo pip3 install ahd(need a network connection)From sourceClone this repo: (https://github.com/Descent098/ahd)Runpip install .orsudo pip3 install .in the root directory (one with setup.py)UsageUsage:ahd[-h][-v]ahdlist[-l]ahddocs[-a][-o]ahdconfig[-e][-iCONFIG_FILE_PATH]ahdregister<name>[<command>][<paths>]ahd<name>[<command>][<paths>][-d]Options:-h,--helpshowthishelpmessageandexit-v,--versionshowprogram'sversionnumberandexit-l,--longShowsallcommandsinconfigurationwithpathsandcommands-a,--apishowsthelocalAPIdocs-o,--offlineshowsthelocalUserdocsinsteadofliveones-e,--exportexportstheconfigurationfile-iCONFIG_FILE_PATH,--importCONFIG_FILE_PATHimportstheconfigurationfile-d,--detailsprintsthedetailsofacommandRegisterThe register command allows you to register a command to be used later on.Required Arguments:<name>;  This is apositionalplaceholder value for the name of a command you  are registering. Once the command is registered you can run it by usingahd <name>.<command>;  This is apositionalplaceholder value for the macro you want to run when the command is used after being registered. For example if you wanted to delete all the PDF's in a directory the macro you would normally run isrm *.pdfand so you would doahd register <name> "rm *.pdf" <paths>.It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts.<paths>;  This is apositionalplaceholder value for the path(s) that you want the command to run the macro in by default. For example if you wanted to a command to execute a macro on the desktop when it's run you can doahd register <name> <command> "~/Desktop".It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts. Additionally you can specify multiple directories through comma delimiting, for example:ahd register <name> <command> "~/Desktop, ~/Documents, ~/Pictures", or you can usepath expansionwhich will match directories through regex or wildcards. For example to run a command in all directorieswithinthe desktop you could doahd register <name> <command> "~/Desktop/*"or just use regex to match paths more explicitly for example to only include folders on the desktop that are numbers between 0-9 you could do:ahd register <name> <command> "~/Desktop/[0-9]".Using a Registered CommandYou can use a registered command by simply typingahd <name>, where<name>is whatever name you gave to the command.Optional Arguments:<command>; This is an optional positional argument that lets you overwrite the command, while retaining the registered paths. For example lets say you have a set of paths registered with a command that typically runsgit pullover the specified paths. You want to run a different command on the paths (lets say remove all the pdfs in the folder) You can do:ahd <name> "rm *.pdf"which will executerm *.pdfinstead ofgit pullon the defined paths.It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts.<paths>; This is an optional positional argument that lets you overwrite the paths the command will run against. To retain the original command you must use a ".". So for example lets say you have a command registered that runsgit pullagainst~/Desktop/*, but now you want to rungit pullagainst~/Documents/*you can useahd <name> "." "~/Documents/*"and it will run the macro against~/Documents/*instead of~/Desktop/*It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts. Additionally you can specify multiple directories through comma delimiting, for example:ahd register <name> <command> "~/Desktop, ~/Documents, ~/Pictures", or you can usepath expansionwhich will match directories through regex or wildcards. For example to run a command in all directorieswithinthe desktop you could doahd register <name> <command> "~/Desktop/*"or just use regex to match paths more explicitly for example to only include folders on the desktop that are numbers between 0-9 you could do:ahd register <name> <command> "~/Desktop/[0-9]".listThe list command shows a list of your current registered commands.Optional Arguments:-l or --long: Shows all commands in configuration with the registered paths and macros.docsThe docs command is designed to bring up documentation as needed, you can runahd docsto open the documentation site in the default browser.Optional Arguments:-a or --api: Used to serve local API documentation (Not yet implemented)-o or --offline: Used to serve local user documentation (Not yet implemented)configThis command is used for configuration management. It is recomended to useregisterto register/update commands. The config command is for managing configurations manually take a look at the documentation for details aboutmanual configuration.Optional Arguments:-e --export: Export the current configuration file (calledahdconfig.yml)-i --import: Import a configuration file; takes the path to the config file as an argumentContact/ContributeFor a full contribution guide, check thecontribution section of the documentation. Also be sure to check thefaqbefore submitting issues.For any additional questions please submit then through githubhere(much faster response), or my emailkieran@canadiancoding.ca.ChangelogV 1.0.0; June 6th 2022The version was bumped to a major release because pre V0.5.0 configs have been fully deprecated, if you are using an old config see migration steps belowThere are 3 primary focuses for this release:Improve developer/contributor documentation and infrastructureAdd metadata to configs so you can review how you use ahdFinalize some features that make ahd more intuitive and simple to useFeatures:Added spell-check for suggestions when input is close to a valid commandAdded additional metadata to config file for each entry:updated: The datestamp when the command was updated (will update on re-registering)created: The datestamp when the command was created (will not update on re-registering)runs: The number of times a command has been runlast_run: The datestamp when the command was last run (initially "never")Added-dflag to display command detailsAdded command metadata for usage details like how many times it's been run and when it was added (access usingahd <command> -d)Also will provide details like the current config for a given command, similar toahd listbut for a single commandUpdated testing to run on a schedule for quicker bug awarenessUpdated testing for coverage of all modulesAllowed for globbing paths with filesfor example you can run a command over all files by extension in a path usingahd register <command name> "<command>" "/path/*.<extension>"Documentation:Added documentation about removing migration for preV0.5.0configurationsBug Fixes:Fixed errors in testing pipelineFixed bugs with initializing a config fileAdded missing reserved commands to autocompleteFixed bugs on *nix installs without bashFixed several bugs with escaping on *nix systemsMigrating old configs:in order to migrate old configs install ahd v0.5.0pip install --upgrade ahd==0.5.0then follow guide here (ignore step 1):Migrating from Pre v0.5.0 configs - Ad-Hoc Dispatcher (ahd.readthedocs.io)Once updated to new config reinstall latest version usingpip install --upgrade ahdV 0.5.0; August 22nd 2020Focus for this release was to make it easier to understand how to use and contribute to ahd, to convert from configparser to PyYaml and cleanup some left over errors in deepsource.Features:Replaced configparser withPyYaml; see migration notice in the docs for detailsDocumentation:Overhauled user documentation site for clarityRevamped READMEAdded GlossaryRevamped contribution guideAdded Code Style guideCleaned up wording surrounding what the project actually doesTransitioned from full roadmap project boards to per-release project boardsBug Fixes:Inability to build from sdist due to missing files; Thanks tothatchfor the fixFixed testing pipeline in github actionsV 0.4.0; February 10th 2020Focus for this release was breaking up command line parsing into more testable chunks.Features:All argument parsing is now based on discrete functionsAdded a list command to show your current available commandsDocumentation:Created API documentation site:https://kieranwood.ca/ahdV 0.3.0; February 6th 2020Focus for this release was on building sustainable development pipelines (logging, testing etc.), and making the project more reliable in edge cases and error handling.Features:Built out the testing suite to be run before releaseBuilt out the logging mechanism for debuggingIntroduced many error catches for various issues.Bug Fixes:Added config command to bash autocompleteV 0.2.1; February 2nd 2020Added support for . as current directory pathFixed issue with being unable to import configuration filesFixed issue with docs command when running --apiV 0.2.0; February 2nd 20202Focus was on improving the overall useability of ahd. Note this version breaks backwards compatibility, but includes a migration guide in the docs (to be removed in V0.3.0).Features:Bash Autocomplete implemented (ZSH and fish to come)Ability to export configurationAbility to import configurationAdded a top level "docs" command to easy access documentationAdded cross-platform wildcard support (see docs for usage)Added cross-platform home directory (see docs for details)Bug fixes:Fixed issue where running "register" command without any flags would error out instead of printing help infoFixed issue with relative path trackingDocumentation improvements:Added issue templates for bug reports and feature requestsAdded pull request templatesAdded contribution guideAdded migration informationAdded relevant documentation for all features released in V0.2.0V 0.1.0; January 28th 2020Initial release focused on creating the basic functionality for the ahd command.Features:Ability to register a commandAbility to specify command to runAbility to specify the location(s) to run the command in.Have commands store to a configuration file using configparser