forthebadge forthebadge Gem Version ADD_LAST_UPDATED_WHEN

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.

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 Robert A. Heiler

You can read the MIT licence here:

https://opensource.org/licenses/MIT

Contact information

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 part this is because the UI annoys me (on non-chrome browser loading takes too long), but also because of Google's attempt to establish mass surveillance via its federated cohorts sniffing (FLoC). I do not know what happened at Google, but enough is enough - there is only so much you can take while supporting greed. When it comes to data mining done by private groups, ultimately the user became the product.

Do keep in mind that responding to emails may take some time, depending on the amount of work I may have at that moment, due to reallife time constraints. I will, however had, read feedback eventually. Patches and code changes are welcome too, of course, as long as they are in the spirit of the project at hand, e. g. fitting to the general theme. For this I may make use of github as a discussion site, but this has a low priority right now.