rtfm-filemanager 2.0.2 → 2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dddef7180c16901442304eb4525ece982a16a3d6f96ce39258c4acd44db2783b
-  data.tar.gz: cb7411ed3d9c8abf5654893cc4eb5dcad6e1786ccbb15fbc5f3486a75ba9d154
+  metadata.gz: 1513671bf2225ce310f4da9d6456c24f9268b6adbbb295574f2251358bb1bc7d
+  data.tar.gz: 8018bd4e856182ae60a7957e9381c4109c28423710ed224276633b9763b4d075
 SHA512:
-  metadata.gz: 756f154772d46ebc46e31cca1e9e44af4cf1ef73a5a136a64e891990bedf1ab8c4708fdc08da8283bb088920c182dc6e7fc24de2a2b757eeedc517d02cb51f26
-  data.tar.gz: d8679cde6f8c897d206c0c489349c5e83636c018ba8a0f599df478e699cd2e0c87eeb07a53ed55492ce914cb3a55308e0ab498de4e1e6ff9aa86871aed732175
+  metadata.gz: 84902969b49951e25999896cfb64e7712bb21032b6b5c1d43f239b3a926077faa7e5d7fb02c834587a004d5830b75517451c90ad84a82e230007802777703439
+  data.tar.gz: 23f9324a0382237e030d9e172495ec22329c679d98c16c1f3e6c3943b68bd5b5930072939e8798f72e8862ceba4396447c31b632a22fc47e70fc455c8af9d7d2

data/README.md

@@ -0,0 +1,298 @@
+# RTFM - Ruby Terminal File Manager
+
+## What?
+RTFM is a file manager for the terminal written in Ruby. It lets you browse
+directories and view the content of directories and files. Files are syntax
+highlighted, images are shown in the terminal, videos are thumbnailed, etc.
+You can bookmark and jump around easily, delete, rename, copy, symlink and
+move files. RTFM has a a wide range of other features. Read on for what it can
+do.
+
+Note: RTFM works best with the (u)rxvt, xterm and Eterm terminal emulators.
+
+## Why?
+RTFM parses your LS_COLORS to ensure color consistency with the terminal experience.
+
+The idea came to mind as I was working on [a complete
+LS_COLORS setup](https://github.com/isene/LS_COLORS) with a corresponding
+ranger theme. But making a separate theme for ranger to mimic a massive
+LS_COLOR setup is rather stupid. File managers should parse LS_COLORS as
+default rather than implement their own themes. This became an itch that
+I kept scratching until I could happily replace ranger two weeks later.
+
+
+## How?
+RTFM is a two-pane file manager. You navigate in the left pane and the content
+of the selected item (directory or file) is shown in the right pane. The right
+pane is also used to show information such as the currently tagged items, your
+(book)marks, output from commands, etc. 
+
+You can run any command in the bottom "command line" and have the output
+presented in the right pane. Use LEFT and RIGHT keys to go back and forth on
+the command line, HOME to beginning of line, END to end of line, Backspace or
+Ctrl-h to delete previous character, Ctrl-w to delete previous word, TAB to
+complete directories and file names and ENTER to issue the command, while
+Ctrl-u deletes the line. Issuing ENTER on a blank line has no effect.
+
+## Installation
+
+You can install RTFM by simply coloning this repo and put the file `rtfm` in
+your "bin" directory. Or you can simply run `gem install rtfm-filemanager`.
+
+There are two basic prerequisites needed: `x11-utils` and `xdotool`. On
+Ubuntu these would be installed via `apt install x11-utils xdotool`.
+
+In order to run RTFM (without generating [a bunch of
+warnings](https://github.com/isene/RTFM/issues/1)), you need to do a `gem
+install curses` (gets version 1.3.2) instead of installing via `apt install
+ruby-curses` (gets version 1.2.4-1build1 on Ubuntu 20.04). 
+
+Content of text files are handled by `cat` - or by `bat` if you want beautiful
+highlighting. Other files are shown via external programs. It is shown if you
+have the program installed (Debian/Ubuntu family of Linux distros command in
+last column):
+
+File type                   | Requirements                     | Installation
+----------------------------|----------------------------------|-------------------------------
+Syntax highlighting of text | `bat`                            | `apt install bat`
+PDFs                        | `pdftotext`                      | `apt install poppler-utils`
+LibreOffice                 | `odt2txt`                        | `apt install odt2txt`
+MS docx                     | `docx2txt`                       | `apt install docx2txt`
+MS pptx                     | `unzip`                          | `apt install unzip`
+MS xlsx                     | `ssconvert`                      | `apt install gnumeric`
+MS doc/xls/ppt              | `catdoc`, `xls2csv` and `catppt` | `apt install catdoc`
+Images                      | `w3m` and `ImageMagick`          | `apt install w3m imagemagick`
+Video (thumbnails)          | `ffmpegthumbnailer`              | `apt install ffmpegthumbnailer`
+
+Install rtfm from scratch with all of the above on Ubuntu:
+```
+sudo apt update
+sudo apt install ruby-full git libncurses-dev x11-utils xdotool bat poppler-utils odt2txt docx2txt catdoc w3m imagemagick ffmpegthumbnailer
+sudo gem install curses
+git clone https://github.com/isene/RTFM
+cd RTFM
+sudo cp rtfm /usr/bin/
+cp .rtfm.launch ~/
+echo "source ~/.rtfm.launch" >> .zshrc # or .bashrc if you run bash as shell
+```
+
+## Screenshot
+
+![](img/screenshot.png)
+
+## Image preview in the terminal
+
+RTFM uses w3mimgdisplay (part of the w3m package) to show images in the
+terminal. Some terminals have an issue with this - either the images don't
+show, the previous image is not cleared (new image overlaps the previous) or
+they show for only a flash or a few seconds. The table below shows how the
+most popular terminals fare with this. An "O" indicates that the terminal is
+OK, while an "X" indicates that it fails:
+
+Terminal      |Images | No overlap | Images stay
+--------------|-------|------------|-----------
+(u)rxvt       |   O   |    O       |   O
+xterm         |   O   |    O       |   O
+Eterm         |   O   |    O       |   O
+kitty         |   O   |    O       |   O
+alacritty     |   O   |    O       |   X
+terminology   |   O   |    O       |   X
+stterm        |   O   |    O       |   X
+gnome-terminal|   O   |    X       |
+xfce4-terminal|   O   |    X       |
+mate-terminal |   O   |    X       |
+lilyterm      |   O   |    X       |
+termit        |   X   |            |
+lxterminal    |   X   |            |
+qterminal     |   X   |            |
+
+
+## Keys
+
+These are the set of keys to move around and do actions within RTFM:
+
+### Basic keys 
+
+Key    | Description
+-------|------------------------------------------------------------------
+?      | Show this help text
+r      | Refresh RTFM (recreates all windows. Use on terminal resize or when there is garbage somewhere)
+R      | Reload configuration (~/.rtfm.conf)
+W      | Write parameters to ~/.rtfm.conf (@lsall, @lslong, @lsorder, @lsinvert, @border, @width, @preview, @tagged, @marks)
+q      | Quit
+Q      | QUIT (without writing changes to the config file)
+
+### Motion
+
+Key        | Description
+-----------|------------------------------------------------------------------
+DOWN or j  | Go one item down in left pane (rounds to top)
+UP or k    | Go one item up in left pane (rounds to bottom)
+LEFT or h  | Go up one directory level
+RIGHT or l | Enter directory or open file (using xdg-open or run-mailcap). Use the key 'x' to force open using xdg-open (or run-mailcap). Use 'x' for opening html files in a browser rather than editing the file in your text editor.
+PgDown     | Go one page down in left pane
+PgUp       | Go one page up in left pane
+END        | Go to last item in left pane
+HOME       | Go to first item in left pane
+
+### Jumping and marks
+
+Key    | Description
+-------|------------------------------------------------------------------
+m      | Mark current dir (persistent). Next letter is the name of the mark [a-zA-Z'] The special mark "'" jumps to the last directory (makes toggling dirs easy) Press '-' and a letter to delete that mark
+M      | Show marked items in right pane
+'      | Jump to mark (next letter is the name of the mark [a-zA-Z']). The 5 latest directories visited are stored in marks 1-5 (1 being the very latest)
+/      | Enter search string in bottom window to highlight matching items and jump to the first match
+\\	   | Remove search pattern
+n      | Jump to the next item matched by '/'
+N      | Jump to the previous item matched by '/'
+~      | Jump to Home directory
+f      | Follow symlink to the directory where the target resides
+L      | Start 'locate' search for files, then use '#' to jump to desired line/directory
+
+### Tagging
+
+Key    | Description
+-------|------------------------------------------------------------------
+t      | Tag item (toggles)
+Ctrl-t | Add items matching a pattern to list of tagged items (Ctrl-t and then . will tag all items)
+T      | Show currently tagged items in right pane
+u      | Untag all tagged items
+
+### Manipulate items
+
+Key    | Description
+-------|------------------------------------------------------------------
+p      | Put (copy) tagged items here
+P      | PUT (move) tagged items here
+s      | Create symlink to tagged items here
+d      | Delete selected item and tagged items. Press 'y' to confirm
+c      | Change/rename selected (adds command to bottom window)
+
+### Directory views
+
+Key    | Description
+-------|------------------------------------------------------------------
+a      | Show all (also hidden) items
+A      | Show All info per item (show item attributes)
+o      | Change the order/sorting of directories (circular toggle)
+i      | Invert/reverse the sorting
+O      | Show the Ordering in the bottom window (the full ls command)
+G      | Show git status for current directory
+H      | Do a cryptographic hash of the current directory with subdirs. If a previous hash was made, compare and report if there has been any change
+S      | Show comprehensive system info (system, CPU, filesystem, latest dmesg messages)
+I      | Show OpenAI's description of the selected item and its content (if available). You must have installed the ruby-openai gem and added your openai secret key in the .rtfm.conf (add `@ai = "your-secret-openai-key") for this to work. If RTFM is installed as a gem, the ruby-openai gem is included in the installation
+
+### Right pane
+
+Key    | Description
+-------|------------------------------------------------------------------
+ENTER  | Refresh the right pane
+TAB    | Next page of the preview (if doc long and ∇ in the bottom right)
+S-TAB  | Previous page (if you have moved down the document first - ∆ in the top right)
+w      | Change the width of the left/right panes (left pane ⇒ ⅓ ⇒ ¼ ⇒ ⅕ ⇒ ⅙ ⇒ ½ ⇒ ⅓)
+\-      | Toggle preview in right pane (turn it off for faster traversing of directories)
+_      | Toggle preview of images in right pane
+
+### Additinal commands
+
+Key    | Description
+-------|------------------------------------------------------------------
+F      | Show only files in the left pane matching extension(s) (e.g. "txt" or "pdf,png,jpg")
+g      | Run 'grep' to show files that contains the MATCH in current directory
+:      | Enter "command mode" in bottom window (press ENTER to execute, press Ctrl-G to escape)
+;      | Show command history in right pane
+y      | Copy path of selected item to primary selection (for pasting with middle mouse button)
+Y      | Copy path of selected item to clipboard
+
+
+## A convenient shell function
+Add this line to your `.bashrc` or `.zshrc` to make RTFM exit to the current
+directory by launching the file manager via `r` in the terminal:
+
+`source ~/.rtfm.launch`
+
+... and place the file `.rtfm.launch` in your home directory.
+
+With this, you can jump around in your directory structure via RTFM, exit to
+the desired directory, do work in the terminal and go back into RTFM via `r`.
+
+
+## Configuration file
+When you first exit RTFM, it will write your (book)marks and the set of tagged
+files to `.rtfm.conf`. This ensures your marks and tagged files are
+persistent. It also means you can launch rtfm tag a bunch of dirs and files,
+drop out back to the terminal to do some work, back into rtfm and resume to
+work with your previously tagged items.
+
+You can also set persistent variables in the config file manually. At the top
+of `.rtfm.conf` you can set the following:
+
+To have long info per item: `@lslong = true` (this is otherwise set to `false`)
+
+To show hidden files: `@lsall = "-a"` (this is otherwise set to `""`)
+
+To set any additional 'ls' switches, set the variable `@lsuser`. To not list
+any files containg the word "test", you could do this:
+```
+@lsuser = "--ignore=test"
+```
+
+To change the default width of the left pane to something other than ⅓rd of
+the terminal width: `@width = 5` (would set the left pane width to ⅕th).
+
+To add borders in RTFM: `@border = true`
+
+To have some commands already prepared for the command history, you can set:
+```
+@history = ["cat /home/me/MyTodo.txt", "neofetch --stdout"]
+```
+To open files with `run-mailcap` instead of `open-xdg` set:
+```
+@runmailcap = true
+```
+
+These variables that you manually add to the top of the config files are
+undisturbed by launching and exiting RTFM.
+
+You can also use `W` inside of RTFM to write all the parameters mentioned
+above to the config file - instead of adding them manually.
+
+To exit RTFM without writing any changes to you marks or list of tagged items,
+exit with `Q`. They will then remain the same as when you launched RTFM for
+that session.
+
+
+## Extra info
+The top line shows information about the currently item in the left pane. When
+you are at a file, the information is pretty self explanatory:
+
+`Path: /home/geir/RTFM/README.md (-rw-rw-r-- 6,0K)`
+
+This shows the full path of the selected file as well as the permissions and
+the size of the file. When you are at a directory in the left pane, you get
+two numbers in brackets. The first number is the number of regular dirs/files
+in that directory. The second shows the total number of entries, including the
+hidden directories and files:
+
+`Path: /home/geir/RTFM (drwxrwxr-x 4,0K) [4 8]`
+
+Different file types may have extra self explanatory information included in
+square brackets at the end of the top info line. Image files will have the
+size of the image included while pdf files will have the number of pages. More
+file specific information will be included when I feel like adding such.
+
+## Screencast
+[![RTFM screencast](/img/screenshot-logo.png)](https://youtu.be/ANUOlDryUng)
+
+
+## Development
+I don't expect this program to be used by others. I do this for my own
+enjoyment and because I want a file manager that fits my needs better than any
+others I have found. If you come up with a feature request I feel is cool, I
+may include it. Bug reports are always welcome.
+
+A note to developers: You can hit the "@" key to enter the Ruby debug mode
+where anything you enter in the bottom command window will be sent to the Ruby
+eval() function and output to the right pane. You can for instance issue
+`puts @searched` to see the currently active search pattern. 

data/bin/rtfm

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # encoding: utf-8
-
+#
 # SCRIPT INFO 
 # Name:       RTFM - Ruby Terminal File Manager
 # Language:   Pure Ruby, best viewed in VIM
@@ -91,6 +91,7 @@ RIGHT PANE
  _       = Toggle preview of images in right pane
 
 ADDITINAL COMMANDS
+ F       = Show only files in the left pane matching extension(s) (e.g. "txt" or "pdf,png,jpg")
  g       = Run 'grep' to show files that contains the MATCH in current directory
  :       = Enter "command mode" in bottom window (press ENTER to execute, press Ctrl-G to escape)
  ;       = Show command history in right pane
@@ -99,7 +100,6 @@ ADDITINAL COMMANDS
 
 COPYRIGHT: Geir Isene, 2020-3. No rights reserved. See http://isene.com for more.
 HELPTEXT
-
 @firstrun = <<FIRSTRUN
 
 Welcome to RTFM - the Ruby Terminal File Manager. This help text is shown on the first run.
@@ -118,7 +118,6 @@ Viewing Images uses "w3m and ImageMagick":                apt install w3m imagem
 Viewing Video thumbnails uses "ffmpegthumbnailer"         apt install ffmpegthumbnailer
 
 FIRSTRUN
-
 unless File.exist?(Dir.home+'/.rtfm.conf')
   puts @firstrun
   puts "... hit ENTER to show the RTFM help text."
@@ -127,7 +126,6 @@ unless File.exist?(Dir.home+'/.rtfm.conf')
   puts "\n... hit ENTER to start RTFM. Enjoy :-)"
   STDIN.gets
 end
-
 begin # BASIC SETUP
   require 'fileutils'
   require 'io/console'
@@ -181,6 +179,7 @@ begin # BASIC SETUP
   ## These should not be set by user in .rtfm.conf
   @directory  = {}    # Initialize the directory hash for remembering directories visited
   @searched   = ""    # Initialize the active searched for items
+  @lsfiles    = ""    # File types to show (initially set to all file types"
   @index      = 0     # Set chosen item to first on startup
   @marks["'"] = Dir.pwd
   ## File type recognizers
@@ -683,6 +682,11 @@ def main_getkey # GET KEY FROM USER
     getch
     @break = true
   # ADDITIONAL COMMANDS
+  when 'F' # Filter out filetypes not matching @lsfiles
+    loop do
+      @lsfiles = w_b_getstr("Filetype(s) to show: ", @lsfiles)
+      break if @lsfiles.match(/^$|\w+(,\w+)*$/)
+    end
   when '/' # Get search string to mark items that match the input 
     @w_b.nohistory = true
     @searched = w_b_getstr("/ ", "")
@@ -1000,7 +1004,7 @@ def w_r_show # SHOW CONTENTS IN THE RIGHT WINDOW
     elsif File.directory?(@selected)
       ls_cmd  = "ls #{@selected_safe} #{@lsbase} #{@lsall} #{@lsorder} #{@lsinvert} #{@lsuser}"
       @files  = `#{ls_cmd} 2>/dev/null`.split("\n")
-      ls_cmd += %q[ -lhgGH --time-style="long-iso" | awk '{printf "%s%12s%6s%6s%5s", $1,$4,$5,$3,$2 "\n"}']
+      ls_cmd += %q[ -lhgGH --time-style="long-iso" 2>/dev/null | awk '{printf "%s%12s%6s%6s%5s", $1,$4,$5,$3,$2 "\n"}']
       @fspes  = `#{ls_cmd} 2>/dev/null`.split("\n").drop(1)
       list_dir(false)
     # TEXT 
@@ -1076,7 +1080,7 @@ end
 def w_r_info(info) # SHOW INFO IN THE RIGHT WINDOW
   image_show("clear") if @image; @image = false
   @w_r.clr
-  @w_r. refresh
+  @w_r.refresh
   w_r_width = Curses.cols - (Curses.cols/@width) - 2
   info.gsub!(/(.{1,#{w_r_width}})( +|$\n?)|(.{1,#{w_r_width}})/, "\\1\\3\n")
   @w_r.text      = info
@@ -1205,7 +1209,11 @@ def openai # INTERFACE TO OPENAI
   p += "Give a brief summary of its content: " + c unless File.directory?(@selected) and c == ""
 
   response = client.completions( parameters: { model: "text-davinci-003", prompt: p, max_tokens: 200 })
-  text = "OpenAI description:\n" + response["choices"][0]["text"]
+  begin
+    text = "OpenAI description:\n" + response["choices"][0]["text"]
+  rescue
+    text = "No OpenAI response"
+  end
 
   @w_r.fg = 229
   w_r_info(text)
@@ -1214,7 +1222,11 @@ end
 # BOTTOM WINDOW FUNCTIONS 
 def w_b_info(info) # SHOW INFO IN @W_B
   @w_b.clr
-  info      = ": for command (use @s for selected item, @t for tagged items)" if info == nil
+  if info == nil
+    info      = ": for command (use @s for selected item, @t for tagged items) - press ? for help" 
+    info      = "Showing only file type #{@lsfiles}" if @lsfiles != ""
+    info      = "Showing only file types #{@lsfiles}" if @lsfiles =~ /,/
+  end
   info      = info[1..(@w_b.maxx - 3)] + "…" if info.length + 3 > @w_b.maxx 
   info     += " " * (@w_b.maxx - info.length) if info.length < @w_b.maxx
   @w_b.text = info
@@ -1404,7 +1416,6 @@ loop do # OUTER LOOP - CATCHING REFRESHES VIA 'r'
     @w_p.refresh
     @w_t.fg, @w_t.bg = 232, 249
     @w_t.attr        = Curses::A_BOLD
-    @w_b.fg, @w_b.bg = 250, 238
     @w_b.update = true
     @w_r.update = true
     @w_r.pager  = 0
@@ -1418,16 +1429,25 @@ loop do # OUTER LOOP - CATCHING REFRESHES VIA 'r'
     @change     = true
     @change_tag = true # For future need to force @change
     loop do # INNER, CORE LOOP 
+      @w_b.fg, @w_b.bg = 250, 238
+      @w_b.fg, @w_b.bg = 250, 88  if @lsfiles != ""
       @w_r.text = ""
       begin # Jump to home dir if current dir is externally removed
         Dir.pwd
       rescue
         Dir.chdir
       end
-      ls_cmd  = "ls #{@lsbase} #{@lsall} #{@lsorder} #{@lsinvert} #{@lsuser}" # Get files in current directory 
+      lsf     = @lsfiles.split(",").map! {|e| "*." + e.strip }
+      lsf     = lsf.join(" ")
+      ls_cmd  = "ls #{@lsbase} #{@lsall} #{@lsorder} #{@lsinvert} #{@lsuser} #{lsf}" # Get files in current directory 
       @files  = `#{ls_cmd} 2>/dev/null`.split("\n")
-      ls_cmd += %q[ -lhgG --time-style="long-iso" | awk '{printf "%s%12s%6s%6s%5s", $1,$4,$5,$3,$2 "\n"}']
+      ls_cmd += %q[ -lhgG --time-style="long-iso" 2>/dev/null | awk '{printf "%s%12s%6s%6s%5s", $1,$4,$5,$3,$2 "\n"}']
       @fspes  = `#{ls_cmd} 2>/dev/null`.split("\n").drop(1)
+      if @lsfiles != ""
+        dirs    = `ls -d */`.split("/\n")
+        @files  = dirs + @files
+        @fspes  = dirs + @fspes
+      end
       if Dir.pwd != dir_old
         if @directory.key?(Dir.pwd)
           @selected = @directory[Dir.pwd]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rtfm-filemanager
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: '2.1'
 platform: ruby
 authors:
 - Geir Isene
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-25 00:00:00.000000000 Z
+date: 2023-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curses
@@ -47,7 +47,7 @@ dependencies:
 description: 'A full featured terminal browser with syntax highlighted files, images
   shown in the terminal, videos thumbnailed, etc. You can bookmark and jump around
   easily, delete, rename, copy, symlink and move files. RTFM has a a wide range of
-  other features. New in 2.0.2: Fixed ruby-openai dependency.'
+  other features. New in 2.1: Added filter-by-extension via the key ''F'''
 email: g@isene.com
 executables:
 - rtfm
@@ -55,6 +55,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rtfm.launch"
+- README.md
 - bin/rtfm
 homepage: https://isene.com/
 licenses: