#!/usr/bin/python

#  Author: Donald Miner <dminer@tresys.com>

#

# Copyright (C) 2003 - 2005 Tresys Technology, LLC

#      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, version 2.

"""

	This script generates XML documentation information for layers specified

	by the user.

"""

import sys

import os

import glob

# GLOBALS

class dec_style:

	'''

	"Declaration Style"

	Specifies the syntax of a declaration. Intended to be used with

	getParams().

	'''

	# Example of a line: foo(bar,one,two);

	# A style that would fit this: dec_style("foo(",3,",",");")

	#  "foo(" - the opening of it, ends at the begining of the first param.

	#  3 - the number of parameters.

	#  "," - the delimeter to parse apart parameters.

	#  ");" - the end of the declaration statement.

	def __init__(self,open_str,params,delim,close_str):

		self.open_str = open_str

		self.params = params

		self.delim = delim

		self.close_str = close_str

INTERFACE = dec_style("interface(`",1,None,"'")

TEMPLATE = dec_style("template(`",1,None,"'")

TUNABLE = dec_style("gen_tunable(",2,",",")")

# boolean FIXME: may have to change in the future.

BOOLEAN = dec_style("gen_bool(",2,",",")")

# Default values of command line arguments.

directory = "./"

warn = False

meta = "metadata"

layers = []

tunable_files = []

# FUNCTIONS

def getXMLComment(line):

	'''

	Returns the XML comment, (removes "## " from the front of the line).

	Returns False if the line is not an XML comment.

	'''

	for i in range(0,len(line)-1):

		# Check if the first 3 characters are "## "

		if line[i:i+3] in ("## ", "##\t"):

			# The chars before '#' in the line must be whitespace.

			if i > 0 and not line[0:i-1].isspace():

				return False

			else:

				return line[i+3:]

	# No XML comment.

	return False	

def getParams(line, style):

	'''

	Returns a list of items, containing the values of each parameter.

	'''

	# Clean out whitespace.

	temp_line = line.strip()

	# Check to see if the string begins with the specified opening

	# string specified by style.

	if temp_line[0:len(style.open_str)] == style.open_str:

		temp_line = temp_line[len(style.open_str):].strip()

	else:

		return False

	# If there is a delimeter.

	if style.delim:

		temp_line = temp_line.split(style.delim)

	else:

		temp_line = [temp_line]

	# Only interested in a sertain number of tokens, specified by style.

	temp_line = temp_line[:style.params]

	# Remove the end of the declaration, specified by style.

	end = temp_line[-1].find(style.close_str)

	if end == -1:

		warning("line \"%s\" may be syntactically incorrect"\

			% line.strip())

		return False

	temp_line[-1] = temp_line[-1][:end]

	# Remove whitespace

	for i in range(0,len(temp_line)-1):

		temp_line[i] = temp_line[i].strip()

	return temp_line

def getModuleXML(file_name):

	'''

	Returns the XML data for a module in a list, one line per list item.

	'''

	# Try to open the file, if it cant, just ignore it.

	try:

		module_file = open(file_name, "r")

		module_code = module_file.readlines()

		module_file.close()

	except:

		warning("cannot open file %s for read, skipping" % file_name)

		return []

	module_buf = []

	# Infer the module name, which is the base of the file name.

	module_buf.append("<module name=\"%s\">\n" 

		% os.path.splitext(os.path.split(file_name)[-1])[0])

	temp_buf = []

	# Phases:	find header - looking for the header of the file.

	#		get header - get the header comments and stop when first

	#			     whitespace is encountered.

	#		find interface - looking for interfaces to get info for.

	phase = "find header"

	# Go line by line and figure out what to do with it.

	for line in module_code:

		# In this phase, whitespace and stray code is ignored at the

		# top of the file.

		if phase == "find header":

			if line.isspace():

				continue

			# Once a comment is encountered, start trying to get the

			# header documentation.

			elif getXMLComment(line):

				phase = "get header"

			# If an interface is found, there is no header, and no

			# documentation for the interface.

			elif getParams(line,INTERFACE)\

				 or getParams(line,TEMPLATE):

				phase = "find interface"

		# In this phase, XML comments are being retrieved for the file.

		if phase == "get header":

			if getXMLComment(line):

				temp_buf.append(getXMLComment(line))

				continue

			# If the line is whitespace, the file header is over,

			# continue on to find interfaces.

			elif line.isspace():

				module_buf += temp_buf

				temp_buf = []

				phase = "find interface"

				continue

			# Oops! The comments we have been getting weren't part

			# of the header so attribute them to an interface

			# instead.

			elif getParams(line,INTERFACE)\

				 or getParams(line,TEMPLATE):

				phase = "find interface"

		# In this phase, XML comments are being attributed

		if phase == "find interface":

			if getXMLComment(line):

				temp_buf.append(getXMLComment(line))

				continue

			# If the line is the declaration of a interface,

			# infer the interface name and add all the comments

			# to the main buffer.

			elif getParams(line,INTERFACE):

				module_buf.append("<interface name=\"%s\">\n"\

					% getParams(line,INTERFACE)[0])

				if len(temp_buf):

					module_buf += temp_buf

				else:

					module_buf.append("<summary>\n")

					module_buf.append("Summary is missing!\n")

					module_buf.append("</summary>\n")

					module_buf.append("<param name=\"?\">\n")

					module_buf.append("Parameter descriptions are missing!\n")

					module_buf.append("</param>\n")

				temp_buf = []

				module_buf.append("</interface>\n")

				continue

			elif getParams(line,TEMPLATE):

				module_buf.append("<template name =\"%s\">\n"\

					% getParams(line,TEMPLATE)[0])

				if len(temp_buf):

					module_buf += temp_buf

				else:

					module_buf.append("<summary>\n")

					module_buf.append("Summary is missing!\n")

					module_buf.append("</summary>\n")

					module_buf.append("<param name=\"?\">\n")

					module_buf.append("Parameter descriptions are missing!\n")

					module_buf.append("</param>\n")

				temp_buf = []

				module_buf.append("</template>\n")

	# The file had no interfaces, just a header.

	if phase == "get header":

		module_buf += temp_buf

	# If there are XML comments at the end of the file, they arn't

	# attributed to anything. These are ignored.

	elif len(temp_buf):

		warning("orphan XML comments at bottom of file %s" % file_name)

	module_buf.append("</module>\n")

	return module_buf

def getLayerXML(directory):

	'''

	Returns the XML documentation for a layer.

	'''

	layer_buf = []

	# Infer the layer name from the directory name.

	layer_buf.append("<layer name=\"%s\">\n" % os.path.basename(directory))

	# Try to open the metadata file for this directory and if it exists,

	# append the contents to the buffer.

	try:

		layer_meta = open(directory+"/"+meta, "r")

		layer_buf += layer_meta.readlines()

		layer_meta.close()

	except:

		warning("cannot open file %s for read, assuming no data"\

			% meta)

	# For each module file in the layer, add its XML.

	for module in glob.glob("%s/*.if" % directory):

		layer_buf += getModuleXML(module)

	layer_buf.append("</layer>\n")

	return layer_buf

def getTunableXML(file_name):

	'''

	Return all the XML for the tunables in the file specified.

	'''

	# Try to open the file, if it cant, just ignore it.

	try:

		tunable_file = open(file_name, "r")

		tunable_code = tunable_file.readlines()

		tunable_file.close()

	except:

		warning("cannot open file %s for read, skipping" % file_name)

		return []

	tunable_buf = []

	temp_buf = []

	# Find tunables and booleans line by line and use the comments above

	# them.

	for line in tunable_code:

		# If it is an XML comment, add it to the buffer and go on.

		if getXMLComment(line):

			temp_buf.append(getXMLComment(line))

			continue

		# Get the parameters of a TUNABLE style line.

		params = getParams(line,TUNABLE)

		tag = "tunable"

		# If the line is not a TUNABLE style declaration, try BOOLEAN.

		if not params:

			params = getParams(line,BOOLEAN)

			tag = "boolean"

		# If the line is one of the two styles above, add a tunable tag

		# and give it the data from the temprorary buffer.

		if params:

			tunable_buf.append\

				("<%s name=\"%s\" dftval=\"%s\">\n"

				% (tag, params[0], params[1]))

			tunable_buf += temp_buf

			temp_buf = []

			tunable_buf.append("</%s>\n" % tag)

	# If there are XML comments at the end of the file, they arn't

	# attributed to anything. These are ignored.

	if len(temp_buf):

		warning("orphan XML comments at bottom of file %s" % file_name)

	return tunable_buf

def getPolicyXML(directory):

	'''

	Return the compelete reference policy XML documentation through a list,

	one line per item.

	'''

	# Keep track of original path so that it will change back at the end.

	old_dir = os.path.abspath(os.path.curdir)

	# Attempt to change directory into the policy directory. If it doesn't

	# exist just return an empty documentation.

	try:

		os.chdir(directory)

	except:

		warning("cannot change directory to %s, ignoring"\

			% directory)

		return []

	policy_buf = []

	policy_buf.append("<policy>\n")

	# Add to the XML each layer specified by the user.

	for layer in layers:

		policy_buf += getLayerXML(layer)

	# Add to the XML each tunable specified by the user.

	for tunable_file in tunable_files:

		policy_buf += getTunableXML(tunable_file)

	policy_buf.append("</policy>\n")

	# Return to old directory.

	try:

		os.chdir(old_dir)

	except:

		error("cannot change directory to %s" % old_dir)

	return policy_buf

def usage():

	"""

	Displays a message describing the proper usage of this script.

	"""

	sys.stdout.write("usage: %s [-w] [-d directory] [-m file] "\

		% sys.argv[0])

	sys.stdout.write("layerdirectory [layerdirectory...]\n\n")

	sys.stdout.write("Options:\n")

	sys.stdout.write("-w --warn		--	"+\

				"show warnings\n")

	sys.stdout.write("-m --meta <file>	--	"+\

				"the filename of the metadata in each layer\n")

	sys.stdout.write("-d --directory <dir>	--	"+\

				"directory where the layers are\n")

	sys.stdout.write("-t --tunable <file>	--	"+\

				"A file containing tunable declarations\n")

def warning(description):

	'''

	Warns the user of a non-critical error.

	'''

	if warn:

		sys.stderr.write("%s: " % sys.argv[0] )

		sys.stderr.write("warning: " + description + "\n")

def error(description):

	'''

	Describes an error and exists the program.

	'''

	sys.stderr.write("%s: " % sys.argv[0] )

        sys.stderr.write("error: " + description + "\n")

        sys.stderr.flush()

        sys.exit(1)

# MAIN PROGRAM

# Check that there are command line arguments.

if len(sys.argv) <= 1:

	usage()

	sys.exit(1)

# Parse the command line arguments

for i in range(1, len(sys.argv)):

	if sys.argv[i-1] in ("-d", "--directory", "-m", "--meta",\

					"-t", "--tunable"):

		continue

	elif sys.argv[i] in ("-w", "--warn"):

		warn = True

	elif sys.argv[i] in ("-d", "--directory"):

		if i < len(sys.argv)-1:

			directory = sys.argv[i+1]

		else:

			usage()

	elif sys.argv[i] in ("-m", "--meta"):

		if i < len(sys.argv)-1:

			meta = sys.argv[i+1]

		else:

			usage()

	elif sys.argv[i] in ("-t", "--tunable"):

		if i < len(sys.argv)-1:

			tunable_files.append(sys.argv[i+1])

		else:

			usage()

	else:

		layers.append(sys.argv[i])

# Generate the XML and output it to a file

lines = getPolicyXML(directory)

for s in lines:

	sys.stdout.write(s)