** This file is not up to date **

TODO: Add comments and modifications to appropriate functinons, such
as addComponent, newModel, etc. (Low priority)
TODO: Add functions for retrieval of icon information. (High Priority)

API for interactive environment
===============================

The API for interactive/incremental development consist of a set of
Modelica functions. They are sent to the interactive environment as
plain text and parsed using an expression parser for Modelica. The API
will be used by humans when interactively building models, directly or
by using scripts, but also by for instance a model editor who wants to
interact with the symbol table for adding/changing/removing models and
components, etc.

When a function fails to perform its action the string "-1" is returned.


Definitions:
------------
An == Argument no. n
<cref> == Component Reference, e.g. `A.B.C' or `A'
<ident> == identifier, e.g. `A' or `Modelica'
<string> == Modelica string, e.g. `"Nisse"' or `"foo"' 
<expr> == Arbitrary Modelica expression
The following functions are provided:

Function				Meaning
===========				=======
saveModel(<string>,<cref>)		Saves the model (A1) in a file
					given by a string (A0).

loadFile(<string>)			Loads all models in the file,
					return true or false

loadFileInteractive(<string>)		Loads all models in the file
					and return all classes on top
					level of that file.

loadClass(<cref>)			Loads the model (A0) by looking up the 
					correct file to load in $MODELICAPATH. 
					Loads all models in that file into 
					the symbol table.

createModel(<cref>)			Creates an empty model.

deleteModel(<cref>)			Deletes the model from the
					symbol table.

addComponent(<ident>,<cref>,		Adds a component with name (A0),
	<cref>,annotate=<expr>)		type (A1), and class (A2) as
					arguments. Optional
					annotations are given with
					the named argument `annotate'.

deleteComponent(<ident>,<cref>)		Deletes a component (A0)
					within a class (A1).

updateComponent(<ident>,<cref>,		Updates an already existing component.
	<cref>,annotate=<expr>)

addClassAnnotation(<cref>,		Adds annotation given by
	annotate=<expr>)		A1( in the form annotate=classmod(...)) to the
					model definition referenced by A0.
					Should be used to add Icon Diagram and
					Documentation annotation.


getComponentCount(<cref>)		Returns the number of
					components in a class.

getNthComponent(<cref>,<int>)		Returns the belonging class, 
					component name and  type name
					of the nth component of a class.
					e.g. "A.B.C,R2,Resistor"


getNthComponentAnnotation(<cref>,<int>) Returns the flattened
					annotation record of the nth
					component.
					Consists of a comma separated
					string of 15 values, see
					Annotations below, e.g "false,10,30,..."

getInheritanceCount(<cref>)		Returns the number of inherited classes of a class.

getNthInheritedClass(<cref>,<int>)	Returns the type name of the nth inherited class of a class

getConnectionCount(<cref>)		Returns the number of
					connections in the model.

getNthConnection(<cref>,<int>)		Returns the nth connection,
					as a comma separated pair of
					connectors, e.g. "R1.n,R2.p".
getNthConnectionAnnotation(<cref>,<int>)
					Returns the nth connection
					annotation as comma separated
					list of values of a flattened
					record, see Annotation below.
addConnection(<cref>,<cref>,<cref>, annotate=<expr>)
					Adds connection connect(A0,A1)
					to model A2, with annotation
					given by the named argument
					annotate.
updateConnection(<cref>,<cref>,<cref>, annotate=<expr>)
					Updates an allready existing
					connection
deleteConnection(<cref>,<cref>,<cref>)	Deletes the connection connect(A0,A1) in class 
					given by A2. 

addEquation(<cref>,<expr>,<expr>)	Adds the equation A1=A2 to the
					model named by A0.
getEquationCount(<cref>)		returns the number of
					equations in the model named
					A0. (This includes connections)
getNthEquation(<cref>,<int>)		returns the nth (A1) equation of
					the model named by A0. e.g
					"der(x)=-1" or
					"connect(A.b,C.a)"
deleteNthEquation(<cref>,<int>)		Deletes	the nth (A1) equation
					in the model named by A0.
					
getConnectorCount(<cref>)		Returns the number of
					connectors of a class.
					NOTE: partial instantiation of
					inheritance performed

getNthConnector(<cref>,<int>)		Returns the name of the nth
					connector, e.g "n".

getNthConnectorIconAnnotation(<cref>,<int>)	
					Returns the nth connector
					icon layer annotation as comma separated
					list of values of a flat
					record, see Annotation below.
					NOTE: Since connectors can be
					inherited, a partial
					instantiation of the
					inheritance structure is performed.

getNthConnectorDiagramAnnotation(<cref>,<int>)
					Returns the nth connector
					diagram layer annotation as comma separated
					list of values of a flat
					record, see Annotation below.
					NOTE: Since connectors can be
					inherited, a partial
					instantiation of the
					inheritance structure is
					performed.

getIconAnnotation(<cref>)		Returns the Icon Annotation of 
					the class named by A0. 

getDiagramAnnotation(<cref>)		Returns the Diagram annotation of 
					the class named by A0. 
					NOTE: Since the Diagram 
					annotations can be found in base
					classes a partial instantiation is 
					performed that flattens the inheritance 
					hierarchy in order to find all annotations.

getPackages(<cref>)			Returns the names of all Packages in class
					named by A0 as a list,
					e.g. getPackages(Modelica) =>
					{Electrical,Blocks,Mechanics,Constants,Math,SIunits}

getClassNames(<cref>)			Returns the names of all class
					defintions in a class
					(package),
getClassNames()				Returns the names of all class
					definitions in the global scope.

isType(<cref>)				Returns true if class is a type, otherwise false.

isPrimitive(<cref>)			Returns true if class is of primitive type, otherwise false.

isConnector(<cref>)			Returns true if class is a connector, otherwise false.

isModel(<cref>)				Returns true if class is a model, otherwise false.

isRecord(<cref>)			Returns true if class is a record, otherwise false.

isBlock(<cref>)				Returns true if class is a block, otherwise false.

isFunction(<cref>)			Returns true if class is a function, otherwise false.

isPackage(<cref>)			Returns true if class is a package, otherwise false.

existClass(<cref)			Returns true if class exist in symbolTable, otherwise false.

existModel(<cref>)			Returns true if class exist in symbol table and has restriction
					model, otherwise false.

existPackage(<cref>)			Returns true if class exist in symbol table and has restriction
					package, otherwise false.

getComponents(class)			Return a list of all
					components with associated
					info...

setComponentProperties(			Sets the component properties as:
			<cref>,		class
		       <cref>,		component name
		       {<bool>,		final attribute	
		        <bool>,		flow attribute
			<bool>,		protected=true, public = false	
			<bool>},	replaceable = true, otherwise false
		       {<string>	variability,"constant",	"parameter" 
					   "discrete" or ""
			},
			{<bool>,	inner prefix ( = true)
			 <bool>},       outer prefix ( = true)
			{<string>}	causality, "input" "output" or ""
			)

getCrefInfo(cref)                         Returns the string "file,lineno,columno" with the
                                          position info for the specified component reference
                                          Example:
                                          >>> getCrefInfo(Modelica.Electrical.Analog.Basic.Capacitor)
                                          /cygdrive/c/dev/ModelicaLibrary//Modelica/Electrical/Analog/Basic.mo,249,3

getElementsInfo(cref)                     Returns all the elements in a class with the following format:
                                          {attr1=value1, attr2=value2, .... }
                                          In a class can be elements or annotations:
                                          - annotations: { elementvisibility=public|protected, elementtype=annotation }
                                          - elements:
                                            + general attributes: 
                                               { 
                                                 elementvisibility=public|protected, 
                                                 elementfile=file, 
                                                 elementline=line, 
                                                 elementcolumn=column,
                                                 /* the next ones are exactly like in getComponents */
                                                 final=true|false,
                                                 replaceable=true|false,
                                                 inout=inner|outer|innerouter|none
                                                 elementtype=classdef|extends|import|component
                                                 ... /* more here depending on the elementtype. read below */
                                               }
                                               /* depending on the elementtype some more attributes will follow here */
                                               for classdef: classname=id, classrestriction=PACKAGE|..., classfile=file, classline=line, classcolumn=column
                                               for extends: path=name
                                               for import: kind=named|qualified|unqualified 
                                                     + for named: id=id, path=name
                                                     + for qualified: path=name
                                                     + for unqualified: path=name
                                               for component: typename=component_type, names={component_name, "comment"}, flow=true|false, 
                                                              variability="unspecified"|"discrete"|"parameter"|"constant",
                                                              direction="input"|"output"|"unspecified"
                                               
getEnvironmentVar("varname")      returns the contents of the "varname" environment variable
                                  or error if the variable does not exist

setEnvironmentVar("varname", "varvalue")      returns "Ok" if "varname" was set (overwritten) succesfully
                                              or "error" if the variable set failed



ERROR Handling
==============
When an error occur in any of the functions above, the string
"-1" is returned.

Annotations
===========
1. Component annotations.
------------------------
Component annotations are modifications of the following (flattened)
Modelica record:
record Placement
       Boolean visible = true;
       Real transformation.x=0;
       Real transformation.y=0;
       Real transformation.scale=1;	
       Real transformation.aspectRatio=1;	
       Boolean transformation.flipHorizontal=false;
       Boolean transformation.flipVertical=false;
       Real transformation.rotation=0;
       Real iconTransformation.x=0;
       Real iconTransformation.y=0;
       Real iconTransformation.scale=1;	
       Real iconTransformation.aspectRatio=1;	
       Boolean iconTransformation.flipHorizontal=false;
       Boolean iconTransformation.flipVertical=false;
       Real iconTransformation.rotation=0;
end Placement;

Connection annotations are modifications of the following (flattened)
Modelica record:

record Line
  Real points[2][:];
  Integer color[3]={0,0,0};
  enumeration(None,Solid,Dash,Dot,DashDot,DashDotDot) pattern = Solid;
  Real thickness=0.25;
  enumeration(None,Open,Filled,Half) arrow[2] = {None, None};
  Real arrowSize=3.0;
  Boolean smooth=false;
end Line;

This is the Flat record Icon, used for Icon layer annotations
record Icon 
  Real  coordinateSystem.extent[2,2] = {{-10, -10}, {10, 10}});
  GraphicItem[:] graphics;
end Icon;
The textual representation of this flat record is somewhat more
complicated, since the graphics vector can conceptually contain
different subclasses, like Line, Text, Rectangle, etc. To solve this,
we will use record constructor functions as the expressions of these.
For instance, the following annotation
annotation (
Icon(coordinateSystem={{-10,-10}, {10,10}},
graphics={Rectangle(extent={{-10,-10}, {10,10}}),
Text({{-10,-10}, {10,10}}, textString=”Icon”)}));

will produce the following string representation of the flat record
Icon:
{{{-10,-10},{10,10}},{Rectangle(true,{0,0,0},{0,0,0},LinePattern.Solid,FillPattern.None,0.25,BorderPattern.None,{{-10,-10},{10,10}},0),Text({{-10,-10},{10,10}},textString="Icon")}}

This is the flat record for the Diagram annotation:

record Diagram
  Real  coordinateSystem.extent[2,2] = {{-10, -10}, {10, 10}});
  GraphicItem[:] graphics;
end Diagram;

The flat records string representation is identical to the flat record 
of the Icon annotation.

Flat records for Graphic Primitives.
====================================
record Line
  Boolean visible = true;
  Real points[2,:];
  Integer color[3] = {0,0,0};
  LinePattern pattern = LinePattern.Solid;
  Real thickness = 0.25;
  Arrow arrow[2] = {Arrow.None, Arrow.None};
  Real arrowSize = 3.0;
  Boolean smooth = false;
end Line;

record Polygon
  Boolean visible = true;
  Integer lineColor[3]={0,0,0};
  Integer fillColor[3]={0,0,0};
  LinePattern pattern = LinePattern.Solid;
  FillPattern fillPattern = FillPattern.None;
  Real lineThickness = 0.25;
  Real points[2,:];
  Boolean smooth = false;
end Polygon;
  
record Rectangle
  Boolean visible=true;
  Integer lineColor[3]={0,0,0};
  Integer fillColor[3]={0,0,0};
  LinePattern pattern = LinePattern.Solid;
  FillPattern fillPattern = FillPattern.None;
  Real lineThickness = 0.25;
  BorderPattern borderPattern = BorderPattern.None;
  Real extent[2,2];
  Real radius;
end Rectangle;

record Ellipse
  Boolean visible = true;
  Integer lineColor[3]={0,0,0};
  Integer fillColor[3]={0,0,0};
  LinePattern pattern = LinePattern.Solid;
  FillPattern fillPattern = FillPattern.None;
  Real lineThickness = 0.25;
  Real extent[2,2];
end Ellipse;

record Text
  Boolean visible = true;
  Integer lineColor[3]={0,0,0};
  Integer fillColor[3]={0,0,0};
  LinePattern pattern = LinePattern.Solid;
  FillPattern fillPattern = FillPattern.None;
  Real lineThickness = 0.25;
  Real extent[2,2];
  String textString;
  Real fontSize;
  String fontName;
  TextStyle textStyle[:];  //Problem, fails to instantiate if 
			   // styles are given as modification
end Text;
  
record BitMap
  Boolean visible = true;
  Real extent[2,2];
  String fileName;
  String imageSource;
end BitMap;



Issues for Redesign
===================

An interactive function interface could be part of the Modelica
specification or Rationale. In order to add this, the different
implementations (OSM and Dymola and perhaps existing proposals) needs
to be merged. This section presents some naming conventions and other api
design issues that needs to be taken into consideration when deciding
on the standard api.


1. Naming conventions.
   Proposal: function names should begin with a Non-capital letters
   and have a Capital character for each new word in the name, 
   e.g. 
	loadModel
	openModelFile

2. Return type
   There is a difference between the current implementations. OSM
   returns strings, "OK" or "-1", while Dymola returns Boolean, e.g
   true or false.
   Proposal: All functions, not returning information, like for instance
   getModelName, should return a Boolean value.

3. Argument types.
   There is also a difference between implementations for the
   arguments of a function. For instance, Dymola uses strings as model
   and component references, while OSM uses component references.
   E.g loadModel("Resistor") in Dymola, but loadModel(Resistor) in
   OSM.
   One could also use both alternatives, since Modelica will probably
   have function overloading in the near future.

4. Function set
   The major issue is of course which subset of functions to include,
   and what they should do.
   
   Below is a table of Dymola and OSM functions merged together. The
   table also contains a proposal for the standard.

    <s> == string
    <cr> == component reference
    [] == list constructor, e.g. [<s>] == vector of strings

   Dymola		OSM			Description         Proposal
====================================================================
   list()		-			list variables      list

   listfunctions()	-			list function name  listfunctions
						+ description	    

   -			list(<cr>)		print model def.    list(<cr>), list(<s>)

   classDirectory()	-			current directory   currentDirectory()

   eraseClasses()	clear()			removes models      clearClasses()

			clear()			removes all (models clearAll()
						& variables)					

   -			-			clear variables	    clearVariables()

   openModel(<s>)	loadFile(<s>)		load models in file loadFile(<s>)

   openModelFile(<s>)	loadModel(<cr>)		open file that	    loadModel(<cr>),loadModel(<s>)
						contain the model

   saveTotalModel(<s>,<s>)  -			save total modeldef. saveTotalModel(<s>,<s>) 
								     or saveTotalModel(<s>,<cr>)

   -			saveModel(<cr>,<s>)	save model	    saveModel(<s>,<s>) or saveModel(<s>,<cr>)


   -			createModel(<cr>)	create new empty    createModel(<cr>),createModel(<s>)
						model
   eraseClasses([<s>])   deleteModel(<cr>)	remove model from   deleteModel(<cr>),deleteModel(<s>)
						symboltable
   
   instantiateModel(<s>) instantiateClass(<cr>)  instantiate model  instantiateClass(<cr>)
  