From 25905594a2ee13f76e77b5412f65ff32bb35649e Mon Sep 17 00:00:00 2001 From: Riyyi Date: Mon, 31 Jan 2022 11:17:45 +0100 Subject: [PATCH] Meta: Add build instructions and basic usage to README.org --- README.org | 134 +++++++++++++++-------------------------------------- 1 file changed, 37 insertions(+), 97 deletions(-) diff --git a/README.org b/README.org index 88ea07e..cdf20b4 100644 --- a/README.org +++ b/README.org @@ -1,116 +1,56 @@ -* Stowage +#+TITLE: Manafiles +#+AUTHOR: Riyyi +#+LANGUAGE: en +#+OPTIONS: toc:nil -Needed information for generation: -- short option -- long option -- short description (for usage ouput) -- long description (for manpage output) +Config file and package tracking utility. -* Machine specific configuration +- Manage dotfiles and system config files. +- Selectively command and uncomment depending on machine configuration. +- Store a list of all installed packages. +- Install packages from a stored list. -- Selection based on file name -- Config section selection based on pattern with machine name -- Possibly variable insertion and comment removal +** Build instructions -* Option Parsing - -Parsed from left to right. - -** Types - -- Short option -- Long option -- Argument to option -- Non-option parameter (default argument) - -*** Short Option - -'-' followed by short option character. -If option has required argument, directly after OR separated by white-space. -Optional argument must be directly after the option character. - -Possible to write several short options after one '-', -if all (except last) do not have *required* or *optional* arguments. - -*** Long Option +#+BEGIN_SRC shell-script +$ mkdir build +$ cd build +$ cmake .. +$ make +#+END_SRC -'--' followed by long option name. -If option has a required argument, directly after, separated by '=' OR white-space. -Optional argument must be directly after the option, separated by '='. +** Installation -*** Non-option Parameter +#+BEGIN_SRC shell-script +$ sudo make install +#+END_SRC -Each parameter not starting with '-' and not a required argument of a previous option, -is a non-option parameter. +** Usage -Each parameter after a '--' parameter is always interpreted as a non-option parameter. +*** Selectively comment and uncomment -* Examples +Config files can be pushed from the working directory to the system like so: #+BEGIN_SRC shell-script -./stowage -Fals -./stowage -F -a -l -s - -./stowage --file --add --pull --push - -./stowage -r filename -./stowage -rfilename -./stowage --remove=filename -./stowage --remove filename - -./stowage --remove filename other stuff -./stowage --remove filename -- other stuff +$ manafiles -Fs #+END_SRC -** Multiple of the same options +When pushing files to the system, manafiles recognizes special blocks and comments +or uncomments them depending on the machine's configuration. Such a block looks +like this: #+BEGIN_SRC shell-script -./stowage -e pattern1 -epattern2 --regexp=pattern3 --regexp pattern4 +# >>> distro=arch hostname=arch-desktop user=anon +export PATH="$PATH:$HOME/.local/bin" +# <<< #+END_SRC -* TODO [24/38] - -- [X] macros: add more EXPECT_ -- [X] macros: print to stderr, add colors -- [X] suite: improve printing style -- [X] convert more tests from main() -- [X] suite: add time tracking -- [X] suite: print time info -- [X] suite: add mechanism for EXPECT_ macros to mark current test as failed -- [X] suite: print suite failed tests - -- [X] argparser: after first non option, go into no-option mode. this should be a setting to enable (default off) -- [X] argparser: support '--' to go into non-option mode -- [X] argparser: add multi-option support, vectors! -- [X] argparser: support non-option arguments parsing + storing -- [X] argparser: non-option arguments, what error messages, when? -- [X] argparser: update tests to check non-option arguments -- [X] argparser: add addOption overloads -- [ ] argparser: generate usage string -- [ ] argparser: generate man page string -- [X] argparser: parse() function to return bool false if any error has occurred -- [ ] argparser: setting for failure behavior (usage/exit/usage+exit) -- [X] argparser: add proper tests for non-existent options -- [X] argparser: m_exitOnFirstError is implemented wrong in longOption, should also break in the main loop! - I think its fine in shortOption as it can parse multiple arguments -- [X] argparser: support optional arguments, if acceptvalue fails and arg is optional, increment index and try again -- [X] argparser: receives empty parameters (at least arguments), decide what to do with them. $ uname bla => uname: extra operand ‘bla’ -- [X] argparser: dont use std::regex, just loop through characters and bail if unexpected -- [ ] argparser: support long option abbreviations, if they are not ambiguous -- [ ] argparser: support for single - long options -- [ ] argparser: check and set $value to $next before the if spaghetti to simplify, at least in longOption +This block uses all of the supported configurations, ~distro~, ~hostname~ and + ~user~. These can be used in any combination and order. -- [X] system: add piping functionality, print result of previous command to stdin before execvp() ? -- [ ] system: output/error/status getter, automatically call exec if workload -- [ ] system: output/error getter, cut off last character if its "\n", as std::string already handles trailing \n -- [X] system: test with file descriptors captured in std::system -- [ ] system: write test cases -- [ ] system: fix bug: splitting on space needs to be escapable, ex: '\ ' or ' ' or " ", needs a lexer -- [ ] system: test if exec() can return a reference? +If *all* of the given configurations match, manafiles will make sure that the +contents of the block are uncommented. If *any* of them do *not* match, then +manafiles will make sure that the contents of the block are commented. -- [X] dotfile: add loop index to forEachDotfile -- [ ] dotfile: convert excludePaths and system directories matching to regex -- [ ] dotfile: add excludePaths (ignore file) config file functionality - https://systemcrafters.net/managing-your-dotfiles/using-gnu-stow/ - https://www.gnu.org/software/stow/manual/stow.html#Types-And-Syntax-Of-Ignore-Lists -- [ ] dotfile: add system directories config file functionality +*** COMMENT System config files +*** COMMENT Exclude paths