forthebadge forthebadge Gem Version

This gem was last updated on the 16.04.2024 (dd.mm.yyyy notation), at 17:37:27 o'clock.

logo

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 /AUTOGENERATED/.

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 cmder, then you can use this option:

--no-quotes

This may also be useful if you have to use a shell such as cmder 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 directory, 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 Rcfiles.new(:cd_aliases).

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 cmder 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 shorter - 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 May 2022 the old class called Rcfiles::ExpandCdAliases was renamed into Rcfiles::DirectoryAliases. 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 May 2022 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 input string such as 'pwdj' can be turned into the corresponding aliased string, which would be '/Depot/j/' 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 Roebe::Shell 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 rcfiles 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 /usr/lib/ruby/site_ruby/3.1.0/rcfiles/yaml/cd_aliases.yml.

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 load_the_dataset_from_the_file_cd_aliases(). This is automatically called whenever Rcfiles::DirectoryAliases.new is called. Have a look at the file at rcfiles/test/testing_using_another_path_to_directory_aliases.rb to see how you can load your own .yml file specifically.

Licence

Since as of April 2021, 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 all feedback as an opportunity to improve my projects nonetheless.

In 2022 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.