Plowshare for Bash 4, GIT-snapshot


Introduction
============

Plowshare4 is a set of command-line tools (written entirely in shell script)
designed for managing file-sharing websites (aka Hosters).

Plowshare4 is divided into 5 scripts:
  - plowdown, for downloading URLs
  - plowup, for uploading files
  - plowdel, for deleting remote files
  - plowlist, for listing remote shared folders
  - plowprobe, for retrieving information of downloading URLs

For a complete list of supported websites (named "module"), have a look here:
http://code.google.com/p/plowshare/wiki/Readme


Dependencies
============

To run plowshare4 and all its modules you will need:

> A POSIX compliant operating system:
    - GNU/Linux (Debian/Ubuntu/Fedora/Gentoo/Archlinux/...): coreutils, sed
      (Busybox sed is working too, need version >1.10)
    - BSD/Mac OSX: requires GNU-sed
    - Cygwin
> Bash (version >= 4.1). It will NOT work using Busybox or Dash (POSIX) shell.
> Curl (version >= 7.24, with SSL support: usually required for premium account)
> Character encoding converter (recommended)
    - recode or
    - perl + HTML::Entities

> Some websites are using captchas. You'll need a (X11, FB or ascii) picture viewer
  for manual console entry or an account to an automatic solving service:
    - display (imagemagick, X11) or
    - feh (imlib2, X11) or
    - sxiv (imlib2, X11, very fast) or
    - qiv (imlib2, X11) or
    - fim (frame buffer and ascii art image viewer) or
    - img2txt (libcaca) or
    - tiv (perl script using Image::Magick, color output) or
    - aview (libaa) or
    - 9kw.eu account or
    - Antigate.com account or
    - CaptchaBrotherhood account or
    - DeathByCaptcha account

> Some websites requires javascript interpreter [1]
    - spidermonkey or
    - rhino (JavaScript engine written in Java)

---
[1] Used by turbobit and zalaa


Install
=======
See INSTALL file for details.


Usage examples
==============

All five scripts share the same verbose options:
> '-v0' (alias: '-q'),
> '-v1' (errors only),
> '-v2' (infos message; default),
> '-v3' (show all messages),
> '-v4' (show all messages, HTML pages and cookies, use this for bug report).

Getting help:
> '--help'
> '--longhelp' (plowdown & plowup only, prints modules command-line options)

Plowdown
--------

1. Download a file from Rapidshare
$ plowdown http://www.rapidshare.com/files/86545320/Tux-Trainer_250108.rar
  Like firefox (append .part suffix to filename while file is being downloaded)
$ plowdown --temp-rename http://www.rapidshare.com/files/86545320/Tux-Trainer_250108.rar

2. Download a file from Rapidshare with a proxy (curl supports "http_proxy" and
   "https_proxy" environment variables, notice that 3128 is the default port)
$ export http_proxy=http://xxx.xxx.xxx.xxx:80
$ plowdown http://www.rapidshare.com/files/86545320/Tux-Trainer_250108.rar

3. Download a list of links (one link per line)
$ plowdown file_with_links.txt

4. Download a list of links (one link per line) commenting out (with #) those successfully downloaded
$ plowdown -m file_with_links.txt

5. Limit the download rate (in bytes per second). Accepted prefixes are k, K, Ki, M, m, Mi.
$ plowdown --max-rate 900K http://www.rapidshare.com/files/86545320/Tux-Trainer_250108.rar

6. Download a file from HotFile using an account (free or premium)
   (note ':' is used to separate user from password)
$ plowdown -a 'myuser:mypassword' http://hotfile.com/dl/68261330/2f2926f/

7. Download a password-protected file from Mediafire:
$ plowdown -p 'somepassword' http://www.mediafire.com/?mt0egmhietj60iy

8. Filter alive links in a text file
$ plowdown -c file_with_links.txt > file_with_active_links.txt

9. Avoid never-ending downloads: limit the wait delays & number of retries
   (limitations apply for each link)
$ plowdown --max-retries=4 --timeout=3600 my_big_list_file.txt

Plowup
------

1. Upload a single file anonymously to BayFiles
$ plowup bayfiles /tmp/foo.bar

2. Upload a bunch of files anonymously to 2Shared
$ plowup 2shared /path/myphotos/*
Notice that only files will be sent, subdirectories will be ignored.

3. Upload a file to Mirrorcreator changing uploaded file name
$ plowup mirrorcreator /path/myfile.txt:anothername.txt

4. Upload a file to MegaShares (anonymously) + set description
$ plowup -d "Important document" megashares /path/myfile.tex

5. Upload a file to RapidShare with an account (premium or free)
$ plowup -a 'myuser:mypassword' rapidshare /path/xxx

6. Upload a file to Oron anonymously with a proxy.
$ export http_proxy=http://xxx.xxx.xxx.xxx:80
$ export https_proxy=http://xxx.xxx.xxx.xxx:80
$ plowup oron /path/myfile.txt

7. Abort slow upload (if rate is below limit during 30 seconds)
$ plowup --min-rate 100k mediafire /path/bigfile.zip

8. Modify remote filenames
$ plowup --name-prefix="2011.jul-" mirrorcreator *.rar

Be aware that curl is not capable of uploading files containing a comma (,)
in their name, so make sure to rename them before using plowup.

Plowdel
-------

1. Delete a file from Oron ("delete" link required)
$ plowdel http://oron.com/hymvzwi4mkk7?killcode=cmh5cer4s6

2. Delete files (deletes are successive, not parallel)
$ plowdel http://oron.com/hymvzwi4mkk7?killcode=cmh5cer4s6 \
      http://depositfiles.com/rmv/1643181821669253

3. Delete a file from RapidShare (account is required)
$ plowdel -a myuser:mypassword http://rapidshare.com/files/293672730/foo.rar

Plowlist
--------

1. List links contained in a shared folder link and download them all
$ plowlist http://www.mediafire.com/?qouncpzfe74s9 > links.txt
$ plowdown -m links.txt

2. List two shared folders (first URL is processed, then the second one, this is not parallel)
$ plowlist http://www.mediafire.com/?qouncpzfe74s9 http://www.sendspace.com/folder/5njdw7

3. List some sendspace.com web folder. Render results for vBulletin "BB" syntax.
$ plowlist --printf '[url=%u]%f[/url]' http://www.sendspace.com/folder/5njdw7

4. List links contained in a dummy web page. Render results as HTML list.
$ plowlist --fallback --printf '<li><a href="%u">%u</a></li>' \
      http://en.wikipedia.org/wiki/SI_prefix

Plowprobe
---------

1. Filter alive links in a text file
$ plowprobe file_with_links.txt > file_with_active_links.txt

2. Custom results format : print filename and size (as shell comment)
$ plowprobe --printf "#%f (%s)%n%u" http://www.sendspace.com/file/5njdw7

3. Use '-' argument to read from stdin
$ plowlist http://pastebin.com/1d82F5sd | plowprobe - > filtered_list.txt


Implement your own modules
==========================

Core of plowshare export a set of API to help text and HTML processing.
It is designed to be as simple as possible to develop new modules.
A module must be written in shell with portability in mind; one module matches
one website.

A guide is available here:
http://code.google.com/p/plowshare/wiki/NewModules
API list is here:
http://code.google.com/p/plowshare/wiki/NewModules2

A common approach is also to study existing modules.


Feedback
========

If you find a bug in plowshare or want to propose an enhancement,
open a new ticket here:
http://code.google.com/p/plowshare/issues/list

# vim: set fileencoding utf-8