ftp_paradise 1.3.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 500f307720442be0d408bc34e4035ecd316a8e650c1662b82d7ac1ffaec3ad88
+  data.tar.gz: faf604c3f0d8d80a580203078cca63c39d9bc87c8eead888e425889643e25215
+SHA512:
+  metadata.gz: 54588cac933f4322db0f1df4a6c0a336359266fec96edb35365c0d91cd6716f219bfb90addc6a96218a988ed80d1b48b48893308372866bfe86a75a9827c621c
+  data.tar.gz: 8050acc810f17e39d34eb26481be6c2991506b00b0b6b7c150e1ed1d8bbbd0349d54e85c1f3c6245449f82ab7aba923da7971cb2902aebc5607ddaa02c421f80

data/README.md

@@ -0,0 +1,309 @@
+[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](http://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/ftp_paradise.svg)](https://badge.fury.io/rb/ftp_paradise)
+
+## 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.
+
+
+## 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:
+
+    shevegen@gmail.com
+
+(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. I will,
+however had, read feedback. 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.)
+
+Thank you.

data/bin/create_remote_directory

@@ -0,0 +1,9 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'ftp_paradise/toplevel_methods/ftp_object.rb'
+
+ARGV.each {|entry|
+  FtpParadise.remote_create_directory(entry)
+}

data/bin/ftp_get

@@ -0,0 +1,17 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'ftp_paradise'
+
+_ = FtpParadise::Connection.new(:dont_run_yet) { :use_default_dataset }
+_.be_verbose
+_.do_login
+_.do_use_colours
+_.remote_cd 'www'
+
+ARGV.each {|obtain_this_file|
+  _.download(
+    obtain_this_file
+  )
+}

data/bin/ftp_upload

@@ -0,0 +1,42 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# Usage example for a binary upload:
+#
+#   ftp_upload file --binary
+# 
+# =========================================================================== #
+require 'ftp_paradise'
+
+if ARGV.empty?
+  puts 'Please supply at least one argument.'
+  exit
+end
+
+_ = FtpParadise::Connection.new(:dont_run_yet)
+_.be_verbose
+
+# =========================================================================== #
+# Next, check commandline arguments given:
+# =========================================================================== #
+ARGV.each {|entry|
+  case entry.to_s.delete('-')
+  when '--start-gui',
+       '--gui',
+       'gui',
+       'startgui' # fupload --gui
+    FtpParadise.do_start_gui
+    exit
+  when /-?-?help/
+    e '  --binary # use binary method'
+    exit
+  when 'binary','BINARY','BIN','bin','--binary'
+    _.set_mode :binary, :be_verbose
+  end
+}
+_.set_data('SHEVY')
+_.do_login('SHEVY')
+ARGV.each {|file|
+  _.upload(file, :be_silent) if File.exist? file
+}

data/bin/ftp_upload_binary

@@ -0,0 +1,18 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This code can be used to upload a binary file.
+# =========================================================================== #
+require 'ftp_paradise/toplevel_methods/upload_this_binary_file.rb'
+
+if ARGV.empty?
+  puts 'Please supply at least one argument to this file.'
+  exit
+end
+
+ARGV.each {|file|
+  if File.exist? file
+    FtpParadise.upload_this_binary_file(file, :be_silent)
+  end
+}

data/bin/iftp

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'ftp_paradise'
+
+FtpParadise.interactive(ARGV)

data/bin/remote_remove

@@ -0,0 +1,28 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This code can be used to remove a remote file from a FTP site.
+# =========================================================================== #
+require 'ftp_paradise'
+
+if ARGV.empty?
+  puts 'Please supply at the least one argument.'
+  exit
+end
+
+_ = ::FtpParadise::Connection.new(:dont_run_yet)
+# =========================================================================== #
+# This is presently hardcoded to my system.
+# =========================================================================== #
+_.set_data('SHEVY')
+_.do_login('SHEVY')
+
+ARGV.each {|file|
+  if file.include? '/' # Handle / given, meaning that we first cd into the base dir there.
+    dirname = File.dirname(file)
+    _.cd_into_this_remote_directory(dirname)
+    file = File.basename(file)
+  end
+  _.delete(file, :be_verbose) # Be verbose rather than silent. 
+}

data/doc/README.gen

@@ -0,0 +1,292 @@
+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.
+
+ADD_CONTACT_DETAILS