#!/usr/bin/python
################################################################################
## \file mailto.py
## \author Jonathan D. Lettvin (Jonathan At at aT lettvin Dot dot doT com)
## \date 20091119
## \brief script to translate "mailto:" urls to agent-driven email composition
##  based on code from
##  "http://www.artima.com/weblogs/viewpost.jsp?thread=4829"
##  "http://www.howtogeek.com/howto/ubuntu/\
##          set-gmail-as-default-mail-client-in-ubuntu/"
##  Please feel free to improve on this script, and send me the improved code.
################################################################################
## Browser URLs of scheme "mailto" can be made to drive a script.
## This script works on ubuntu linux 9.10 (Karmic Koala) using Python 2.6.4.
## An individual user can put this script in their home directory structure.
## It can also be placed in /usr/bin, /usr/local/bin, /usr/share/bin, etc...
## This script is not needed for Mozilla firefox, but is needed for many others.
## Browsers like google Chrome and SeaMonkey can be modified to use this script.
################################################################################
# Here is a sample mailto URL from CraigsList:
#   "mailto:psheerin@endeca.com?\
#    subject=\
#    Software%20Engineers&\
#    body=\
#    %0A%0Ahttp%3A%2F%2Fboston.craigslist.org%2Fgbs%2Fsof%2F1471851937.html%0A"
# Although presented on several lines, consider it to be all one no-space line.
################################################################################
# ENABLE: (illustration for google Chrome)
# In ubuntu linux 9.10 use "System > Preferences > Preferred Applications".
# Suppose your name is geek and installed this script as "/home/geek/mailto.py".
# Use "chmod u+x /home/geek/mailto.py" to make the script executable.
# Within the "Internet" tab choose "Custom" in the "Mail Reader" drop-down list.
# Under this drop-down list is a text field called "Command:".
# Insert the text "/home/geek/mailto.py %s" without quotes and then close.
# Test the script by browsing to a web-page with a mailto URL and try it.
# To make this script hidden replace all "mailto.py" with ".mailto.py".
# Edit this script to engage your preferred agent and composer.
################################################################################
# TODO: Make appropriate branches in code for detected operating system.
################################################################################

################################################################################
# CONFIGURABLE BEGINS:
# It's probably best not to force agents and composers.  Keep them configurable.
# System to system differences between installations is too great to force.
# These values can be modified by the user to choose an email browser agent
# and the mail server basic string for composing emails.
# Here are the originals used when the script was written.
#   agent      = "/usr/bin/google-chrome"
#   composer   = "https://mail.google.com/mail?view=cm&tf=0"
#   swapChrome = [('&','&'),('subject=','su=')]
#   swap       = swapChrome
# Other refinements may be needed to translate things like "subject=" to "su=".
# Each composer may require different swap dictionaries.
################################################################################
version    =		0.1
agent      =		"/usr/bin/google-chrome"
composer   =		"https://mail.google.com/mail?view=cm&tf=0"
swapChrome = [		# Translations necessary for google Chrome
 ('subject=','su='),	# Known text sub needed for google Chrome.
 ('&','&')		# Nice to leave this to last and text subs above it.
]
swap       =		swapChrome
################################################################################
# CONFIGURABLE ENDS:
################################################################################

################################################################################
# Python library resources are needed by this script.
from urlparse import urlparse
from string import split, join, replace
from os import execl
import sys,getopt

################################################################################
"""Module docstring.

mailto.py is to be executed by browsers when the user hits a mailto scheme URL.
Comments in the script aid in configuration and enabling the script.
It takes a single argument: the entire HREF string from the URL.
"""

################################################################################
def usage(err):
  """Handle requests for help and errors."""
  print >>sys.stderr, "Error:  %s" % err
  print >>sys.stderr, "Usage:  %s mailto:{text}" % os.path.basename(sys.argv[0])
  sys.exit(2)

################################################################################
def mailto(oldURL):
  """Reconstruct the URL into usable form and run it through the agent."""
  pathpart = urlparse( fromBrowser )	##< Break down oldURL into components
  pair     = split( pathpart.path, '?' )##< Divide path into page and args
  args     = pair[1]			##< Keep local copy of URL args
  for k, v in swap:			##< Go through dictionary
    args = replace( args, k, v )	##< and swap keys in args as needed.
  newURL  = composer + "&to=" + pair[ 0 ] + "&" + args
  execl( agent, "mailto.py", newURL );	##< Drive newURL into email agent
  sys.exit(0)

################################################################################
def main(argv=None):
  """Variation on Guido van Rossum's handling for run-time environment."""
  if argv is None:
    argv = sys.argv
  try:
      if(len(sys.argv) != 2):
	usage("Must have exactly one arg")
      args = sys.argv[1:]
      if( args[0] == "-v" or args[0] == "--help"):
        usage("version: %s" % version)
      test = split( args[0], ':' )
      if( len( test )!=2 ):
	usage("first arg must have a colon")
      if( test[0]!="mailto" ):
	usage("first arg must be mailto:")
      mailto(args[0])		##< Here is the call to handle mailto links.
  except SystemExit: pass	##< normal exits land here
  except:			##< unhandled exceptions land gently here
    print >>sys.stderr, "Done"
    return 2

################################################################################
if __name__ == "__main__":
  sys.exit(main())
################################################################################
# mailto.py <EOF>
################################################################################