
                               Plowshare GIT-e27b529 (2012-04-09)


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
    - BSD (requires GNU-sed and GNU-getopt)
    - Mac OSX: need homebrew
    - Cygwin
> Bash (version >= 3.0, version >= 3.0.12 recommended)
> Curl (with SSL support, usually required for premium account)
> Character encoding converter (recommended)
    - recode or
    - perl + HTML::Entities

> Some websites are using reCaptcha. You'll need a (X11 or ascii) picture viewer 
  for manual console entry or an account to an automatic solving service:
    - display (imagemagick) or
    - aview (libaa) or
    - img2txt (libcaca) or
    - tiv (perl script using Image::Magick) or
    - CapthaTrader account or
    - Antigate.com account

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

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


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


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


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 --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. Advanced use. Use a different download manager for the final link download.
   File URL, file name and cookie file are available through interpolations. 
$ plowdown --exec 'wget -O "%f" %d' http://www.mediafire.com/?k10t0egmhi23f
$ plowdown --exec 'wget --load-cookies %c -O "%f" %d' http://www.zshare.net/download/991482815663bbe3/
  For premium users, use 2 connections:
$ plowdown -a user:password --exec 'aria2c -x2 %d' http://depositfiles.com/files/fv2u9xqya
$ plowdown -a user:password --printf "Module  : %m" --exec 'aria2c -x2 %d' http://depositfiles.com/files/fv2u9xqya

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://depositfiles.com/files/fv2u9xqya

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 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. 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 Zshare ("delete" link required)
$ plowdel http://www.zshare.net/delete/1234567890ABCD/

2. Delete files (deletes are successive, not parallel)
$ plowdel http://www.zshare.net/delete/1234567890ABCD/ 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


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

# vim: set fileencoding utf-8
