docgenerator 0.1.1

data/docgenerator_element.rb

@@ -0,0 +1,570 @@
+class Object
+	alias :old_is_a? :is_a?
+	#Redefine the standard is_a?
+	#Returns also true, if one of the ids is in testvalu
+	def is_a?( testvalue)
+		if testvalue.old_is_a?(Symbol)
+			if old_is_a?(Element)
+				return ids.include?(testvalue) 
+			else
+				return false
+			end
+		else
+			return old_is_a?(testvalue)
+		end
+	end
+end
+#This class defines possible elements of a document.
+#For each type of elements a class is defined.
+#The definition can be done explicite or generic with Element.create.
+#
+#All types of elements are stored in a hash, 
+#the elements can be created via the method Element.get (or element() ).
+#
+#Tracing
+#Often there is the problem, that you get an error when you write the element.
+#But the error is done, when the element is created.
+#When you redefine ELEMENTS_TRACE, some tracing information are stored during creation.
+class Element
+	include Backlinks
+	#Hash with all ids and their corresponding classes.
+	@@ids = Hash.new( )
+	#All attributes are stored in this hash.
+	#The key is the corresponding class.
+	@@attr	= { Element => {} }
+	#All output routines are stored in this hash.
+	#The key is the corresponding class.
+	@@log	= false
+	def Element.log=( log )
+		@@log = log
+	end
+	#Flag, if the calling stack should be analysed for each Element
+	#Only for document debbuging
+	@@trace	= nil
+	#Set Element tracing on/off
+	def Element.trace=( val )
+		@@trace = val
+	end
+
+	SUPPORTED_TARGETS = [ :latex, :html, :wiki, :text, :debug ]
+
+	#Return a element class.
+	def Element.get( name )
+		return @@ids[name]
+	end
+	#This method is called, when a subclass of this class is defined.
+	#This can happen via Element.create or in another programm.
+	#
+	#Add subclasses to the list of all element classes and initialize some internal hashes.
+	def Element.inherited( subclass )
+		puts "New subclass for 'Element' created: '#{subclass}'" if @@log
+		#All attributes of a class are collected in a hash.
+		@@attr[subclass]	= {}
+		#Fill @@ids
+		#There is no possibility to give a list of id's or names to a 'inherit'-method.
+		#So a special method Element.add is used.
+		Element.add( [subclass], subclass )
+	end
+	#Add a new element class or assign another name (synonym) for a class.
+	#The initial call is made by Element.inherited.
+	def  Element.add( idlist, elementClass )
+		if ! elementClass.new.kind_of?( Element )
+			raise "Element.add get no Element-class #{elementClass}"
+		end
+		if ! idlist.kind_of?( Array )
+			idlist = [ idlist ]
+		end
+		idlist.each{|id|
+			if @@ids[ id ] == nil
+				puts "Element class '#{id}' is new: #{elementClass}" if @@log
+				#All new ids are collected
+				@@ids[ id ] = elementClass
+			elsif	@@ids[ id ] == elementClass
+				puts "Element class '#{id}' is defined double: #{elementClass}" if @@log
+			else
+				puts "Error: ID '#{id}' is redefined #{@@ids[id]} -> #{elementClass}"
+				@@ids[id] = elementClass
+			end
+		}
+	end
+	
+	#Generic creation of a new class to define a new element.
+	#-	name must be defined.
+	#-	attr is a hash with all attributes.
+	#	For details see Element.add_attributes
+	#-	content is a flag, which defines if the element contains "content".
+	#	Valid values are:
+	#	-	true:	content available and necessary (e.g. <p>)
+	#	-	:empty_ok: content available, but not necessary (e.g. <td> or iframe)
+	#	-	false:	no content, no endtag, but tag closed with / (example: <br />)
+	#	-	nil:		no content, no endtag, no closing	(example: <br>)
+	#-	output contains a hash with logic, how to handle the output.
+	#	-:htmltag	Tag for html-output.
+	#	-:latex	Template for LaTeX-output
+	#	-:html		Template for HTML-output
+	def  Element.create( name, attr = {}, content = false, output = {} )
+		#First some checks
+		if ! attr.kind_of?( Hash )
+			raise "Type error Element.create: Expected Hash, get #{attr.class}"
+		end
+		#Generic class creation
+		elementclass = Class.new( Element )
+		#Add the id of the new class to central collection.
+		Element.add( name, elementclass )
+
+		#Set a flag, if the class can contain 'content'.
+		#-true:	content available and necessary (e.g. <p>)
+		#-:empty_ok: content available, but not necessary (e.g. <td>)
+		#-false:	no content, no endtag, but tag closed with / (example: <br />)
+		#-nil:		no content, no endtag, no closing	(example: <br>)
+		elementclass.class_eval( %Q|
+			def content?()
+				return #{content.inspect}
+			end|)
+		
+		output.each{ |k,v|
+			case k
+			when :latex
+				elementclass.add_output( :latex,	v )
+			when :html
+				elementclass.add_output( :html,	v )
+			when :text
+				elementclass.add_output( :text,	v )
+			when :wiki
+				elementclass.add_output( :wiki,	v )
+			when :htmltag
+				if v
+					elementclass.class_eval( "def htmltag()\n'#{v}'\nend" )
+				else
+					elementclass.class_eval( "def htmltag()\nnil\nend" )
+				end
+			else
+				puts "Unknown format #{k} for #{name}"
+			end
+		}
+		elementclass.add_attributes( attr )
+		#Return the class.
+		return elementclass
+	end
+	#Return all id's of the class.
+	#This method is expanded in Element.add.
+	def ids( )
+    myids = []
+    @@ids.each{|k,v| myids << k if v == self.class }
+		return myids
+	end
+	#Prepares an overview on all Elements.
+	#Can be used for some debugging.
+	def Element.overview( list = @@ids.values.uniq )
+		if ! list.kind_of?(Array)
+			list = [ list ]
+		end
+		result = '=' * 10 + "\nElement overview:"
+		list.each{ |k|
+			result += "\n#{k}\n"
+			result += "\tId's:\t\t"
+			result += k.new.ids.join("\n\t\t\t")
+			result += "\n\tAttributes:\t"
+			result += "can contain "
+			result += "no " if ! k.new.content?
+			result += "content\n\t\t\t"
+			@@attr[k].each{ |k2,v|
+				result += "#{k2}:\t#{v.inspect}\n\t\t\t"
+			}
+		}
+		return result
+	end
+	#Add possible attributes to an element class.
+	#Attributes are defined in a hash, each key get a array with values.
+	#The values can be:
+	#-	OBLIGATORY/OPTIONAL
+	#-	Alias (this allows the usage of a position and a name for a parameter).
+	#-	allowed elements ( e.g. list content only list items)
+	#Problem: Attributes are not inherited. See Element.get_attribute_list
+	#
+	#This method is called from a subclass. 
+	#Fixme: add_attributes overwrites everything.
+	def Element.add_attributes( attr )
+		elattr	= @@attr[self]	#self is the class 
+		attr.each{ |k,a |
+			elattr[k] = a
+		}
+	end
+	#Returns list of attributes.
+	#Can be used for copying attributes from one class to another class.
+	def Element.get_attribute_list( elementclass )
+		return @@attr[elementclass]
+	end
+	#Add an output routine.
+	def Element.add_output( target, string )
+		case target
+		when :latex
+			cmd = "def to_latex()\n"
+		when :html
+			cmd = "def to_html()\n"
+		when :text
+			cmd = "def to_text()\n"
+		when :wiki
+			cmd = "def to_wiki()\n"
+		else
+			puts "#{self}: Undefined target format #{target}"
+		end
+		if ! string.kind_of?( String )
+			puts "Error element <#{self.new.ids}>: #{string.inspect} is no String"
+		end
+		template = string.gsub(/\\/, '\\\\\\')
+		template.gsub!(/"/, '\"')
+		cmd += "\"#{template}\"\n"
+		cmd += "end\n"
+		class_eval( cmd )
+	end
+	#Defines an element.
+	#
+	#There are two ways to add values:
+	#-	"named" values in an hash.
+	#	This named values can be attributes of a HTML-Tag or Parameters of a TeX-Makro.
+	#	There is a check, if the attribute exist.
+	#-	Content. Values "inside" the element.
+	#	The content can be the content of a HTML-Tag or the content of a TeX-Environment.
+	#	There is a check, if this class allows content.
+	def initialize( attr={}, content = nil)
+		#@attr is a hash containing the values for each attribute.
+		@attr = Hash.new(  )
+    if self.content?()
+      @content	= []
+    else
+      @content	= nil
+    end
+		@part_of	= []	#list of elements, where this element is part of (normaly only one element)
+		@part_of_doc	= []	#list of documents, where this element is part of (normaly only one element)
+		@crbefore	= false	#make \n before element
+		@crmid	= false	#make \n before and after opening/closing html-tag
+		@crafter	= false	#make \n after element
+		#List of targets, where the element can be used.
+		#Details see method restrict_to()
+		#Default: allsupported targets
+		@targets	= SUPPORTED_TARGETS.dup
+    @suppressed_targets = []
+		
+		#Initialize the attribute hash.
+		@@attr[self.class].each{ |k,a|
+			#type check on Attribute does not work .
+			if a.kind_of?( Symbol )
+				#Filled in the second run
+				#~ @attr[k] = @attr[a]
+			elsif a	#.kind_of?( Attribute )
+				@attr[k] = a.new( k, self )
+			else
+				@attr[k] = Attribute.create().new( k, self )
+			end
+		}
+		#Assign Alias-Attributes
+		@@attr[self.class].each{ |k,a|
+			next if !a.kind_of?( Symbol )
+			if @attr[a]
+				@attr[k] = @attr[a]
+			else
+				puts "Undefined Alias-Attribute #{k}"
+				@attr[k] = Attribute.create().new( k, self )
+			end
+		}
+		attr.each{ |k,v|
+			if @attr[k]
+				@attr[k] << v
+			else
+				puts "Usage of unknown attribute '#{k}' in '#{self.ids.join(',')}'"
+			end
+		}
+		@called_by = prepare_tracing_info( @@trace )
+		self << content if  content 
+	end
+	#List (array) of targets, where the element can be used.
+	#Default are all supported targets.
+	#
+	#With restrictions of this attribute, elements can be restricted on special documents.
+	def restrict_to( *argv )
+		@targets = []
+		@suppressed_targets = SUPPORTED_TARGETS.dup
+		puts "Element#restrict_to: #{self.inspect} restrict to #{argv.inspect}" if @@log
+		argv.each{ |arg|
+			#~ if ! SUPPORTED_TARGETS.include?( arg )
+			if ! @suppressed_targets.delete( arg )
+				puts "Restriction for unsupported target #{arg}" if @@log
+			end
+      @targets	<< arg
+		}
+		self
+	end
+	#Only for debbuging reasons.
+	#Should contain the first "no docgenerator.rb-place, where part is called
+	#if @@trace is on, some tracing information is stored during creation.
+	def prepare_tracing_info( doit = @@trace )
+		return nil if ! doit
+		caller().each{|c|
+			next if ( /DocumentGenerator/ =~  c )
+			return c
+		}
+		#--> No calling stack found --> Error		
+		puts '----'*10
+		puts 'Element#prepare_tracing_info: Found no starting place in caller stack'
+		caller().each{|c| puts c }
+		puts '----'*10
+		return caller()
+	end
+	def inspect()
+		if @@trace
+			called_by	= ", Created in #{@called_by}"
+		else
+			called_by	= nil #'unknown. Please set Elements.trace if needed'
+		end
+		return "<Class Element(#{self.ids.join(',')})#{called_by}>"
+		#~ if @content
+			#~ return "<Class Element(#{self.ids.join(',')}) @content=#{@content.inspect}>"
+		#~ else
+			#~ return "<Class Element(#{self.ids.join(',')}) @attr=#{@attr.inspect}>"
+		#~ end
+	end
+	#Accessor on content
+	attr_reader :content
+	#Add something to the content.
+	#Only possible on elements, which supports "content".
+	def << ( content )
+		if @content
+			@content << content
+		else
+			puts "Add content to an element without this feature (#{self.ids}, #{content.inspect}"
+			#~ @site.add2log( :error, "Add content to an element without this feature (#{self.ids}, #{content.inspect}" )
+		end
+		set_backlink( content )
+	end
+
+	#Add content after a target (other content)
+	#	insertafter(target,*obj)
+	#Requires the ability of "content".
+	def insertafter(target,*obj)
+		self.insert(target, 1, obj)
+	end
+	#Add content before a target (other content)
+	#	insertbefore(target,*obj)
+	#Requires the ability of "content".
+	def insertbefore(target,*obj)
+		self.insert(target, 0, obj)
+	end
+	#Insert content relative to a given target.
+	#The target must exist, pos defines the relative position (0=before, 1=one after the element).
+	#Method called by Element#insertbefore and Element#insertafter.
+	def insert(target,pos,*obj )
+		if @content
+			if @content.include?( target )
+				@content[@content.index(target)+pos ,0] = obj
+			else
+				puts "Insert content not possible. Reference object does not exist (#{target.inspect})"
+			end
+		else
+			puts "Add content to an element without this feature"
+		end		
+		self
+	end
+	#Delete the given object.
+	def delete(target )
+		if @content
+			@content.delete( target )
+		else
+			puts "Delete content of an element without this feature"
+		end		
+		self
+	end
+	#Insert an empty line after the last entry
+	def cr()
+		@crafter	= true
+		self
+	end
+	#Insert an empty line before and after the last entry
+	def Cr()
+		@crbefore	= true
+		@crafter	= true
+		self
+	end
+	#Insert an empty line after the last entry and after the opening of the tag.
+	#This feature has it reason for lists, when each :li-tag gets a cr.
+	#The first item gets also a cr.
+	def cR()
+		@crbefore	= false
+		@crmid	= true
+		@crafter	= true
+		self
+	end
+	#Insert an empty line before and after the last entry and after the opening of the tag.
+	def CR()
+		@crbefore	= true
+		@crmid	= true
+		@crafter	= true
+		self
+	end
+	#Accessor on attribute list
+	attr_reader :attr
+	#Return an attribute to add content.
+	def [] (key)
+		attr = @attr[key]
+		if !attr
+			puts "Request unknown attribute '#{key}', return a dummy"
+			attr = Attribute.create( ).new(key, self)
+		end
+		return attr
+	end
+	#Default setting, each element class may contain contents.
+	#Can be redefined by Elements.create.
+	#-true:	content available and necessary (e.g. <p>)
+	#-:empty_ok: content available, but not necessary (e.g. <td>)
+	#-false:	no content, no endtag, but tag closed with / (example: <br />)
+	#-nil:		no content, no endtag, no closing	(example: <br>)
+	def content?()
+		return true
+	end
+	#check if there is content assigned.
+	def empty?()
+		return @content.empty?
+	end
+	@@level = 0
+	#Build a String to be used for the target document.
+	#Calls Element#to_latex and Element#to_html.
+	def to_s( target = Document.target( self ) )
+		#Return empty string, if target is not requested.
+		if ! @targets.include?( target )
+      if @suppressed_targets.include?(target)
+			puts "Element#to_s: Content of #{self.inspect} suppressed for Target #{target.inspect}." if @@log
+      else
+			puts "Element#to_s: Target #{target.inspect} not supported for #{self.inspect}." if @@log
+      end
+			return ''
+		end
+		#Some checks
+		@attr.each{|k,v|
+			if v.required? and v.to_s == '' and v.settings.include?(target)
+				puts "#{self.ids}: Attribut '#{k}' without required value"
+			end
+		}
+		#Build the string.
+		result = ''
+		case target
+		when :latex
+			result = to_latex()	
+		when :html
+			result = to_html()
+		when :wiki
+			result = to_wiki()
+		when :text
+			result = to_text()
+		when :debug
+			@@level += 1
+			result = "\n<element #{self.ids.join(',')} begin>"
+			@attr.each{|k,v|
+				#result += "\n\t#{k}: #{v.inspect}" 
+				if v != []
+					result += "\n\t#{k}:" 
+					v.each{|v2|
+						result += v2.to_s
+					}
+				end
+			}
+			result += @content.to_s
+			result += "\n<element #{self.ids.join(',')} end>"
+			@@level -= 1
+			result.gsub!(/^/, "\t" * @@level ) 
+		else
+			puts "Undefined target format '#{target}'"
+		end
+		#Already added in submethods
+		#~ result = "\n#{result}" 	if @crbefore
+		#~ result << "\n" 			if @crafter
+		return result
+	end
+	#This is a dummy method, called from Element#to_s for the target format LaTeX.
+	#This method must be overwritten from the element class.
+	#
+	#By default, the concatenation of all ids and the content is taken.
+	def to_latex()
+		puts "Missing output routine for LaTeX (#{self.ids.join(',')}) [#{@called_by}]" if @@log
+		cmd	=	''
+		cmd	<<	"\n" if @crbefore
+		cmd	<<	"\\#{self.ids}{#{@content}}"
+		cmd	<<	"\n" if @crafter
+		return cmd
+	end
+	#Method for definition inside Element.create.
+	def linebreak( flag = true )
+		flag ? "\n" : ''
+	end
+	#Prints the optional attribut key inside []. If empty, nil is returned
+	def texoptional(key)
+		return nil if ! @attr[key].filled?
+		return "[#{@attr[key]}]"
+	end
+	#Build key-val options from attributs.
+	#Used e.g. by includegraphics.
+	def texkeyval()
+		keyval = []
+		@attr.sort_by{|k,v| v.sortkey	}.each{|k,v|
+			keyval << "#{k}={#{v}}" if v.to_s != '' and v.texkeyval?
+		}
+		return keyval.join(', ')
+	end
+	#Method for html-output.
+	#If the method is redefined, the result is taken as a tag.
+	def htmltag()
+		''
+	end
+	#This is a dummy method, called from Element#to_s for the target format HTML.
+	#The tag from Element.htmltag is taken and all attributes and the content are used.
+	#
+	#This method can be overwriten from the element class.
+	def to_html()
+		tag = htmltag()
+		if ! tag 
+			puts "No HTML element available (#{self.ids.join(',')})" if @@log
+			return ''
+		elsif tag == ''
+			tag = 'span' 
+			puts "Missing output routine for HTML (#{self.ids.join(',')}) [#{@called_by}]" if @@log
+		end
+		#Test if the HTML-Tag should contain something, but there is nothing.
+		#If :empty_ok it is ok, that there is no content (e.g <td>)
+		#May make problems, if an empty tag is used to set a id-mark.
+		if content?() and content? != :empty_ok and
+			( ! @content or @content == [] or @content == [nil] )
+			puts "HTML-Tag #{tag} without content -> ignored"	if @@log
+			return ''
+		end
+		html	= String.new()
+		html	<<	"\n" if @crbefore
+		html  << "<#{tag} "
+		@attr.sort_by{|k,v|	 v.sortkey }.each{|k,v|
+			html << "#{k} = \"#{v}\" " if v.to_s != '' and v.html?
+		}
+		if @content
+			html << ">"
+			html	<<"\n" if @crmid
+			html << "#{@content}"
+			html	<< "\n" if @crmid and @content.size > 0 and html[-1,1] != "\n"
+			html << "</#{tag}>"
+		elsif	content?() == nil
+			html	<< '>'
+		else
+			html << '/>'
+		end
+		html	<<	"\n" if @crafter
+		return html
+	end	#to_html
+	def to_wiki()
+		puts "Missing output routine for Wiki (#{self.ids.join(',')}) [#{@called_by}]" if @@log
+		return "#{@content}\n"
+	end
+	def to_text()
+		puts "Missing output routine for Text (#{self.ids.join(',')}) [#{@called_by}]" if @@log
+		text = String.new()
+		text	<<	"\n" if @crbefore
+		text = "#{@content}".strip
+		text	<<	"\n" if @crafter
+		return text
+	end
+end