1	Meta
1.1	Title: DoorScope LUA API Documentation
1.2	Author: rochus.keller@doorscope.ch
1.3	Version: 2014-01-31
1.4	Compatible with: DoorScope 0.9.0
2	Abstract
2.1	This is the official documentation of the DoorScope Lua API.
2.2	This document assumes that the reader is familiar with the Lua 5.1 language (as documented e.g. in the Lua Reference Manual www.lua.org/.../).
3	Class Hierarchy
3.1	SpecialValue
3.2	String
3.3	ContentObject
3.3.1	Repository
3.3.2	Folder
3.3.3	Document
3.3.4	Annotation
3.3.5	Object
3.3.5.1	Title
3.3.5.2	Section
3.3.5.3	Table
3.3.5.4	TableRow
3.3.5.5	TableCell
3.3.5.6	Picture
3.3.5.7	StubObject
3.3.6	Link
3.3.6.1	InLink
3.3.6.2	OutLink
3.3.7	ChangeEvent
3.4	File
4	Synonyms
4.1	int
4.1.1	Synonym for a plain Lua number used as integer.
4.2	luastring
4.2.1	Synonym for a plain Lua string.
4.3	Array
4.3.1	Synonym for a plain Lua table used as an array (index 1..n).
4.3.2	The template notation <Class> is used to specify the type of the array elements.
4.4	Record
4.4.1	Synonym for a plain Lua table with property names as keys.
5	Common Features of all Classes
5.1	Properties
5.1.1	type (read only)
5.1.1.1	The class name of the object
5.1.2	data (read only)
5.1.2.1	Returns the data table of the object
5.2	Meta Methods
5.2.1	__index( name )
5.2.1.1	Returns the property or the named value of the data table, if no property with the given name is known.
5.2.2	__newindex( name, value )
5.2.2.1	If name corresponds to a property, sets the propery to value (or throws an exception if read-only); if not, sets the named value of the data table.
6	Classes
6.1	String
6.1.1	Methods
6.1.1.1	luastring toLatin1()
6.1.1.1.1	Renders the String to latin-1 luastring.
6.1.1.2	luastring toUtf8()
6.1.1.2.1	Renders the String to utf-8 luastring.
6.1.1.3	fromUtf8( luastring )
6.1.1.3.1	Sets the String to luastring interpreted as utf-8.
6.1.1.4	fromLatin1( luastring )
6.1.1.4.1	Sets the String to luastring interpreted as latin-1.
6.1.2	Meta Methods
6.1.2.1	__tostring()
6.1.2.1.1	Renders a latin-1 luastring; same as toLatin1().
6.1.3	Constructor
6.1.3.1	String()
6.1.3.1.1	Creates an empty String.
6.1.3.2	String( luastring )
6.1.3.2.1	Creates a String from a luastring interpreted as latin-1.
6.1.3.3	String( String )
6.1.3.3.1	Creates a String as a copy of another String.
6.2	SpecialValue
6.2.1	Methods
6.2.1.1	luastring toLatin1()
6.2.1.1.1	Renders the value to latin-1 luastring.
6.2.1.2	String toString()
6.2.1.2.1	Renders the value to String.
6.2.1.3	luastring getValueType()
6.2.1.3.1	Returns the type name of the value.
6.2.1.4	int, int, int getDate()
6.2.1.4.1	Renders the value to a date represented as three int on the stack (year, month, day).
6.2.1.5	int, int, int getTime()
6.2.1.5.1	Renders the value to a time represented as three int on the stack (hour, minute, second).
6.2.1.6	String toHtml()
6.2.1.6.1	Renders the value an HTML String.
6.2.2	Functions
6.2.2.1	String toHtmlDiff( new, old, fragment, charset )
6.2.2.1.1	new, old: String, luastring or SpecialValue
6.2.2.1.1.1	The two strings from which the diff is created
6.2.2.1.2	fragment: boolean
6.2.2.1.2.1	true: create a HTML fragment
6.2.2.1.2.2	false: create a full HTML string
6.2.2.1.3	charset: luastring
6.2.2.1.3.1	Defines the character set to be used for the HTML string or fragment; defaults to "latin-1".
6.2.3	Meta Methods
6.2.3.1	__tostring()
6.2.3.1.1	Renders a latin-1 luastring; same as toLatin1().
6.2.4	Constructor
6.2.4.1	SpecialValue()
6.2.4.2	SpecialValue( SpecialValue )
6.3	ContentObject
6.3.1	Methods
6.3.1.1	ContentObject getParent()
6.3.1.1.1	A DoorScope database is a hierarchy of ContentObjects with a Repository on the top of the hierarchy. Each ContentObject (besides the Repository) therefore has a parent, which is returned by this method.
6.3.1.2	Array<ChangeEvent> getHistory()
6.3.1.2.1	Returns an array of ChangeEvent objects which are children of this object.
6.3.1.3	Array<Annotation> getAnnotations()
6.3.1.3.1	Returns an array of Annotation objects which are children of this object.
6.3.1.4	Array<Object> getContent()
6.3.1.4.1	Returns an array of Title, Section, Table, TableRow, TableCell or Picture objects which are children of this object.
6.3.1.5	Array<Folder> getFolders()
6.3.1.5.1	Returns an array of Folder objects which are children of this object. Only the Repository and Folders contain Folder objects. For convenience this method is available on any ContentObject.
6.3.1.6	Array<Document> getDocuments()
6.3.1.6.1	Returns an array of Document objects which are children of this object. A Document is called a Module in DOORS. Only the Repository and Folders contain Document objects. For convenience this method is available on any ContentObject.
6.3.1.7	Record getValues()
6.3.1.7.1	Returns all attributes (key/value pairs) associated with this object; these include the built-in and user defined attributes in DOORS. You can use this method to find out which attributes belong to a specific ContentObject. Remember that due to the __index meta method you can also access each attribute individually.
6.3.2	Meta Methods
6.3.2.1	__index( name )
6.3.2.1.1	If name represents an intrinsic DOORS or DoorScope or a persistent DOORS attribute, its value is returned. Otherwise the value of the data table of the ContentObject or nil is returned.
6.3.2.2	__newindex( name, value )
6.3.2.2.1	If name is an intrinsic DOORS or DoorScope property, a read-only exception is thrown. Otherwise the key/value pair is written to the data table of the ContentObject. Note that these values are not persistent. It is not possible to overwrite DOORS attributes.
6.4	Repository
6.4.1	Inherits ContentObject; in addition the following features are available:
6.4.2	Methods
6.4.2.1	Document selectDocument( title )
6.4.2.1.1	Presents a dialog box from which the user can select a Document. Returns the selected Document or nil.
6.4.2.1.2	title: luastring
6.4.2.1.2.1	Optional string used as title of the dialog box.
6.5	Folder
6.5.1	Inherits ContentObject; no additional features.
6.6	Document
6.6.1	This is the representation of a physical document; corresponds to a DOORS Module.
6.6.2	Inherits ContentObject; no additional features.
6.7	Annotation
6.7.1	This is a review comment associated with a ContentObject.
6.7.2	Inherits ContentObject; no additional features.
6.8	Title, Section, Table, TableRow, TableCell, Picture
6.8.1	These are the objects constituting the text flow of a Document.
6.8.2	Inherits ContentObject; no additional features.
6.9	Link
6.9.1	Inherits ContentObject; in addition the following features are available:
6.9.2	Methods
6.9.2.1	StubObject getStub()
6.9.2.1.1	Returns the redundant Object the Link points to. If you export a Module from DOORS using DoorScopeETL, each peer object of the inbound or outbound Link is redundantly stored as a StubObject together with all it's attributes. This way you can understand the purpose of a Link even without also exporting all referenced Modules from DOORS.
6.10	InLink, OutLink
6.10.1	Inherits Link; no additional features.
6.11	ChangeEvent
6.11.1	Represents a log entry of the change history of a ContentObject.
6.11.2	Inherits ContentObject; no additional features.
6.12	File
6.12.1	Methods
6.12.1.1	int write( luastring, escape )
6.12.1.1.1	Write a luastring to the file. Returns the number of bytes written.
6.12.1.1.2	escape: bool
6.12.1.1.2.1	If true, '<', '>' and '&' are replaced by "&lt;", "&gt;" and "&amp;".
6.12.1.2	luastring read( len )
6.12.1.2.1	Reads from the file and returns a luastring corrsponding to the read content.
6.12.1.2.2	len: int
6.12.1.2.2.1	Optional argument to control the maximum number of bytes to read. Defaults to zero. If zero or below, the whole file is read and returned as luastring.
6.12.1.3	bool isEof()
6.12.1.3.1	Returns true, if there are no more bytes to read from the file. Throws an exception if File is not readable.
6.12.1.4	close()
6.12.1.4.1	Closes the file; this makes sense if you don't use the file anymore and you don't want to wait until the garbage collector deletes the File.
6.12.2	Functions
6.12.2.1	File openForWriting( title )
6.12.2.1.1	Present a file selector dialog to the user where she can select a file name to be opened for writing. If the user cancels the operation, nil is returned. If the file cannot be written, an exeption is thrown.
6.12.2.1.2	title: luastring
6.12.2.1.2.1	Optional title to be displayed on the file selector dialog.
6.12.2.2	File openForReading( title )
6.12.2.2.1	Present a file selector dialog to the user where she can select an existing file to be opened for reading. If the user cancels the operation, nil is returned. If the file cannot be read, an exeption is thrown.
6.12.2.2.2	title: luastring
6.12.2.2.2.1	Optional title to be displayed on the file selector dialog.