| 68 | | The parameter can be any Entity from the previously defined Grammar and every Entity of this Type will be checked this way. |
| 69 | | |
| 70 | | And if the Check finds some inconsistency awarningwill be displayed to this Entity Instance in the Editor. |
| 71 | | |
| 72 | | The other files in the Package contain supporting Methodes for the validation |
| 73 | | |
| 74 | | like |
| 75 | | |
| 76 | | {{{ |
| 77 | | EbnfAnalysisUtils.findReferences(rule); |
| 78 | | }}} |
| 79 | | or |
| 80 | | |
| 81 | | {{{ |
| 82 | | EbnfAnalysisUtils.findReferences(rule,resourceDescriptions); |
| 83 | | }}} |
| 84 | | Which find the Rule references inside a BNF-File or outside a BNF-File. |
| 85 | | |
| 86 | | == Quickfixing can be applied to warnings given by Validations: == |
| 87 | | In the File de.ugoe.cs.swe.bnftools.ebnf.ui/de.ugoe.cs.swe.bnftools.ui.quickfix/!EbnfQuickfixProvider.xtend |
| 88 | | |
| 89 | | quickfixes for validation-warnings can be defined e.g.: |
| | 59 | |
| | 60 | The parameter can be any entity type from the previously defined grammar and the validation rule will be applied on every entity of this type. If the validation conditions are not met, a warning message will be produced and displayed next to the violating entity Instance in the editor. The other files in the package contain supporting methods for the validation, such as |
| | 61 | `EbnfAnalysisUtils.findReferences(rule)` or `EbnfAnalysisUtils.findReferences(rule,resourceDescriptions)`, which provide functionality for finding rule references within a BNF file or within a set of BNF files. |
| | 62 | |
| | 63 | == Quick-fixing == |
| | 64 | |
| | 65 | Quick-fixing can be applied to warnings raised by violations of validation constraints. Quick-fixes can be defined in Xtend according to the general framework provided by xText in the file `de.ugoe.cs.swe.bnftools.ebnf.ui/de.ugoe.cs.swe.bnftools.ui.quickfix/EbnfQuickfixProvider.xtend`, e.g.: |
| 112 | | {{{ |
| 113 | | @Fix(EbnfValidator.unusedRuleDescription) |
| 114 | | }}} |
| 115 | | The accaptor inside applies the changes, via two possible ways: |
| 116 | | |
| 117 | | 1. Change the Document itself (like the example shows). |
| 118 | | |
| 119 | | 1. Change the underlying ecoremodel. |
| 120 | | |
| 121 | | == Generation allows to generate other files from a BNF-Document: == |
| 122 | | In our case we create a .fo document, that can be transformed into a PDF-Document using Apache FOP. |
| 123 | | |
| 124 | | It can be customized in the File de.ugoe.cs.swe.bnftools.ebnf/de.ugoe.cs.swe.ebnf.generator/!EbnfGenerator.xtend |
| 125 | | |
| 126 | | Where thedoGeneratemethode defines how the files given by a Resource and a !IfileSystemAccess should generate a new file. While for every relevant Entity from the |
| 127 | | |
| 128 | | BNF a compile Methode handles the generation in the new file, while it calls the compile Methode for every related Entity e.g.: |
| 129 | | |
| 130 | | {{{ |
| 131 | | def void doGenerate(Resource resource, IFileSystemAccess fsa,boolean mode) { |
| | 89 | |
| | 90 | The acceptor inside applies the changes in two possible ways: |
| | 91 | |
| | 92 | 1. Change the Document itself (as shown in the example). |
| | 93 | |
| | 94 | 1. Change the underlying Ecore model. |
| | 95 | |
| | 96 | == Generation == |
| | 97 | |
| | 98 | Generation allows the user to generate other files from a BNF document. In our case we create an intermediate `.fo` document, that can be transformed into a PDF or an RTF document by using Apache FOP. The generation of the intermediate `.fo` document can be customised in Xtend according to the general framework provided by Xtext in the file `de.ugoe.cs.swe.bnftools.ebnf/de.ugoe.cs.swe.ebnf.generator/EbnfGenerator.xtend`. |
| | 99 | |
| | 100 | The `doGenerate` method defines how the file described by a `Resource` and an `IFileSystemAccess` shall be processed in order generate a new file in the target format. The `compile` methods then handle the transformation, for each relevant entity instance and all related entity instances, e.g.: |
| | 101 | |
| | 102 | {{{ |
| | 103 | def void doGenerate(Resource resource, IFileSystemAccess fsa, boolean mode) { |
| 171 | | To include apache fop you need to add all the jars in a folder e.g. Libs in your project, add this folder to your buildpath, cofigure buildpath and add the jars to it and add them in the plugin.xml on the page runtime at classpath. |
| 172 | | |
| 173 | | == Formatting or Prittey Printing is to format the BNF-Document: == |
| 174 | | In the File de.ugoe.cs.swe.bnftools.ebnf/de.ugoe.cs.swe.ebnf.formatting/!EbnfFormatter.xtend |
| 175 | | |
| 176 | | the Method configureFormatting(!FormattingConfig c)allows to define formatting rules |
| 177 | | |
| 178 | | before, after or between Enteties or Keywords. |
| 179 | | |
| 180 | | e.g.: |
| 181 | | |
| 182 | | {{{ |
| 183 | | @Inject extension EbnfGrammarAccess override protected voidconfigureFormatting(FormattingConfig c) |
| | 142 | |
| | 143 | The Apache FOP libraries need to be added to the build path and the plugin dependencies. |
| | 144 | |
| | 145 | == Formatting == |
| | 146 | |
| | 147 | Formatting (or pretty-printing) can be used to automatically format the BNF document by inserting white space where appropriate in order to improve the readability of the document. Formatting can be defined in Xtend according to the general framework provided by Xtext by adapting the file `de.ugoe.cs.swe.bnftools.ebnf/de.ugoe.cs.swe.ebnf.formatting/EbnfFormatter.xtend`. The method `configureFormatting(FormattingConfig c)` describes the formatting rules before, after, or between entity instances or keywords, e.g.: |
| | 148 | |
| | 149 | {{{ |
| | 150 | @Inject extension EbnfGrammarAccess |
| | 151 | override protected void configureFormatting(FormattingConfig c) |
| 241 | | == Also it is possible to add features to the UI via Xtext: == |
| 242 | | Therefor i recomend reading this Guide http://flipsomel.wordpress.com/. |
| 243 | | |
| 244 | | But don't use the @Override annotation! |
| 245 | | |
| 246 | | == Deployment as Plugin: == |
| 247 | | If you want to deploy your the BNF Tools you can use the deployment as plugin: |
| 248 | | |
| 249 | | Rightclick your xTextProject, choose __export__, choose __Plug-in development --> Deployable plug-ins and fragments__, choose all parts of the project, *.ebnf *.ebnf.tests *.ebnf.ui and a directory. After you finish this will generate a jar for every one of the choosen projects. Add these to the pluigin-folder of a eclipse and it should be installed |
| 250 | | |
| 251 | | == Deployment as RCP: == |
| 252 | | If you want to create a Rich client platform for a standalone minimal worbench setup with only your plugin an requiered plugins in it RCP is a good choice (This is for an eclipse 3.x RCP). |
| 253 | | |
| 254 | | First create your __xText Project__, then create a new __Plug-in Project__. Give it a name, |
| 255 | | |
| 256 | | e.g. de.ugoe.cs.swe.bnftools.ebnf.product. Click next, and unchoose __Generate an Activator, a Java Class that controls the plug-in-s life cycle__ and __This plug-in will make contributions to the UI__. Also choose __no__ at __Rich client Platform__. Press finish. |
| 257 | | |
| 258 | | now open the __Manifest.MF__, go to the __Overview page__ and choose __This plug-in in a singleton__. Then go to the __Dependencies page__ and add __org.eclipse.core.runtime__. |
| 259 | | |
| 260 | | Now create a product configuration in your product project, on its __Overview Page__click new, choose a fitting name and ID, your product project as defining Plugin and org.eclipse.ui.ide.workbench as application. Now go back to the __Manifest.MF__and open the __Extensions Page__. There you should now see 1 Extension __org.eclipse.core.runtime.products__ with a product inside. This should have __org.eclipse.ui.ide.workbench__ as application and the given name of the product configuration as name. Rightclick the product and create a new property and if you want you can give it a customized name and value. |
| 261 | | |
| 262 | | Now back to the p __roduct configuration__ and its dependencies page. There you add all your xtext projects and your product, then click __add Requiered Plug-ins__. After this you still need to add the Plugins __org.eclipse.ui.ide.application__ and __org.eclipse.core.net__. Now you can test your product by running it as a Runtime Eclipse, if there is a missing plugin you can find it using the_ _validate plugins option__ in the run configurations plug-ins page . Deploy it using __Export as an Eclipse Product__ in the __product configuration__.__ |
| 263 | | |
| 264 | | @ To make the generator run properly you need to add org.eclipse.xtext.xbase to your product configuration dependencies |
| | 199 | |
| | 200 | |
| | 201 | == Generation UI == |
| | 202 | |
| | 203 | |
| | 204 | See the guide at http://flipsomel.wordpress.com/ (skip the @Override annotations). |
| | 205 | |
| | 206 | TODO: Transfer relevant instructions. |
| | 207 | |
| | 208 | == Deployment as Plugin == |
| | 209 | |
| | 210 | The simplest way to deploy the BNF Tools is to deploy them as a plugin: |
| | 211 | |
| | 212 | * Right click the xTextProject --> Export... --> Plug-in Development --> Deployable plug-ins and fragments |
| | 213 | * Choose all parts of the project, *.ebnf *.ebnf.tests *.ebnf.ui and an output location. |
| | 214 | * Click finish. |
| | 215 | * Transfer the generated JARs in the output location to the pluigin-folder of the target Eclipse distribution and it should be installed. |
| | 216 | |
| | 217 | == Deployment as RCP == |
| | 218 | |
| | 219 | A more portable way to deploy the BNF Tools is as a standalone Rich Client Platform (RCP) application. This results in a standalone minimal workbench setup with only the BNF plugin and required dependencies. |
| | 220 | |
| | 221 | * Create a new Plug-in Project e.g. `de.ugoe.cs.swe.bnftools.ebnf.product`. Click next, and uncheck ''Generate an Activator'', a Java class that controls the plug-in's life cycle and ''This plug-in will make contributions to the UI''. Also choose ''no'' at ''Rich Client Platform''. Press finish. |
| | 222 | * Open the `MANIFEST.MF` of the newly created project, go to the ''Overview'' page and choose ''This plug-in in a singleton'', then go to the ''Dependencies'' page and add `org.eclipse.core.runtime`. |
| | 223 | * Create a product configuration in your product project |
| | 224 | * On its ''Overview'' page, click ''New'', choose a fitting ''name'' and ''ID'', select the product project as ''defining plug-in'' and `org.eclipse.ui.ide.workbench` as ''application''. |
| | 225 | * Go back to the `MANIFEST.MF` and open the ''Extensions'' page. There you should now see one ''Extension'' `org.eclipse.core.runtime.products` with a newly created product inside. This should have `org.eclipse.ui.ide.workbench` as ''application'' and the given name of the product configuration as ''name''. |
| | 226 | * Right-click on the product and create a new ''property'' and optionally give it a customised ''name'' and ''value''. |
| | 227 | * Go back to the product configuration and its ''Dependencies'' page. |
| | 228 | * Add all the xText projects and the newly created product, then click ''Add required plug-ins''. |
| | 229 | * Manually add the plug-ins `org.eclipse.ui.ide.application` and `org.eclipse.core.net`. |
| | 230 | * To make the generator run properly, manually add also `org.eclipse.xtext.xbase` to the dependencies. |
| | 231 | * Test your product by running it as a ''Runtime Eclipse Application''. |
| | 232 | * If there is a missing plug-in you can find it using the ''Validate plug-ins'' option in the run configurations plug-ins page. |
| | 233 | * Deploy it using ''Export as an Eclipse Product'' in the product configuration. |
