
                               Plowshare GIT-a87465b (2011-09-26)


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

Plowshare is a command line (CLI) application designed for popular
file-sharing websites (aka Hosters).

Plowshare is a set of four tools (written entirely in shell script):
  - plowdown, for downloading URLs
  - plowup, for uploading files
  - plowdel, for deleting remote files
  - plowlist, for listing remote shared folders

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


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

To run plowshare you will require:

> A POSIX compliant operating system: 
    - GNU/Linux (Debian/Ubuntu/Fedora/Gentoo/Archlinux/...): coreutils, sed
    - Cygwin
    - BSD (requires GNU-sed and GNU-getopt)
    - Mac OSX: need homebrew
> Bash (version >= 3.0)
> Curl (with SSL support, usually required for premium account)

> Character encoding converter (recommended)
    - recode or
    - perl + HTML::Entities

> Some websites requires javascript interpreter [1]
    - spidermonkey or
    - rhino

> Some websites are using captchas. You'll need:
    - imagemagick (with GIF and TIFF support)
    - tesseract-ocr (with TIFF support; version >=2.04)
    - perl + Image::Magick (aka PerlMagick) [2]

> X11 picture viewer (used on site using reCaptcha)
    - display (imagemagick)

> Picture ascii-art viewer (optional)
    - aview or
    - libcaca or
    - tiv

---
[1] Used by 1fichier, badongo, dataport.cz, mediafire and zshare modules
[2] Used by badongo and netload.in modules


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

Plowshare is also available for several Linux distribution (Debian, Fedora, ...):
Consult online documentation for up-to-date list:
http://code.google.com/p/plowshare/wiki/Readme


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

All four 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).

'--help' switch will detail all specific (per modules) options.

Plowdown
--------

1. Download a file from Rapidshare
$ plowdown 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 (you can use curl rates: K=Kbps, M=Mbps, G=Gbps)
$ plowdown -r 50K http://www.rapidshare.com/files/86545320/Tux-Trainer_250108.rar

6. Download a file from Megaupload using a free membership account 
   (note ':' is used to separate user from password)
$ plowdown -a myuser:mypassword http://www.megaupload.com/?d=132348234

7. Download a password-protected file from Megaupload:
$ plowdown -p somepassword http://www.megaupload.com/?d=ieo1g52v

8. Advanced use. Use a different web retriever for the last file download. 
   File URL, file name and cookies are available through interpolations. 
   Assuming you want to use wget:
$ plowdown --run-download='wget -O "%filename" --load-cookies "%cookies" "%url"' \
    http://www.2shared.com/file/4446939/c9fd70d6/Test.html

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

10. Avoid never-ending downloads: limited the number of tries 
    (mainly for captchas) and wait delays for each link
$ plowdown --max-retries=20 --timeout=3600 http://x7.to/x469d5y

Plowup
------

1. Upload a file to dataport.cz (account required)
$ plowup -a myuser:mypassword dataport_cz /tmp/foo.bz2

2. Upload a file to Multiupload changing uploaded file name
$ plowup multiupload /path/myfile.txt:anothername.txt

3. Upload a file to Megaupload with a free membership account:
$ plowup -a myuser:mypassword -d "My description" megaupload /path/myfile.txt

4. Upload a file to Megaupload with a premium account and multifetch upload
$ plowup -a myuser:mypassword -d "My description" megaupload \
    --multifetch http://www.somewherefarbeyond.com/somefile

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

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

7. Modify remote filenames
$ plowup mirrorcreator --name-prefix="2011.jul-" *.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 megaupload (account is required)
$ plowdel -a myuser:mypassword http://www.megaupload.com/?d=132348234

Plowlist
--------

1. List links contained in a shared-folder link and download them all
$ plowlist http://www.mediafire.com/?sharekey=79ac821ea0110 > links.txt
$ plowdown -m links.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 approch 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
