Modelling API

The modelling API enables to navigate and to edit the graph of instances. This can be achieved by a very high level API.

Working with instances

Every node already created is associated with a unique uid.

A first function is to find find an item from a plugin. It is specifically usefull to get access to a classifier but can be used for every plugin item.

def cve.find_plugin_item(uid=None)

When getting a classifier object it can be instantiated with the cve.new function :

def cve.new(classifier=None) # new instance from classifier

The cve.new function returns a cveitem. A cveitem has many methods but the following ones are the main ones, which enable to access with get methods and to edit attribute values based on 3 type of actions, set or insert/remove, depending of the attribute type. The reference api of the class cveitem is here

Note that a classifier defines its attributes but also methods. A graphic node, for example in the Viewer meta-model, has a color attribute of type vvector. Changing the color of an instance may be done with:

instance.set_state_value('color',(r,g,b,a))

but the classifier may propose methods: why not a set_color method leading to the equivalent code, for cveitem instanciating a GRNODE classifier:

instance.set_color((r,g,b,a))

but this entirely depends on the classifier definition, while the set_state_value option is always available. The statement instance.set_state_value('color',(r,g,b,a)) will return False if instance is not a GRNODE while set_color will produce an python error.

At any time we can save or load a complete model with the two functions:

def save_as(what=[],filename='unnamed.cve',force_replace=False) # where what is a list of vitems.

def load(filename, plugin=False) # which read a cve file and returns a list of vitems: graph roots.

Defining a meta-model

Classifier definition

A meta-model is also defined with the same type of semantic graph, but indeed it mainly defines classifiers. We can define two type classifiers:

• classifiers representing an autonomous device :

  cl=cve.classifier_device(name="DEVICENAME",role="CVEROLE",rep='filepath',frequency=None[|value(in s)])
  

• classifiers representing a more or less complex object to be used as a sub state of the interface of a device.

  cl=cve.classifier_item(name='ITEMNAME',rep='filepath')
  

  Both are creating a classifier object which may be completed by a list of attributes and methods, thanks to the two classifier methods.

def add_attribute(self,name="attribute_new",classifier=None,
                  cardmin=1,cardmax=1,mandatory=True,default_value=None,specialised=False)
      #classifier is any other classifier or 'vstate', 'vstring', 'vfile', 
      #'vvector', 'vreal', 'vboolean', 'vcolor', 'vint', 'vtransform',
      #'cveitem', 'cvedevice', 'cvebehavior', 'cvepackage', 'cverule', 
      #'cveclassifier', 'cveattribute'
        
def add_methods(self, filename, *args) 

Just note that methods may be used to associate a complex behavior to an instance of the classifier but it is also a way to provide semantic shortcut to basic state change functions, like the set_color(self,(r,g,b,a) method (see above) which may replace a set_state_value(self,'color',(r,g,b,a))

As in many oriented object language the classifier may specialize an other classifier or may be an abstract classifier (not supposed to be instantiated)

   def specialisation(self,fatherclassifier) # to define inheritance
   def set_abstract(self,abstract=True)      # return True if the classifier inherites from the classifier passed in parameters

When creating a new classifier, as any item of the semantic graph, a unique id is automatically generated as a random string. If the meta-model is created within a python script, this unique id will change each time the script is executed. Since classifiers may be find easily, CVE offers a convenient function to create and associate a id with more semantics but which must remain unique. It concatenates a model name, the classifier name and a domain.

cl.uuid=cve.create_fix_uid(modelname,classname,domain)

We can add callbacks to a classifier as for cveitems. Whenever an instance of the classifier is edited the callback will be executed see . This works only when the classifier is taken in charge by a device runtime and it is not part of a static model. Not saved in permanent files.

add_callback # add a callback to a specific item for execution by the current device. This callback is not part of the model but part of the device runtime. 
remove_callback # the complementary function of the previous one. |

Publishing a meta model

Thus to create a meta model, a python script should define the classifiers and save them in a cve file. Obviously the save-as function may be used to save a cve model but this function is overloaded by the create_plugin function which save a list of cveitem in a file but place the file at a correct location to be recognized as a plugin and which manage plugin dependencies.

To create classifiers, it is mandatory to import cve package. But this call imports automatically all the existing plug-ins. When updating a plug-in, the plug-in must be masked and with it all the dependent plug-in. This is the role line 2. Then the cve module may be imported, classifiers can be (re)defined, the plug-in may be (re)made (line 4) and the dependent packages may be unmasked (line 5).

1 modelname='XXX' 
2 execfile(os.environ['CVEROOT']+os.sep+'cve'+os.sep+'util'+os.sep+'maskplugin.py',{'modelname':modelname})
3 import cve
  ...
  create classifiers
  ...
4 cve.create_plugin(name='',PACKS=[],dirname=None,depends=[]): 
5 cve.plugin_retrieve(modelname)