rcfiles 1.3.55

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbf39bf00945d09e1a142c1388b77551791331d70503bb680dc1895e48aa7031
+  data.tar.gz: cefdaf7349d54f3d0fdd70e7b0d43881e0f037b19f554d199b226603c93cfc11
+SHA512:
+  metadata.gz: 2e0a0284b7945922a21b3fa95aa713e62019a1cece72e947977e85412946d88c9a4a9b8b035a785c16173d4fcbdb911aa9d340de27a150dfef0dd36aa18e8172
+  data.tar.gz: 1cafd72d82bcb47bb0af0dcbf23f5dd80a0dd3cefb83f1a0bebd0fcbb6efc4dc6185544c5193572795d4a4940a11550336e6469f8c4e7e96a2541228b57b4341

data/README.md

@@ -0,0 +1,562 @@
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/rcfiles.svg)](https://badge.fury.io/rb/rcfiles)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">20.04.2024</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">20:17:25</span> o'clock.
+
+![logo](https://i.imgur.com/Mf9u97a.png)
+
+## Goals for the rcfiles project
+
+This project will try to automatically generate valid rc-files for shells
+such as bash or zsh. **rc-files** are resource-files typically used by
+shells, which can be sourced in that shell. The default use case will
+refer to the **bash** shell since that is the shell that I do happen
+to use most of the time.
+
+These **rc-files** are generated from yaml files. These yaml files in turn
+are, mostly, also distributed with this project, but of course you can use
+your own yaml files as well. More on this elsewhere in this document, but
+in principle the rcfiles project could also autogenerate various .rb files
+rather than rc-files, or depend on yaml files alone. This will be considered
+in the long run, but for the time being (written in **April 2019**) this
+is not yet a possibility.
+
+The main idea for this project is, evidently, my own use case, which is
+to primarily make my aliases, custom export settings in shells, and so
+forth, available for other/new computers quickly.
+
+## Requiring the rcfiles project
+
+The project is required via this way:
+
+    require 'rcfiles'
+
+Of course you could use **load** too, but require is more common and,
+in my opinion, better, unless you need the behaviour of **load**
+exactly.
+
+## The main directory
+
+The **main directory**, as far as the project here is concerned,
+is simply the directory into which the various rc-files will be
+autogenerated.
+
+On my **home system**, this is usually the directory called
+<b>/AUTOGENERATED/</b>.
+
+The reason as to why I am using such a short, top-level directory is
+that it is quite convenient for me to navigate to it or source the
+various rc-files generated from that directory, such as in:
+
+    . /AUTOGENERATED/aliases_rc
+
+However had, there is one **obvious drawback** with this approach - you
+need to have write permission into that directory close to the **root**
+of the filesystem, if you wish to auto-generate rc-files into that
+directory. And this is not always possible, such as when you are in
+a **restricted environment** (workspace-computers in a university, for 
+example). Or it may be unwanted by you, anyway.
+
+Thus, it must be possible to specify another directory that is to
+be used here.
+
+If you want to **query the current main directory** in use then you
+can use the following **toplevel API**: 
+
+    Rcfiles.main_directory?
+
+If you want to set towards a **new main directory**, then you can
+use the **set_main_directory()** method:
+
+    Rcfiles.set_main_directory
+
+As argument to this method simply pass the directory that you wish
+to use to that method.
+
+So, for example, say that your name is john, and you want to 
+keep the rc-files in your home directory on a Linux system, so
+you may want to do this:
+
+    Rcfiles.set_main_directory('/home/john/rcfiles/')
+
+Ideally make sure that the directory already exists, and that
+you can write/read in/from that directory. But if this is your
+home directory then you will typically have this access-permission,
+anyway. Same with **/tmp/** on most linux distributions.
+
+You can also use a simpler toplevel API such as:
+
+    Rcfiles.set_path
+
+## Commandline usage of this project:
+
+If you do not want to auto-generate rc-files that have a "" quote, as
+part of its value setting (the part on the right side of an alias),
+such as for use in projects such as <b>cmder</b>, then you can use
+this option:
+
+    --no-quotes
+
+This may also be useful if you have to use a shell such as <b>cmder</b>
+which appears to only support unquoted aliases.
+
+So invoke the executable in bin/ like this:
+
+    rcfile --cmder-target
+    rcfile --cmder
+
+To see where the main .yml files are, do this:
+
+    rcfiles --report
+
+To find out hwo many aliases are part of this project, do:
+
+    rcfiles --n_aliases? # 46337 aliases are available in this project (28.08.2020).
+
+## How to use this project from within ruby-code
+
+You first have to require this project, obviously:
+
+    require 'rcfiles'
+
+Now - in order to batch-generate the various rc-files, you can use
+an API such as the following one:
+
+    Rcfiles.run
+    Rcfiles.new
+
+This defaults to my own aliases. For now this is how it is but in
+future releases, people will be able to use their own custom
+aliases.
+
+If you want to store at the rc-files at a specific location,
+such as a certain <b>directory</b>, then you can use the
+symbol :store_at such as in the following example:
+
+    Rcfiles.new(store_at: Dir.pwd)
+
+The second argument, in this case Dir.pwd, shall denote the
+directory that you wish to use here.
+
+This may be especially useful if you have no access to 
+the base directory at / e. g. when you are in a restricted
+environment (like workstations in a university) or when
+you simply want to use another directory name altogether.
+
+The above API is a bit cumbersome, though, so you can use
+any of the following toplevel APIs instead:
+
+    Rcfiles.set_store_into_this_directory
+    Rcfiles.set_main_directory
+    Rcfiles.set_path
+    Rcfiles.store_at=
+    Rcfiles.store_at=
+    Rcfiles.set_store_here
+    Rcfiles.set_store_into
+
+## Generating individual rc-aliases
+
+There are several ways how to generate individual rc-aliases,
+such as via <b>Rcfiles.new(:cd_aliases)</b>.
+
+But there are other toplevel module-methods as well, such as the
+following variants:
+
+    Rcfiles.generate :cd_aliases
+    Rcfiles.generate :aliases
+    Rcfiles.generate :program_aliases
+
+And numbers as input as well, if one wants to be even shorter:
+
+    Rcfiles.generate 1
+    Rcfiles.generate 2
+    Rcfiles.generate 3
+
+Why so many different ways? I simply just want to auto-generate
+these aliases, no matter the given input. These shortcuts generate my
+bash-specific aliases, but since as of March 2018, I also changed the
+code to generate aliases that work on Windows in the <b>cmder</b>
+shell. **cmder** is a bit different in that it requires aliases without
+quotes (aka no '' or "" may be used there).
+
+## Determining the project's base directory
+
+The toplevel "namespace" contains an instance variable called
+**@project_base_directory**. This variable should point to
+where the .rb files of this project are kept. Additionally
+it will load up the .yml files that reside within the
+**yml/** subdirectory there.
+
+On my Linux home system, this works as-is, but other systems
+may need to be a bit more flexible here, such as windows
+perhaps, or systems where you may have no control over where
+the .rb files may be placed (perhaps in a restricted 
+environment such as university campus).
+
+Thus, you can modify the path to this directory via:
+
+    Rcfiles.set_project_base_directory()
+
+You can also query the current path in use via:
+
+    Rcfiles.project_base_dir?
+    Rcfiles.project_base_directory?
+
+## Using quotes in the generated shell-rc files
+
+The toplevel API **Rcfiles.use_quotes?** is
+used to determine whether quotes will be used or not. Some
+programs, such as **cmder**, need quotes.
+
+You can toggle this behaviour like so:
+
+    Rcfiles.use_quotes = true
+    Rcfiles.use_quotes = false
+
+Or simply:
+
+    Rcfiles.toggle_quotes # <- I prefer the long variant
+    Rcfiles.toggle        # <- But the short variant is also a possibility.
+
+The latter method will flip the state, from true to false
+or from false to true.
+
+## Determining the file location of the different aliases in the project
+
+Sometimes it may be necessary to set the path to yaml files, e. g. in
+particular if you wish to make use of other .yml files that do **not**
+come distributed with this project. That was the major reason why code
+was added here, so that users can adapt the project to their use
+cases.
+
+Have a look at the following API, each one corresponding to the particular
+.yml file (e. g. set_file_aliases() would denote the path to the file
+called **aliases.yml**, whereas set_file_programs_aliases() would modify
+the path to the file called **programs_aliases.yml** and so forth):
+
+    Rcfiles.set_file_aliases()
+    Rcfiles.set_programs_aliases()
+    Rcfiles.set_cd_aliases()
+
+## Rcfiles.report
+
+You can use the toplevel method **Rcfiles.report** to report
+some information about the Rcfiles project, such as from
+which paths it will obtain information.
+
+This functionality was necessary because we can re-define the paths
+that are used to generate rc-files at any time; thus, we needed a
+way to **query** the full path to these different files.
+
+## Rcfiles.infer
+
+The toplevel method **Rcfiles.infer** can be called to
+designate the path to one of the three main .yml files of this
+project. It is thus similar to the three variants documented
+above in this file, such as **Rcfiles.set_file_aliases()**,
+**Rcfiles.set_programs_aliases()** and
+**Rcfiles.set_cd_aliases()**. The difference is that 
+**infer()** is a lot shorter - and a lot simpler, too.
+
+You only have to provide the path to this .yml file at hand.
+
+Generic usage examples:
+
+    Rcfiles.infer 'aliases.yml'
+    Rcfiles.infer 'cd_aliases.yml'
+    Rcfiles.infer 'programs_aliases.yml'
+
+In these cases these files will be automatically used, with
+the path designed here. I recommend to first copy the .yml
+files to e. g. your working home directory, and then call
+the three .infer methods. That should help if for whatever
+reason your ruby installation is unable to find the 
+path - or if you simply wish to use other .yml files, too.
+
+## Colours
+
+By default, **Rcfiles** will make use of **colours**, as defined by
+the 'colours' gem.
+
+However had, this is **optional** and ultimately not really necessary - 
+it is just a convenience feature.
+everyone.
+
+If you would rather **NOT** want to use the **colours gem**, or may
+encounter an error related to colours, you can change this either by
+requiring the rcfiles-project a bit differently, such as through
+either of these two ways (which are the same):
+
+    require 'rcfiles/no_colours'
+    require 'rcfiles/no_colours.rb'
+
+This will automatically disable colours support for the **Rcfiles**
+namespace.
+
+The **first** variant is preferred, in my opinion, since it is
+<b>shorter</b> - but use whatever you prefer, anyway.
+
+You can also use the following code to generate the rc-files
+without making use of colours:
+
+    Rcfiles.run { :disable_colours }
+
+## The directory rcfiles/
+
+Since as of 07.04.2019 this project also includes all auto-generated
+rcfiles, in the subdirectory called **rcfiles/**.
+
+The primary reason as to why these files are distributed with this
+project is so that:
+
+a) they are available as-is when the gem is downloaded
+
+and, even more importantly than that
+
+b) because **psych** sometimes has problems with the main encoding used,
+which means that the rc-files may not be generated on a given 
+computer system as-such. Hence why bundling these files into the
+project directly makes this potential problem a non-issue (excluding
+projects such as cmder, which require aliases to be defined without
+quotes).
+
+If you wish to copy these bundled rc-files via ruby, then you can
+use the following toplevel method:
+
+    Rcfiles.copy_rcfiles_to_the_current_directory
+
+## Copying the rc-files via the commandline
+
+Sometimes it may be useful to quickly copy the rc-files into your
+current working directory, rather than generate them anew.
+
+You can use the following commandline switch in order to achieve
+this, and copy the registered rc-files into the current working
+directory:
+
+    rcfiles --copy-rcfiles
+    rcfiles --copy
+    rcfiles --cp
+
+I needed this functionality so that I could quickly copy the
+rc-files, source them in bash, and continue working from here
+past that point - mostly for convenience.
+
+As stated elsewhere in this document, if you need to use this
+functionality from ruby then you can use **Rcfiles.copy_rcfiles_to_the_current_directory**
+or just **Rcfiles.copy_rcfiles**.
+
+## The PS1 path variable
+
+If you wish to quickly generate a new rc-file with a default
+PS1 (defaulting to my PS that is), the following commandline
+variant can be used:
+
+    rcfiles --ps1
+
+## Generating other rc-files
+
+You can either batch-generate all -rc files, or also cherry-pick
+some of them.
+
+Example:
+
+    rcfiles --programs-aliases
+
+This will generate the **programs_aliases_rc file**.
+
+## Generating a .bat file for the cd-aliases on Windows
+
+Certain windows-related shells, such as the fairly new
+**windows-terminal**, make use of a fairly ... obscure
+syntax for a cd-alias.
+
+For example:
+
+    function pwdhome { set-location "c:\home\x" }
+
+This would assign pwdhome to become a cd-alias to
+/home/x. (Weird syntax.)
+
+If you wish to generate such a .bat file with all
+the cd-aliases available in this project, consider
+using the following commandline variant:
+
+    rcfiles --windows-cd-aliases
+
+Internally the method that is doing this is:
+
+     Rcfiles.create_windows_cd_aliases_bat_file
+
+## Obtaining all aliases, as a Hash
+
+If you need to return all aliases registered in this
+project, as a Hash, then you can use this toplevel
+method:
+
+    Rcfiles.aliases?
+
+In **January 2021** this gem contained 47088 entries (key→value pairs).
+In **April 2021** this gem contained 47661 entries (key→value pairs).
+
+## doskey
+
+**doskey** is an old DOS program (I think; at the least it was
+available on DOS back in the days) that allows you to use aliases
+on windows.
+
+For a better explanation, have a look at the following link:
+
+https://kunalspathak.github.io/2020-11-21-About-doskeys/
+
+The **rcfiles** gem contains tons of aliases. Perhaps you have
+lots of aliases as well and would like to re-use them on
+windows.
+
+You can use the **roebe** gem for that, in particular:
+
+    roebe/classes/doskey_generator.rb
+
+Afterwards you may have to replace the global environment
+variables. You can probably adapt this class/file:
+
+    roebe/classes/replace_global_variables_in_this_file.rb
+
+At any rate, this subsection really just tries to contain
+some helpful **hints** for those who want to make use of
+doskey. You may have to adjust it to your own preference.
+
+## DirectoryAliases respectively Rcfiles::DirectoryAliases
+
+In <b>May 2022</b> the old class called <b>Rcfiles::ExpandCdAliases</b>
+was renamed into <b>Rcfiles::DirectoryAliases</b>. The old functionality
+was retained for the most part, but some parts were changed or even
+removed.
+
+The primary reason for the rewrite was that the old logic of
+ExpandCdAlias was very convoluted and complicated. I wanted to
+extend it in <b>May 2022</b> but got frustrated with the old
+design; some parts of the code base were +10 years old already,
+and not that well designed.
+
+Thus, I decided to rather than maintain the old code, to 
+just create a new class, with a cleaner design from the
+get go.
+
+The basic idea behind class Rcfiles::DirectoryAliases is that 
+an <b>input string</b> such as '<b>pwdj</b>' can be turned into
+the corresponding aliased string, which would be '<b>/Depot/j/</b>'
+instead.
+
+The way how to do so would go like this:
+
+    Rcfiles::DirectoryAliases['pwdj'] # => '/Depot/j/'
+
+This can then be used by a shell, such as <b>Roebe::Shell</b>
+in particular - another project I maintain. The idea here
+is to quickly navigate a local file system without having
+to type the full paths whatsoever.
+
+The class has been written with some flexibility in mind.
+For instance, the main .yml file that it uses can be
+queried via the following method:
+
+    Rcfiles::DirectoryAliases.yaml_file?
+
+On my home system this defaults to:
+
+    /usr/lib/ruby/site_ruby/3.1.0/rcfiles/yaml/cd_aliases.yml
+
+This .yml file, called **cd_aliases.yml**, is also distributed
+by the <b>rcfiles</b> gem. This has been done mostly for
+reasons of convenience - other users can use this .yml file
+if they'd like to, but be aware that this defaults to my 
+home setup, so it may be utterly useless to you. Nonetheless,
+you could maintain your own dataset - all you have to provide
+is a similar .yml file. You can store it somewhere else on
+your own local system.
+
+You can specify the path to such a .yml file via:
+
+    Rcfiles::DirectoryAliases.set_yaml_file_used_by_class_directory_aliases(path_goes_here)
+
+This method is called initially via:
+
+    Rcfiles::DirectoryAliases.set_yaml_file_used_by_class_directory_aliases(:default_yaml_file)
+
+The symbol ::default_yaml_file will refer to the already mentioned
+file called <b>/usr/lib/ruby/site_ruby/3.1.0/rcfiles/yaml/cd_aliases.yml</b>.
+
+Note that this merely specifies the path to the file; it does not
+yet load this file.
+
+To load from this file have a look at the method called
+<b>load_the_dataset_from_the_file_cd_aliases()</b>. This is
+automatically called whenever <b>Rcfiles::DirectoryAliases.new</b>
+is called. Have a look at the file at
+<b>rcfiles/test/testing_using_another_path_to_directory_aliases.rb</b>
+to see how you can load your own .yml file specifically.
+
+## Licence
+
+Since as of <b>April 2021</b>, this project is using the MIT licence.
+It is not a hugely important project, so using a less stringent 
+version was fine by me.
+
+Copyright 2021-2023 Robert A. Heiler
+
+You can read up on the MIT licence here:
+
+https://opensource.org/licenses/MIT
+
+The most important requirement (in my own parlance) is the
+"no-warranty disclaimer", aka legalese to "use at your own
+discretion and risk-analysis, without holding the author
+or anyone else responsible for issues potentially
+originating from using this software".
+
+
+## Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail, for various reasons. In order to limit the
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore when the user becomes the end
+product (such as via data collection by upstream services, including other
+proxy-services). My feeling is that this is a hugely flawed business model
+to begin with, and I no longer wish to support this in any way, even if
+only indirectly so, such as by using services of companies that try to
+promote this flawed model.
+
+In regards to responding to emails: please keep in mind that responding 
+may take some time, depending on the amount of work I may have at that
+moment. So it is not that emails are ignored; it is more that I have not
+(yet) found the time to read and reply. This means there may be a delay
+of days, weeks and in some instances also months. There is, unfortunately,
+not much I can do when I need to prioritise my time investment, but I try
+to consider <b>all</b> feedback as an opportunity to improve my projects
+nonetheless.
+
+In <b>2022</b> rubygems.org decided to make 2FA mandatory for every
+gem owner eventually:
+
+see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+However had, that has been reverted again, so I decided to shorten
+this paragraph. Mandatory 2FA may exclude users who do not have a 
+smartphone device or other means to 'identify'. I do not feel it is
+a fair assumption by others to be made that non-identified people may
+not contribute code, which is why I reject it. Mandatory 2FA would mean
+an end to all my projects on rubygems.org, so let's hope it will never
+happen. (Keep in mind that I refer to mandatory 2FA; I have no qualms
+for people who use 2FA on their own, but this carrot-and-stick strategy
+by those who control the rubygems infrastructure is a very bad one to
+pursue.
+

data/bin/rcfiles

@@ -0,0 +1,12 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'rcfiles'
+
+Rcfiles.parse_commandline(ARGV)
+
+if Rcfiles.is_on_roebe? and (ARGV.first and !ARGV.first.include?('help') )
+  require 'rcfiles/aggregate_all_rcfiles/aggregate_all_rcfiles.rb'
+  Rcfiles::AggregateAllRcfiles.new
+end

data/bin/rcfiles_run_it

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'rcfiles'
+
+Rcfiles.run_it(ARGV)