rcfiles 1.2.46

data/doc/README.gen

@@ -0,0 +1,516 @@
+ADD_RUBY_BADGE
+ADD_LAST_UPDATED_WHEN
+
+![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-2022 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".
+
+ADD_CONTACT_INFORMATION

data/lib/rcfiles/aggregate_all_rcfiles/aggregate_all_rcfiles.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Rcfiles::AggregateAllRcfiles
+#
+# This class will generate a big .sh file.
+#
+# Usage example:
+#
+#   Rcfiles::AggregateAllRcfiles.new(ARGV)
+#
+# =========================================================================== #
+# require 'rcfiles/aggregate_all_rcfiles/aggregate_all_rcfiles.rb'
+# Rcfiles::AggregateAllRcfiles.new
+# =========================================================================== #
+module Rcfiles
+
+class AggregateAllRcfiles # === Rcfiles::AggregateAllRcfiles
+
+  alias e puts
+
+  require 'rcfiles/toplevel_methods/save_file.rb'
+  require 'rcfiles/colours/colours.rb'
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === ARRAY_GATHER_FROM_THESE_FILES
+  # ========================================================================= #
+  ARRAY_GATHER_FROM_THESE_FILES = %w(
+    aliases_rc
+    cd_aliases_rc
+    cflags_rc
+    compile_rc
+    file_information_rc
+    gnome_rc
+    kde_rc
+    kernel_rc
+    lang_rc
+    ldflags_rc
+    ls_colours_rc
+    network_rc
+    path_variable_rc
+    pkgconfig_rc
+    programs_aliases_rc
+    ps1_rc
+    roeberia_settings_rc
+    source_all_the_rc_files.sh
+    system_rc
+    system_settings_rc
+    term_rc
+    video_rc
+  )
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = nil,
+      run_already           = true
+    )
+    reset
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = '')
+    i = [i].flatten.compact
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first? first_argument? # === first?
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    _ = ''.dup
+    base_dir = '/AUTOGENERATED/'
+    ARRAY_GATHER_FROM_THESE_FILES.each {|entry|
+      target = base_dir+entry.to_s
+      if File.exist? target
+        _ << File.read(target)
+        _ << "\n"
+      end
+    }
+    what = _
+    into = base_dir+'aggregated_shell_file.sh'
+    opn(namespace: @namespace); e ::Colours.rev+
+                                  'Now storing into the file `'+
+                                  ::Rcfiles.sfile(into)+'`.'
+    ::Rcfiles.write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === Roebe::AggregateAllRcfiles[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Rcfiles::AggregateAllRcfiles.new(ARGV)
+end # aggregateallrcfiles

data/lib/rcfiles/class/colours.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'rcfiles/class/colours.rb'
+# =========================================================================== #
+require 'rcfiles/colours/colours.rb'
+
+module Rcfiles
+
+class Rcfiles
+
+  # ========================================================================= #
+  # === use_colours?
+  #
+  # We delegate to the toplevel method in order to determine whether
+  # the Rcfiles project will use colours or whether it will not.
+  # ========================================================================= #
+  def use_colours?
+    ::Rcfiles.use_colours?
+  end
+
+  # ========================================================================= #
+  # === sdir
+  # ========================================================================= #
+  def sdir(i)
+    return ::Rcfiles.sdir(i) if use_colours?
+  end
+
+  # ========================================================================= #
+  # === simp
+  # ========================================================================= #
+  def simp(i)
+    return ::Rcfiles.simp(i) if use_colours?
+    i
+  end
+
+  # ========================================================================= #
+  # === sfancy
+  # ========================================================================= #
+  def sfancy(i)
+    return ::Rcfiles.sfancy(i) if use_colours?
+    i
+  end
+
+  # ========================================================================= #
+  # === sfile
+  # ========================================================================= #
+  def sfile(i)
+    return ::Rcfiles.sfile(i) if use_colours?
+    i
+  end
+
+end; end