phpdocr 0.1.1

data/NEWS

@@ -0,0 +1,8 @@
+Verison 0.1.1
+- Minor fix to the manpage
+- Better parsing of php.net pages
+- No longer exlicitly requires rubygems, better handling of missing
+	mechanize gem
+
+Version 0.1
+- Initial release

data/README

@@ -0,0 +1,11 @@
+phpdocr is a simple way to access PHP documentation from php.net from the
+command-line.
+
+It will download, prettify, and output PHP documentation for the
+function/class/.. that was supplied on the command-line, much like perldoc(1)
+does for perl(1) and ri does for ruby(1). Unless you explicitly tell it not to,
+phpdocr will also cache the documentation locally for fast retrieval in the
+future.
+
+phpdocr will send its output to your PAGER (if it is set, otherwise it will
+default to less).

data/phpdocr

@@ -0,0 +1,546 @@
+#!/usr/bin/ruby
+# phpdocr
+# Copyright (C) Eskild Hustvedt 2009
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Fetch from rubygems if available
+begin
+	require 'rubygems'
+rescue LoadError
+	puts '(rubygems appears to be missing, will attempt to continue anyway)'
+end
+# Command-line parsing
+require 'getoptlong'
+# To run the prettifier
+require 'open3'
+# To create a temporary file with HTML
+require 'tempfile'
+# CGI is used for escaping
+require 'cgi'
+# www-mechanize is used for fetching from HTTP
+begin
+	require 'mechanize'
+rescue LoadError
+	puts
+	puts 'You appear to be missing the "mechanize" rubygem.'
+	puts 'phpdocr needs this to be able to fetch data from php.net'
+	puts 'Please install the mechanize rubygem using your OS package manager'
+	puts 'or using the "gem" utility.'
+	puts
+	puts 'Package examples:'
+	puts 'Fedora:        yum install rubygem-mechanize'
+	puts 'Debian/Ubuntu: aptitude install libwww-mechanize-ruby'
+	puts 'Generic/all:   gem install mechanize'
+	exit(1)
+end
+# For creating the cache dir if needed
+require 'fileutils'
+# Application version
+$version = '0.1.1'
+# Bool, true if we should include the user notes section
+$includeUserNotes = false
+# Verbose mode (true/false)
+$verbose = false
+# Cache enabled?
+$cache = true
+# php.net mirror
+$mirror = 'php.net'
+
+# Purpose: Print formatted --help output
+# Usage: printHelp('-shortoption', '--longoption', 'description');
+#  Description will be reformatted to fit within a normal terminal
+def printHelp (short,long,description)
+	maxlen = 80
+	optionlen = 20
+	# Check if the short/long are LONGER than optionlen, if so, we need
+	# to do some additional magic to take up only $maxlen.
+	# The +1 here is because we always add a space between them, no matter what
+	if (short.length + long.length + 1) > optionlen
+		optionlen = short.length + long.length + 1;
+	end
+
+	generatedDesc = ''
+	currdesc = ''
+
+	description.split(/ /).each do |part|
+		if(generatedDesc.length > 0)
+			if (currdesc.length + part.length + 1 + 20) > maxlen
+				generatedDesc.concat("\n")
+				currdesc = ''
+			else
+				currdesc.concat(' ')
+				generatedDesc.concat(' ')
+			end
+		end
+		currdesc.concat(part)
+		generatedDesc.concat(part)
+	end
+	if !(generatedDesc.length > 0)
+		raise("Option mismatch")
+	end
+	generatedDesc.split(/\n/).each do |descr|
+		printf("%-4s %-15s %s\n",short,long,descr)
+		short = ''; long = ''
+	end
+end
+
+# Purpose: Print the help output
+def Help ()
+	puts "phpdocr "+$version.to_s
+	puts ""
+	puts "Usage: phpdocr [OPTIONS] [FUNCTION/CLASS/SEARCH STRING/..]"
+	puts ""
+	printHelp('-h','--help','Display this help text')
+	printHelp('-u','--comments','Include the user comments part of the documentation in output')
+	printHelp('-n','--no-cache','Disable the local doc cache (~/.phpdocr/)')
+	printHelp('-v','--verbose','Enable verbose mode')
+	printHelp('-m','--mirror','Use the supplied mirror of php.net')
+	printHelp('','--version','Output the phpdocr version and exit')
+	printHelp('','--man','Show the phpdocr manpage')
+end
+
+# Purpose: Output a string if in verbose mode
+def vputs (str)
+	if $verbose
+		puts(str)
+	end
+end
+
+# Purpose: Show the manpage
+def showManPage ()
+	if ! inPath('man')
+		puts
+		puts "You don't appear to have the 'man' program installed."
+		puts "Please install it, then re-run phpdocr --man"
+		exit(0)
+	end
+	mySelf = File.expand_path($0)
+	while File.symlink?(mySelf)
+		mySelf = File.readlink(mySelf)
+	end
+	sourceDir = '.'
+	if mySelf != nil
+		sourceDir = File.dirname(mySelf)
+	end
+	dirs = [sourceDir]
+	if ENV['MANPATH']
+		dirs.concat(ENV['MANPATH'].split(':'))
+	end
+	dirs.push('./')
+	dirs.each do |dir|
+		[ 'phpdocr.1','man1/phpdocr.1','man1/phpdocr.1.gz','man1/phpdocr.1.bz2','man1/phpdocr.1.lzma'].each do |manFile|
+			if File.exists?(dir+'/'+manFile)
+				exec('man',dir+'/'+manFile)
+			end
+		end
+	end
+	puts
+	puts 'phpdocr failed to locate its manpage.'
+	puts 'Run the following command to view it:'
+	puts '\curl -s "http://github.com/zerodogg/phpdocr/raw/master/phpdocr.1" |  groff -T utf8 -man | \less'
+end
+
+# Purpose: Print debugging info
+def debugInfo ()
+	puts "phpdocr "+$version.to_s
+	begin
+		if inPath('md5sum')
+			outStr = nil
+			out = IO.popen('md5sum '+File.expand_path($0))
+			outStr = out.readline
+			outStr.sub!(/\s+.*$/,'')
+			puts('md5sum: '+outStr)
+		end
+	rescue
+		puts('(exception while generating md5sum: '+$!+')')
+	end
+	prettifierCmd = prettifier('path',false)
+	if prettifierCmd == nil
+		prettifierCmd = '(missing)'
+	else
+		prettifierCmd = String.new(prettifierCmd.join(' '))
+	end
+	puts 'Prettifier: '+prettifierCmd
+	exit(0)
+end
+
+# Fetch a URL and return its contents
+def getURL (url)
+	begin
+		www = WWW::Mechanize.new
+		vputs('Downloading '+url)
+		return www.get(url).body
+	rescue
+		return ''
+	end
+end
+
+# Purpose: Check for a file in path
+def inPath(exec)
+	ENV['PATH'].split(/:/).each do |part|
+		if File.executable?(part+'/'+exec) and not File.directory?(part+'/'+exec)
+			return true
+		end
+	end
+	return false
+end
+
+# Purpose: Detect and run a prettifier
+def prettifier (path, missingIsFatal = true)
+	# Links family, they use basically the same syntax, but we append
+	# -no-references for elinks.
+	if inPath('elinks')
+		return [ 'elinks','-force-html','-no-references','-dump',path ]
+	end
+	['links2', 'links' ].each do |links|
+		if inPath(links)
+			return [ links,'-force-html','-dump',path ]
+		end
+	end
+
+	# w3m
+	if inPath('w3m')
+		return ['w3m','-dump','-T','text/html',path]
+	end
+
+	# html2text
+	if inPath('html2text')
+		return ['html2text','-style','pretty',path ]
+	end
+
+	# Finally, try lynx
+	if inPath('lynx')
+		return ['lynx','-dump','-force_html',path ]
+	end
+
+	if missingIsFatal
+		# If we found none, then give up
+		puts
+		puts "Failed to locate any HTML parser. Please install one of the following,"
+		puts "and then re-run phpdocr: elinks, links2, links, w3m, html2text, lynx"
+		exit(1)
+	else
+		return nil
+	end
+end
+
+# Purpose: Convert links
+def convertLinks (list)
+	result = ''
+
+	rmlastA = false
+	first = true
+
+	list.split(/</).each do |line|
+		if line =~ /^a[^>]+href="\w/
+			currlink = String.new(line)
+			# Remove the href
+			currlink.sub!(/^a[^>]+href="/,'')
+			# Remove whatever is after the href
+			currlink.sub!(/".*$/,'')
+			# Remove '#' links
+			currlink.sub!(/#.*$/,'')
+			# Parse away .php and function declarations
+			currlink.sub!(/\.php$/,'')
+			currlink.sub!(/^function\./,'')
+			# Remove other HTML
+			line.sub!(/^[^>]+>/,'')
+			# Add new content
+			line = String.new('['+currlink+'] '+line)
+			rmlastA = true
+		# Remove the a> if rmlastA is true
+		elsif line =~ /\/a>/ and rmlastA
+			line.sub!(/^\/a>/,'')
+			rmlastA = false
+		elsif first
+			first = false
+		else
+			line = '<'+line
+		end
+		result.concat(line)
+	end
+	return result
+end
+
+# Purpose: Attempt to fetch suggestions
+def fetchSuggestions (data)
+	final =  []
+	hadStart = false
+	no = 0
+	data.split(/\n/).each do |line|
+		if line =~ /result list start/
+			hadStart = true
+		elsif hadStart == false
+			next
+		elsif line =~ /result list end/
+			break
+		else
+			no += 1
+			# Kill all HTML
+			line.gsub!(/<[^>]+>/,'')
+			if line =~ /\S/
+				final.push(line)
+			end
+		end
+	end
+	if hadStart && final != nil
+		return final
+	else
+		return nil
+	end
+end
+
+# Purpose: Display the contents of the supplied string inside the users PAGER
+def pager(contents)
+	# Detect the pager
+	pager = ENV['PAGER']
+	if pager == '' || pager == nil
+		pager = 'less'
+	end
+
+	# Write data to the pager
+	input = IO.popen(pager,'w')
+	begin
+		input.puts(contents)
+		input.close
+	rescue
+	end
+end
+
+# Purpose: Look up something on the website
+def lookupWeb (name, fetchPattern = true, prevSearch = nil)
+	# fetchPattern means we should run a serach
+	stringC = String.new(name)
+	if fetchPattern == true
+		stringC = CGI.escape(name)
+		url = 'http://'+$mirror+'/manual-lookup.php?pattern='+name
+	else
+		# Otherwise, attempt a direct page
+		if ! stringC =~ /\.php$/
+			stringC.concat('.php')
+		end
+		url = 'http://'+$mirror+'/manual/en/'+stringC+'.php'
+	end
+	# Retrieve data
+	data = getURL(url)
+	# True if this is within the normally returned page
+	hadFirst = false
+	# True if we have had the UDM statement
+	hadUDM = false
+	# The result on normal pages
+	result = ''
+	# The result on index-like pages
+	indexResult = ''
+	# Parse it
+	data.split(/\n/).each do |line|
+		if hadFirst
+			if ! $includeUserNotes && line =~ /(User Contributed Notes|<div id="usernotes">)/
+				break
+			end
+			result.concat(line)
+		elsif line =~ /class="refentry"/ || line =~ /<h3\s*class="title">Description/ || line =~ /<div\s*class="refnamediv">/
+			hadFirst = true
+		end
+		if hadUDM
+			if line =~ /<h1 class="title">/
+				indexResult = String.new(line)
+			else
+				indexResult.concat(line)
+			end
+		elsif line =~ /UdmComment/
+			hadUDM = true
+		end
+	end
+
+	# If we got no useful data, try again if possible, else output failure
+	if ! hadFirst && ! hadUDM
+		# If this was a fetchPattern run, try a direct one
+		if fetchPattern
+			return lookupWeb(name,false,data)
+		else
+			# This was a direct one, output errors
+			puts
+			puts 'Could not find '+name+' in PHP documentation'
+			# If we have a previous search value, attempt to fetch suggestions from it
+			if prevSearch != nil
+				suggest = fetchSuggestions(prevSearch)
+				# If we have suggestions, output them.
+				if suggest != nil
+					puts "\n"
+					puts "Perhaps you were looking for one of these?"
+					while suggest.length > 0
+						printf("%-20s %-20s %-20s %-20s\n",suggest[0],suggest[1],suggest[2],suggest[3])
+						4.times { suggest.shift }
+					end
+				end
+			end
+			return
+		end
+	end
+
+	# If we 'hadFirst', then result contains what we want, otherwise use
+	# indexResult
+	if hadFirst
+		result = convertLinks(result)
+	else
+		result = convertLinks(indexResult)
+	end
+
+	# Write the data to a temporary file so the prettifier can
+	# read it there (not all of them support reading from STDIN)
+	tmp = Tempfile.new('phpdocr')
+	tmp.puts('<html><body>'+result+'</body></html>')
+	tmp.flush
+	cmd = prettifier(tmp.path)
+	# Get the output
+	Open3.popen3(*cmd) { |stdin, stdout, stderr|
+		result = stdout.gets(nil)
+	}
+
+	# Close and remove the temporary file
+	tmp.close(true)
+
+	# Append the url we used to the result
+	result.concat("\nRetrieved from "+url)
+
+	return result
+end
+
+# Purpose: Prepare the cache dir
+def prepCacheDir (name)
+	cacheDir = ENV['HOME']+'/.phpdocr/'
+	if ! File.directory?(cacheDir)
+		if File.exists?(cacheDir)
+			puts cacheDir+': exists but is not a directory, caching disabled.'
+			$cache = false
+			return nil
+		end
+		FileUtils.mkpath(cacheDir)
+	end
+	name.gsub!(/\//,'')
+	filePrefix = 'cache.'
+	if $includeUserNotes
+		filePrefix = 'cache.withNotes.'
+	end
+	return cacheDir+filePrefix+name
+end
+
+# Purpose: Look something up in the cache
+def lookupCache (name)
+	cacheFile = prepCacheDir(name)
+	if cacheFile == nil
+		return
+	end
+
+	if File.exists?(cacheFile)
+		file = File.open(cacheFile)
+		vputs('Loaded information for '+name+' from the cache')
+		return file.gets(nil)
+	end
+
+	return nil
+end
+
+# Purpose: Write something to the cache
+def writeToCache (name,data)
+	cacheFile = prepCacheDir(name)
+	if cacheFile == nil
+		return
+	end
+	file = File.open(cacheFile,'w')
+	file.puts(data)
+	file.close
+end
+
+# Purpose: Look something up
+def lookup(name)
+	result = nil
+	sourceWasWeb = false
+	if $cache
+		result = lookupCache(name)
+	end
+	if !$cache || result == nil
+		sourceWasWeb = true
+		result = lookupWeb(name)
+	end
+	if result != nil
+		if $cache && sourceWasWeb
+			writeToCache(name,result)
+		end
+		pager(result)
+	end
+end
+
+opts = GetoptLong.new(
+	[ '--help', '-h', GetoptLong::NO_ARGUMENT ],
+	[ '--verbose', '-v', GetoptLong::NO_ARGUMENT ],
+	[ '--comments','-u', GetoptLong::NO_ARGUMENT ],
+	[ '--no-cache','--nocache','-n', GetoptLong::NO_ARGUMENT ],
+	[ '--debuginfo', GetoptLong::NO_ARGUMENT ],
+	[ '--version', GetoptLong::NO_ARGUMENT ],
+	[ '--mirror', '-m', GetoptLong::REQUIRED_ARGUMENT ],
+	[ '--man', GetoptLong::NO_ARGUMENT ]
+)
+
+# Handle command-line arguments
+begin
+	opts.each do |opt, arg|
+		case opt
+		when '--help'
+			Help()
+			exit(0)
+		when '--verbose'
+			$verbose = true
+		when '--comments'
+			$includeUserNotes = true
+		when '--no-cache'
+			$cache = false
+		when '--debuginfo'
+			debugInfo()
+		when '--version'
+			puts('phpdocr version '+$version.to_s)
+			exit(0)
+		when '--mirror'
+			$mirror = arg
+		when '--man'
+			showManPage()
+			exit(0)
+		end
+	end
+rescue
+	puts('See --help for more inforation')
+	exit(1)
+end
+
+if ARGV.length == 0 || ARGV.length > 1
+	Help()
+	exit(1)
+end
+
+begin
+	lookup(ARGV.shift)
+rescue => ex
+	puts('---')
+	puts('Exception: '+ex.to_s)
+	puts('Backtrace: '+"\n"+ex.backtrace.join("\n"))
+	puts('---')
+	puts()
+	puts('An exception has occurred and phpdocr can not continue.')
+	puts('This almost certainly reflects a bug in phpdocr.')
+	puts('Please check that you have the latest version off phpdocr,')
+	puts('and if you do, report this issue along with the text between the "---" above');
+	puts('to http://random.zerodogg.org/phpdocr/bugs')
+	exit(1)
+end