61 9 The implementation instance's ``generation_context`` variable is set, so |
68 9 The implementation instance's ``generation_context`` variable is set, so |
62 then it can be used in the actual generation. |
69 then it can be used in the actual generation. |
63 10-11 Output generation methods are called |
70 10-11 Output generation methods are called |
64 ====== ======================================================================== |
71 ====== ======================================================================== |
65 |
72 |
66 Plug-in interface class source |
|
67 ------------------------------ |
|
68 |
73 |
69 The following source listings show the most important parts of the ``ImplReader`` |
74 .. _plugin-howto-plugin-interface-validation: |
70 and ``ImplBase`` classes from a plug-in's point of view: |
|
71 |
75 |
72 .. code-block:: python |
76 Validation |
|
77 ---------- |
73 |
78 |
74 class ReaderBase(object): |
79 .. note:: |
75 """ |
80 |
76 Base class for implementation readers. |
81 See also :ref:`validation-overview` |
77 |
|
78 Each reader class supports one XML namespace, from which it reads an implementation |
|
79 instance. |
|
80 |
|
81 The method for parsing an implementation (read_impl()) is given an ElementTree |
|
82 XML element as the root from which to parse the implementation. The plug-in |
|
83 machinery handles each XML file so that the correct reader class is used to read |
|
84 the implementations from XML elements based on the namespaces. |
|
85 """ |
|
86 |
|
87 # The XML namespace supported by the implementation reader. |
|
88 # Should be something like "http://www.xyz.org/xml/1". |
|
89 # Can also be None, in which case the reader will not be used |
|
90 # (this can be useful for defining base classes for e.g. readers |
|
91 # for different versions of an implementation). |
|
92 NAMESPACE = None |
|
93 |
|
94 # Any extra XML namespaces that should be ignored by the |
|
95 # implementation parsing machinery. This is useful for specifying |
|
96 # namespaces that are not actual ImplML namespaces, but are used |
|
97 # inside an implementation (e.g. XInclude) |
|
98 IGNORED_NAMESPACES = [] |
|
99 |
|
100 # Supported implementation file extensions. |
|
101 # Sub-classes can override this to add new supported file extensions |
|
102 # if necessary. The file extensions simply control whether implementations |
|
103 # are attempted to be read from a file or not. |
|
104 # Note that the extensions are case-insensitive. |
|
105 FILE_EXTENSIONS = ['implml'] |
|
106 |
|
107 @classmethod |
|
108 def read_impl(cls, resource_ref, configuration, doc_root): |
|
109 """ |
|
110 Read an implementation instance from the given element tree. |
|
111 |
|
112 @param resource_ref: Reference to the resource in the configuration in |
|
113 which the given document root resides. |
|
114 @param configuration: The configuration used. |
|
115 @param doc_root: The document root from which to parse the implementation. |
|
116 @return: The read implementation instance, or None. |
|
117 """ |
|
118 raise exceptions.NotSupportedException() |
|
119 |
82 |
120 .. code-block:: python |
83 The ConE plug-in interface allows for the extension of ConfML and ImplML validation. |
|
84 In the same way as support for new implementation languages can be provided |
|
85 by exposing implementation reader classes via egg entry points, validation |
|
86 can be extended by exposing validator classes. |
121 |
87 |
122 class GenerationContext(object): |
88 Validation happens roughly in the following manner: |
123 """ |
|
124 Context object that can be used for passing generation-scope |
|
125 data to implementation instances. |
|
126 """ |
|
127 |
|
128 def __init__(self, tags={}): |
|
129 # The tags used in this generation context |
|
130 # (i.e. the tags passed from command line) |
|
131 self.tags = tags |
|
132 |
|
133 # A dictionary that implementation instances can use to |
|
134 # pass any data between each other |
|
135 self.impl_data_dict = {} |
|
136 |
89 |
137 .. code-block:: python |
90 1. A list of *validator classes* is obtained through some means. In practice |
|
91 this usually means finding all validator classes, and then filtering them |
|
92 down to those that produce the problems that we are interested in. |
|
93 2. A *validation context* is created. This contains everything associated with |
|
94 the validation, and here all found problems are reported. All validators |
|
95 have access to it. |
|
96 3. For each entity (configuration or implementation instance) that is being |
|
97 validated, an instance of each validator class is created and invoked. |
138 |
98 |
139 class ImplBase(object): |
99 This process is nearly the same for ConfML and ImplML validation, only some |
140 """ |
100 details about the validation context and the entities being validated are |
141 Base class for any confml implementation. |
101 different, as well as the fact ConfML validation on the entire configuration, |
142 """ |
102 whereas ImplML validation happens on individual implementation instances, with |
143 |
103 a few exceptions. |
144 # Identifier for the implementation type, used e.g. in .cfg files. |
|
145 # Should be a string like e.g. 'someml'. |
|
146 IMPL_TYPE_ID = None |
|
147 |
|
148 # Defines the default invocation phase for the implementation. |
|
149 # The default is used if the phase is not explicitly set in the |
|
150 # ImplML file or manually overridden by calling set_invocation_phase() |
|
151 DEFAULT_INVOCATION_PHASE = None |
|
152 |
|
153 def __init__(self,ref, configuration): |
|
154 """ |
|
155 Create a ImplBase object |
|
156 @param ref : the ref to the Implml file resource. |
|
157 @param configuration : the Configuration instance for the |
|
158 configuration data. |
|
159 """ |
|
160 self._settings = None |
|
161 self.ref = ref |
|
162 self.index = None |
|
163 self.configuration = configuration |
|
164 self.output_root = self.settings.get('output_root','output') |
|
165 self.output_subdir = self.settings.get('output_subdir','') |
|
166 self.plugin_output = self.settings.get('plugin_output','') |
|
167 |
|
168 self.generation_context = None |
|
169 self._tags = None |
|
170 self._invocation_phase = None |
|
171 self._tempvar_defs = [] |
|
172 |
104 |
173 def generate(self): |
105 The following diagram illustrates ImplML validation: |
174 """ |
106 |
175 Generate the given implementation. |
107 .. image:: impl-validation-classes.jpg |
176 @return: |
108 |
177 """ |
109 The following diagram illustrates ConfML validation: |
178 raise exceptions.NotSupportedException() |
110 |
179 |
111 .. image:: confml-validation-classes.jpg |
180 def post_generate(self): |
112 |
181 """ |
113 For more information on the classes involved in validate see the |
182 Called when all normal generation has been done. |
114 ConE API epydoc for `cone.validation.implmlvalidation <../../epydoc/cone.validation.implmlvalidation-module.html>`_ |
183 |
115 and `cone.validation.confmlvalidation <../../epydoc/cone.validation.confmlvalidation-module.html>`_. |
184 @attention: This is a temporary method used for implementing cenrep_rfs.txt generation. |
116 Also the built-in validators in the package `cone.validation.builtinvalidators <../../epydoc/cone.validation.builtinvalidators-module.html>`_ |
185 """ |
117 can serve as examples. |
186 pass |
|
187 |
|
188 def list_output_files(self): |
|
189 """ |
|
190 Return a list of output files as an array. |
|
191 """ |
|
192 raise exceptions.NotSupportedException() |
|
193 |
|
194 def get_refs(self): |
|
195 """ |
|
196 Return a list of all ConfML setting references that affect this |
|
197 implementation. May also return None if references are not relevant |
|
198 for the implementation. |
|
199 """ |
|
200 return None |
|