ftp_paradise 1.4.5

data/doc/README.gen

@@ -0,0 +1,302 @@
+DEFAULT_RUBY_HEADER
+
+## FtpParadise - Introduction
+
+This README file contains FTP-related information about the ruby
+scripts that are part of the **FtpParadise project**.
+
+Currently the most important part of the FTP Paradise project is
+the Library around the Ruby-FTP base library, and an interactive
+component that can check on the given user-input.
+
+A simple **GUI** also exists to support the extended FTP
+functionality, but this GUI is extremely limited - I recommend
+to use the commandline variant instead. (The commandline variant
+is also significantly faster, in my experience.)
+
+Since as of **March 2014** a web-interface of some sorts is
+available too, currently being offered as a sinatra-app and
+a .cgi file. This is also limited, so again: prefer to use
+the commandline variant whenever possible.
+
+The interactive component can be used to connect to remote websites
+by making use of the script called **iftp** at **bin/iftp**. This
+file is distributed with the project.
+
+The name **iftp** indicates towards "interactive_ftp", which
+describes its functionality best - it allows you to interactively
+enter commands, which will then be evaluated in the context of
+FTP. (Evidently you have to first connect to the remote 
+website via your FTP login credentials, so make sure to do
+that first before inputting commands.)
+
+## Requiring the FtpParadise library:
+
+Simply do the following in order to require this project:
+
+    require 'ftp_paradise'
+
+Please do note that rather than the various .set_ methods, you
+could also use traditional = methods instead.
+
+So, for instance:
+
+    set_port()
+  
+is the very same as using a direct setter method such as:
+  
+    port=
+
+This is mostly for convenience. Use in your code whatever you
+prefer. Most may prefer foo=, I like to read a leading set_
+though, visually.
+
+## The interactive component of the FTP Paradise:
+
+The **interactive** component will properly tell the user whether
+he/she is connected to a remote host or whether the user is not
+connected, since as of the version **1.0.35**.
+
+If you need to determine manually whether you are connected, do
+input this command in the interactive shell:
+
+    connected?
+
+## Autoconnecting (Added as of December 2017)
+
+This presently works only on my home system, by checking whether
+the environment variable IS_ROEBE was set. If it was set, and
+if **an upload event** occurs before we have connected
+somewhere, then we will first connect.
+
+This functionality could be changed to include any way to 
+auto-connect, but for now, this has to suffice.
+
+In September 2018, an additional option has been added. The
+file **automatically_connect_on-statup_of_the_interactive_ftp_shell.yml**
+has been created. If its content is set to true, and if we
+are on **roebe**, and we start the interactive ftp-shell, then
+we will automatically connect to the remote shevy-FTP site.
+
+This obviously is only useful on my home system, but it could
+in theory be expanded to include other FTP sites as well.
+
+## Readline support
+
+The interactive component of the FtpParadise project will try
+to make use of the readline module, if it is available. Not
+every ruby version installed may have support for Readline,
+though, so this must be **optional**.
+
+If you do not want to use readline or do not need it, you can
+pass the flag --no-readline to disable this for the current
+invocation.
+
+    iftp --no-readline
+
+(Where **iftp** stands short for interactive ftp.)
+
+## Using FTP Paradise it in a project:
+
+  First, you must require this gem, as stated above:
+
+    require 'ftp_paradise'
+
+  Then you can use Ruby code such as this one here:
+
+    _ = FtpParadise::Connection.new("science_news")
+    _.set_user 'the_name_of_your_user_here' # <-- this is optional
+    _.set_port '21'                         # <-- this is also optional
+    _.connect_to 'insert_the_ftp_host_here'
+    _.run # Start transation (as in, try to login).
+
+  Note that most of the above is completely optional and thus can be
+  omitted.
+
+  It simply allows you to fine tune when you need to set these entries.
+  
+  Convenience methods exist of course, for instance:
+  
+      FtpParadise.connect to: 'url here'
+
+  A much simpler alternative to the above is to provide a Hash with all
+  that required information instead.
+
+  If you don't want to connect the very moment a new Library class is
+  instantiated, then you can do the following:
+  
+      _ = FtpParadise::Connection.new :dont_run
+
+  You can also directly upload a file, by using a class_method such
+  as this one here:
+
+      FtpParadise.upload(this, to)
+
+  Class methods (or rather, module methods in this case), will
+  be stored in the file module.rb.
+
+  A pure commandline-program also exists, called:
+  
+      ftp_upload
+  
+  Check it's --help option for its available options.
+     
+## Uploading content to a remote FTP server
+
+Remember that you can do all of this via the **official ruby FTP 
+bindings** already - I only wanted to be able to do so interactively
+as well.
+
+Uploading from the interactive FTP paradise executable can be done
+by giving numbers. The FTP paradise project will assume that any
+numbers given, will refer to the index position of the current
+working directory.
+
+That is, index 7 would mean file position at 7 in the current
+directory:
+
+    upload 7,8
+
+The above instructions would try to **upload file number 7**
+and **8** to the remote host. Of course you could use the file
+name instead directly - the numbers are just there for
+convenience. Less to type when in an interactive mode.
+
+Also note that this refers only to files. Directories will be
+ignored for this purpose. This behaviour may change in the
+future, but then again it may not. (The default is mostly 
+what is the most convenient and most used behaviour; for me
+it is a LOT more common to just quickly upload files to a
+remote ftp server, so the number support above prefers
+files too.)
+
+To **upload files** do:
+  
+    upload foo.txt
+  
+You can **upload** several files by using , as a delimiter:
+  
+    upload 6,7
+  
+This would upload file 6 and file 7.
+
+If you wish to batch-upload some .pdf files, you can try this:
+  
+    upload *pdf
+
+To simply batch-upload the content of the current working
+directory, this should suffice:
+
+    upload *
+
+
+## General use cases for the interactive FTP component - using the interactive component
+
+The interactive FTP component allows you to do several **ftp-related
+commands** via an interactive interface. I needed this functionality
+so that I can connect to remote FTP servers and quickly do things
+such as creating a directory, removing it, renaming files, uploading
+and downloading content.
+
+Once you are all set and finished working with the Interactive 
+Ftp component of the ftp_paradise project, you can type **q** or
+**quit** to exit from it again - or simply hit Ctrl-D, which achieves
+the same, more or less.
+
+To start the interactive ftp component, you can issue a command
+such as:
+
+    _ = FtpParadise::InteractiveFtp.new
+
+This should start the interactive component of the **FtpParadise project**.
+
+If you want a **simplified API** call, you can also use:
+
+    _ = FtpParadise.interactive
+
+instead. This variant has the benefit of being more succinct.
+
+Once inside the main loop there, the one that will continually
+fetch user input, you can issue "help" to get help.
+
+The same syntax that is used via <b>upload</b>ing content, can
+also be used by **downloading**, such as via:
+
+    download 8
+    download 8,9
+    download 1,2,3
+
+In short, we can use positional numbers to handle files and
+directories. The number 3 means "whatever is at the third
+position", be it a file or a directory.
+
+You can also specifically download a binary file by issuing:
+
+    download_remote_file test.bin
+
+You can show the full path to a file, both remote or local,
+if you wish to.
+
+For this do either of:
+
+   toggle show
+   show_names
+
+If you wish to remove all remote entries from a remote directory,
+do issue this command:
+ 
+    remote_remove *
+
+You can also upload from the commandline, by using the script
+**ftp_upload**:
+
+    ftp_upload file_that_should_exist_comes_here.txt
+    ftp_upload *
+  
+The latter command would simply upload all the found files in
+the current directory.
+
+You can also do the above in **binary mode**:
+  
+    ftp_upload file --binary
+
+## Editor
+
+You can query which editor is in use, in the interactive FTP
+component of the **FtpParadise project**, by issuing this
+command:
+
+    editor?
+
+You can also assign another editor in use, via:
+
+    set_editor vim # Use "vim" as the editor.
+
+This value is used when you wish to quickly **modify a file**
+from within the **interactive_ftp component**. The latter
+is triggered via:
+
+    edit NAME_OF_THE_FILE_HERE
+    edit foobar.md # <- an example
+
+## Remote Hosts
+
+If you need to determine the remote host, you can use this
+toplevel method:
+
+    FtpParadise.remote_host?
+
+This will return nil if no connection has been made as of
+yet.
+
+## The graphical user interface (ruby-gtk3)
+
+There exists a small ruby-gtk3 client for the ftp_paradise
+gem. Unfortunately it is not complete and has a few bugs;
+if anyone wants to fix that ... :)
+
+For selecting a local file, you currently have to 
+double-click. At some later point I will extend this
+to one-click only.
+
+ADD_CONTACT_DETAILS

data/doc/todo/TODO_FOR_FTP_PARADISE_PROJECT.md

@@ -0,0 +1,79 @@
+(1)
+
+- rcd AUSARBEITUNG
+
+  Changing remote directory to `AUSARBEITUNG` now.
+  Trying to change directory into `AUSARBEITUNG/`.
+
+  ^^^ nope, we should check FIRST before we do 
+  that. "This directory does not exist."
+
+(2)
+
+- Build a GUI Wrapper (in ruby-gnome for now) over the FTP stuff.
+  Once it is finished, we can remove this entry here, or perhaps
+  extend to it every once in a while.
+
+(3)
+
+- Also check that tab completion works for remote files and
+  remote dirs.
+
+(4)
+
+- Add readline support so we can use tab completion. Would be
+  cool to use readline-support TAB COMPLETION, especially when
+  handling directories.
+
+  Tab completion must work for:
+
+    file screenshot.png
+    upload scr<PRESS_TAB_HERE>
+
+(6)
+
+- Build a WWW wrapper, in sinatra.
+
+(7)
+
+- shugo added directory? and stuff. we may be able to simplify
+  our already existing methods for that, then upload.
+  
+  -> Please note that the new methods are available only with FTP servers
+     which support the MLST/MLSD commands specified in RFC 3659.
+
+
+pwd
+The local directory is: 
+  /home/x/STUDIUM/BOKU_WIEN/958118_Obst_und_Weinbau/
+remotemkdir 958118
+Creating remote directory `958118/` now.
+rcd 958118
+false
+#<NoMethodError: undefined method `+' for nil:NilClass>
+rcd 958118
+true
+Changing remote directory to `958118` now.
+Trying to change directory into `958118/`.
+Remote directory is:
+  shevegen.square7.ch/AUSARBEITUNGEN/958118/
+  
+  ^^^^ warum gibt uns das einen Fehler aus????
+
+
+
+FtpParadise.remote_host?
+
+^^^ and show it
+
+FtpParadise.user?
+
+
+
+FtpParadise.password?
+
+
+
+
+^^^ ensure that this exists in particular the top one
+and add a commandline bin/ variant to show this too

data/ftp_paradise.gemspec

@@ -0,0 +1,122 @@
+# =========================================================================== #
+# Gemspec for Project FtpParadise.
+# =========================================================================== #
+require 'ftp_paradise/version/version.rb'
+
+Gem::Specification.new { |s|
+
+  s.name    = 'ftp_paradise'
+  s.version = FtpParadise::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+This project aims to provide some convenience bindings and addon-classes
+for the Ruby-FTP base module.
+
+The basic idea for this project was to make working with FTP-related
+code simpler, and more convenient. This is why the project focuses
+both on commandline use, interactive commandline use, as well as
+GUI components (via ruby-gtk3 primarily).
+
+Please be aware that since as of the year 2020, this project is in a
+low-effort maintenance mode only, though.
+
+Bug fixes may still happen, as well as improvements made to the 
+documentation - but by and large, I am no longer modifying this 
+project that much anymore. My peak FTP days in regards to this
+project were mostly from 2010 to 2014. Since then I have found
+fewer use cases for this project.
+
+For more information about the ftp_paradise project, please have a look
+at the online documentation at https://www.rubydoc.info/gems/ftp_paradise/
+or within the doc/ subdirectory of this gem.
+
+EOF
+
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+
+  # =============================================================== #
+  # Show this when a user installs this project.
+  # =============================================================== #
+  s.post_install_message = <<-EOF
+
+  The interactive file, which can be started by typing "iftp",
+  requires a library called configuration.
+
+  This is NOT the one available at rubygems.org - but instead can
+  be downloaded here:
+
+      wget http://shevegen.bplaced.net/configuration-1.0.21.gem
+
+  Please install only the above configuration-gem variant, not the
+  other gem called "configuration". (You can extract the gem and
+  look at it before you install it of course. Its sole purpose
+  is to read in a bunch of .yml yaml files to provide a proper
+  base configuration for a project.)
+
+  If you wish to start the interactive FTP, the file can be
+  found at:
+
+      bin/iftp
+
+  And should on most Linux systems end up on:
+
+      /usr/bin/iftp
+
+  if the --prefix is at /usr (obviously, if you install into
+  your home directory, then it will be at another location;
+  rubygems should take care of this).
+
+  So just typing "iftp" should suffice to start the interactive FTP
+  component, but keep in mind that you need to download the
+  configuration gem listed above first.
+
+  You can disable the colour-section of the interactive FTP
+  by issuing:
+
+      iftp --disable-colours
+
+  You can also batch-upload some scripts through the command
+  called:
+
+      ftp_upload
+
+  ftp_upload --help should give you some information on how
+  to use it.
+
+  Consider installing the "roebe" gem for making "Configuration"
+  available.
+
+  Thank you and have fun!
+
+  EOF
+
+  s.authors     = ['Robert A. Heiler']
+  s.email       = 'shevegen@gmail.com'
+  s.license     = 'GPL-2.0'
+  s.files       = Dir['**/*']
+  s.files       << ['README.md']
+  s.files       = s.files.flatten
+  s.executables = Dir['bin/*'].map { |entry| File.basename(entry) }
+  s.require_paths = ["lib"]
+
+  s.homepage    = 'http://rubygems.org/gems/ftp_paradise'
+
+  s.required_ruby_version     = '>= '+RUBY_VERSION
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  # =============================================================== #
+  # Dependencies for this project:
+  # =============================================================== #
+  s.add_dependency 'cliner'
+  s.add_dependency 'colours'
+  s.add_dependency 'convert_global_env'
+  s.add_dependency 'rcfiles'
+  s.add_dependency 'opn'
+  s.add_dependency 'verbose_truth'
+  s.add_dependency 'gtk_paradise'
+
+}