ZBNF-Download content

ZBNF-Download content

Inhalt

Topic:.readme_ZBNF.


1 Links-Overview

Topic:.readme_ZBNF.links.


1.1 Links to concepts using ZBNF

Topic:.readme_ZBNF.links..

Note: They are relative links. If you are using it locally from the ZBNF download you should unpack the ZBNFdocu.zip download parallel to the unpacked ZBNF.zip. Elsewhere show to http://www.vishia.org/ZBNF/sf/docu/readme_ZBNF.html.

Concepts

Tools contained in this download ready to use

Example of using ZBNF


1.2 Links to the vishia-page in internet

Topic:.readme_ZBNF.links..

Some links in the text are related to http://www.en.wikipedia.org sides, they are shown with link_(Wikipedia)


2 The content of this download package

Topic:.readme_ZBNF..

A core part is the ZBNF parser. It is a parser which converts textual content either to a XML representation, or to internal Java data which can be postprocessed in any Java application, or it can produce output text in another form via the built in JZcmd text generator.

Another core part is the JZcmd executer and text generator which can produce any text representation from internal Java data. The JZcmd executer can execute any operation system command line or any Java method with standard argument types.

With both parts some applications are built which are used as helpers for software generation:

The ZBNF parser is used in some more applications outside this download, especially from the author direct for


2.1 The ZBNF syntax and the parser

Topic:.readme_ZBNF...

ZBNF is a Semantic backus naur format. The Z symbolized a S for semantic. The _Backus-Naur_Form_(Wikipedia) may be well known.

The syntax to use is presented and processed with a plain textual script. It is conterted to a internal data structure while starting the parsing process on runtime. Then the parser produce output data which are named and sorted adequate to its semantic identifier and disposition in syntactial components. This data can be outputted as XML tree immediately to post-process with the world of XML. But the data can be stored in Java classes to post process in Java applications too.


2.2 The ZBNF parser and XML

Topic:.readme_ZBNF..whyZbnf.

If you should have a XML script, but you won't edit it elaborately, write the intrinsic content in plain text and convert it!

For example to get complexly ANT-Scripts:


If you have plain formatted text, a.e. from another tool-output, and you will process it with XML-techniques, convert it:

For example a bill of material from older computer software:


Why ZBNF ?

If you will translate a programming language in another one or you will extract some informations from Source code, you can parse the source text with ZBNF and write a translation in Java programming or with XSLT techniques. Therefore you also can implement a translator for an own DSL (Domain Specific Language):

An example is generating Reflection Informations in C or C++ from Header files.

Another example is build a XMI file from Headers and import it to an UML Modell.

The last but not least is a technique to access to data in Java programms. But the structure of data is described in C-Sources (Headerfiles, struct). Therefore Java code is generated from Headerfiles, using ByteDataAccess.java.


2.3 The JZcmd executer and text generator

Topic:.readme_ZBNF...

The text generation may be considered as the reverse technique of parsing a text: Conversion from internal Java data which may be a XML Tree representation, other Treenode representations or free data into plain texts. This texts may be C-sources, Control files for make etc.

The text generation may need preparation methods and data instances, which can be called, created and used inside the JZcmd script for text generation. Furthermore structured programming is need such as if(condition), for(element: container) and call subroutine(args). Therefore the text generation was equipped with that features. Last not least operation system's command line invocations may be need and they are obvious to implement, which is done of course. The result is a univerals script language which is capable to replace all Windows-batch-files, some Unix script files and other script languages, if a standard Java Virtual Machine is present on the system.

ZBNFdocu:JZcmd.html

The JZcmd executer uses a plain textual control script file like for example ZBNFdocu:examples/BillOfMaterial/billOfMaterial.ZText.html. The <&data> are replaced by the data, <:if:condition>, <:for:element:container> etc. controls the text output depending on data.

The text generator is established from autumn 2012. The development of the JZcmd approachs was done in 2013 and in spring of 2014 with combining the Zmake utility with JZcmd.


3 The Source of this download, licence

Topic:.readme_ZBNF..

This download comes from http://sourceforge.net/projects/zbnf, Home-Internetpage is http://www.vishia.org/ZBNF.

For licence see ZBNFroot:licence.html.


4 Feedback, collaboration

Topic:.readme_ZBNF..

There are some possibilities to post questions, hints or improvements on the sourceforge project page.

But you can also write your suggestions of improvement to my private email: hartmut.schorrig@vishia.de.

If you detect some mistakes in the english presentation, and you are a native speaker of english language, please send me a corrected version. If it is only a few corrected sentences, it may be nice to have them too. To find out the source please send also a part of the given wrong text. I'm not a native speaker. I think, the technical american version of english language is proper to use.

If you want to use some of this download as input for your own project, it may be fine to inform me. You have to use the LPGL licence with or without information of me. If you want to use any parts of this download with another licence as LPGL, especially without publishing, you have to contact me.


5 Platforms to use

Topic:.readme_ZBNF..

The whole content of this download, including the ZBNF-Parser and the zbnfjax is developed and substantially used under Windows. Than it is tested under Linux too.

All Java-programs are running without binary differences as well under Windows as under Linux. It should be run under a Macintosh- or any Unix-environment too. - But all command scripts are strong incompatible between Windows and the other systems. There are fine differences in the syntax, which prevent a commonly using of the scripts. Scripts (Windows-batch-files, Unix-bash-shell-scripts) are used to start the execution of the Java-programs. This start scripts are contained twice in the examples of the download and twice in the zbnfjax.


6 Content

Topic:.readme_ZBNF.content.

This download contains the pure ZBNF-Definition and -Parser with sources and examples and the zbnfjax, which uses ZBNF, but SAXON, JDOM and ANT too, with some examples.


6.1 ZBNF-Definition

Topic:.readme_ZBNF.content..

The Main description for ZBNF is provided in english language. This description defines the qualities of the ZBNF. The Definition of ZBNF may be used in other contexts as the here provided ZBNF-parser too. It should be recognized as a independently language definition.


6.2 ZBNF-Parser

Topic:.readme_ZBNF.content..

The ZBNF-Parser is supplied as Executable (jar-File, Java Version 1.6 / 6 or higher is required) to transform any textual inputs to XML, and as Java-Sources to use in Java-applications, which may be postprocessing the parsers result. This solution is independent from other organisations and companies. Only a Java system should be present: The Java-Runtime-Environment (http://java.com/en/download/index.jsp) to run programs, which uses ZBNF, and the Java-development environment (http://www.java.sun.com) to compile Java-Programs.


6.3 ZBNF-Parser-Core-Examples

Topic:.readme_ZBNF.content..

The core examples only use the ZBNF-Parser and additional Java-sources to demonstrate post-processing. This examples are present to explain and demonstrate, but also to test the parser. Older versions of the *.reference-Outputs may be compared with newer invocations to check the consistence respectively changes.


6.3.1 Simple Example: BillOfMaterial

Topic:.readme_ZBNF.content...

The BillOfMaterial is a basicly example to explain ZBNF.


6.3.2 C-Header parsing

Topic:.readme_ZBNF.content...

The CheaderParsing shows a complexly ZBNF-syntax scripts to parse Headerfiles from C-language. The same script is used for ZBNFroot:examples_ZBNF_core/Header2Reflection/readme.html and for ZBNFroot:examples_XML/Header2XMI/readme.html.


6.3.3 Java parsing

Topic:.readme_ZBNF.content...

The JavaParsing shows another complexly ZBNF-syntax scripts to parse Java-Files. The same script is used for ZBNFroot:examples_XML/Java2XMI/readme.html and for Java2C.


6.3.4 Test all features

Topic:.readme_ZBNF.content...

The testAllFeatures Contains some scripts, which should be test all features of ZBNF. A comparision with the reference-outputs can be done after changes in the sources of ZBNF or if environment conditions are modified.


6.3.5 Test encoding

Topic:.readme_ZBNF.content...

The testEncodings shows how encoding works.


6.3.6 Vhdl-Script parsing and post processing

Topic:.readme_ZBNF.content...

The VhdlScript is another application. The Java-src-example shows, how a VHDL-inputscript is parsed and translated to Headerfiles. The VHDL-script contains some constant definitions of ports for an FPGA-design and is used in development of FPGA. From this source data a header file is produced which contains the access informations to the FPGA in an address space of a microprocessor. It is typically for embedded control.


6.3.7 Header2Reflection

Topic:.readme_ZBNF.content...

The Header2Reflection is a ready-to-use-executable contained in the zbnfjax-directory. This Translator reads Headerfiles from a C or C++ development and generates so named Reflection-C-files. The generated reflection files can be added to the users C/C++-Project to access data in a symbolic way. The user needs parts of the CRuntimeJavalike-C/C++-Sourcefiles additional to use this concept, see Jc-Reflection. This download doesn't contains this complex source base, it contains only the Translator header2Reflection.jar with its sources. That is because the translator is a pure ZBNF application too.


6.4 zbnfjax

Topic:.readme_ZBNF.content..

The zbnfjax-Folder contains scripts and jars for the usage of ZBNF: The ZBNF-parser is settled mostly in a XML-environment. ZBNF translates text-files to XML, further processing is done using XSLT. The zbnfjax is a complexly ready to use folder for some applications such as Zmake and Documentation generation. The usage of the most tools needs SAXON as XSLT-Translator and JDOM as Java-source base for processing XML-Files. Both are not part of this download. The user, who want to use the XML-processing features should download this parts from its originally internet pages. See below.

All Examples in this download are able to use as test bench. For dayly working only the zbnfjax-Folder are needed. You may disposed this directory at a suitable.position in your file system. The file zbnfjax/batch_template/setZBNFJAX_HOME.bat should be copied in a directory, which is obtainable by the systems PATH. Its content is to be adapted to your system environment. The additional downloads from SAXON and JDOM are disposed at a adequate directory. It may be suitable to put this files in the zbnfjax-folder too.


6.4.1 What contains the zbnfjax-Folder ?

Topic:.readme_ZBNF.content...


6.4.2 Which other tools and sources are needed ?

Topic:.readme_ZBNF.content...


6.5 Examples using zbnfjax

Topic:.readme_ZBNF.content..

The examples are present to explain and demonstrate the usage, but also to test the tool chain. Older versions of the *.reference-Outputs may be compared with newer invocations to check the consistence respectively changes.


6.5.1 vishia-XML-Documentation generation

Topic:.readme_ZBNF.content...

The DocuGenerationViaXML is contained here completly. The scripts and jars are contained exclusively in the zbnfjax-Folder. The description is visible at www.vishia.org/XmlDocu in german language. The example is used to generate the documentation of this download inclusively this documentation. The Sources of all readme-files are given here as plain texts.


6.5.2 vishia-Zmake-System

Topic:.readme_ZBNF.content...

The ZBNFdocu:ZMake.html is contained here completly. The scripts and jars are contained exclusively in the zbnfjax-Folder. The description is visible at www.vishia.org/Zmake in german language.


6.5.3 ByteDataAccess in Java programs

Topic:.readme_ZBNF.content...

The ByteDataAccessJava describes an Example to access byte data which are given in a structure in file described in C-language-header-files.ZBNF helps to generate Java-Sources, which are useful to access such data in byte[]-arrays in Java. The byte[]-arrays are contents (read from files, got from socket-communication data, write in files or translated with sockets). The script and batch-file to do the generation are contained in zbnfjax. This directory contains a example and the test base for the scripts. See also www.vishia.org/Java/indexByteDataAccess.html


6.5.4 Header to XMI/UML

Topic:.readme_ZBNF.content...

The Header2XMI contains examples to generate an XMI-File for UML-Model-Oriented-Development. The script and batchfile to do the generation are contained in zbnfjax. This directory contains a example and the test base for the scripts.


6.5.5 Java to XMI/UML

Topic:.readme_ZBNF.content...

The Java2XMI is the counterpart to generate an XMI-File for UML-Model-Oriented-Development from a Java base. The script and batchfile to do the generation are contained in zbnfjax. This directory contains all files to generate an UML-Model from the Java-Sources of ZBNF. A project in Rhapsody are included. To use this project, you need a Rhapsody software and licence. It is able to download (evluation licence) from http://www.ibm.com/developerworks/downloads/r/rhapsodydeveloper/learn.html


6.6 JZcmd, Text generation

Topic:.readme_ZBNF.content.JZcmd.

JZcmd helps to generate plain texts from any Java data. Additional it is an universal script to invoke both Java routines and operation system routines (command line). This system is used by the newer version of Zmake and some other tools which outputs texts.

The following schema shows the principle::

cmd line ---------->|
Invoke inside a---->|
Java application    |
                   JZcmd ===========+===>cmdLine
                    ^               +===>generate text output
                    |               +<== read files
                   Users JZcmd      +===>write files, especially text generation
                   script           +===>invoke Java routines,
                                         prepare data.

The JZcmd uses the ZBNF parser internally to translate the Users JZcmd script. The syntax of a JZcmd script is defined internally too.

The ZBNF parser can be used especially for textual given data from any file, defined in the script. The script can contain:

It is possible to invoke Java routines and creating Java instances to post-process parsed data. It may be better to program such things in Java.

The JZcmd script helps to express textual outputs with the following approach:

<+out>
  Plain text <&with_Content_of_Variable>
  <:if>conditional text<.if>
<.+>

The text output has not an indentation by this example, but the JZcmd script can use the indentation! There are some more possibilities.

An example for JZcmd is the code generation for statemachine execution from a Statemachine describing script, see ZBNFroot:examples_ZBNF_core/StateMGen/readme.html. A basic example is contained in ZBNFroot:examples_ZBNF_core/BillOfMaterial/readme.html.

The javadoc-Zbnf/org/vishia/zcmd/Zbnf2Text parses an input text and produces one or more output texts. It uses the capability of JZcmd.


6.7 Zbnf2Text

Topic:.readme_ZBNF.content.Zbnf2Text.

The


6.8 Zmake

Topic:.readme_ZBNF.content.Zmake.

Zmake is another organisation of the making process to compile C-Sources, control a XMI-Conversion or all other generation requests. The basic idea is: 

ZmakeUserScript: ===================JZcmd================>ZmakeExecutionScript:
Keep the users make                   ^                   Generate the ready to use
control file simple.                  |                   make file to execute
                             ZmakeGenCtrlScript:
                             Use a second file,
                             which controls details
                             of the make process.

The older version of Zmake produces only a Apache-ANT XML-make file with XSLT. It is the srcJava_Zbnf:_org/vishia/zbnf/Zmake. The scripts are contains in the zbnfjax/xsl folder of this download.

This version using JZcmd can do both, only prepare the control file which is used for any maker, or execute the make process itself. A produced make file can be

Inside a Zmake script the Dependency checker for C/C++-Language files can be invoked. This resolves the problem of compilation only changed files, also if there are older ones. It helps to mastering the dependency problem.

The ZmakeUserScript is the JZcmd script which is invoked and administrate by the user. It can include a JZcmd script which is administrate by the system's administrator who defines more complex compiler options etc. That is the ZmakeGenCtrlScript. This approach is a possibility, not a necessity.


7 This version, differences to previous versions

Topic:.readme_ZBNF..

The last version of ZBNF on sourceforge was published on january-17, 2010 as version 1.0. Some more versions are published on the vishia_Downloadpage. A Version, designated as ZBNF_110731 was published on the vishia download page. This version is considered as 1.1.

This Version is

 Version 1.2

The version 1.2 has only minor changes for the ZBNF parser and syntax. It's stable. The substantial differences between the Version 1.0 and Version 1.2 is the capability of text generation, command line execution and changes of the Zmake system. On the other hand some examples and applications are improved.

The Version 1.0 provides only one way to generate output texts controled with a script: Using XSLT. But the possibilities to write algorithm in XSLT are not so far. The other way to produce an output requires deep special Java programming work. The Header2Reflection tool is an example for that. 

Input_Text ===> ZBNF_parser ===> XML ===> XSLT ====> Output for example ANT
                       |
                       +======> Java_Programm =====> Output for example Header2Reflection

The Version 1.2 contains the JZcmd capability. With them a more universal Java algorithm can be combined with an execution and text generation script. JZ combines the two letters for Java and ZBNF with the designation cmd for command execution. The capability of text generation is a part of command execution.

The end-user oriented parts of programming can be written in the JZcmd-script. Whereby the Java algorithm supplies basic data preparation which is not need to change usually. 

Input_Text ===> ZBNF_parser ===> XML ===> XSLT ====> Output for example ANT
                       |
                       +======> Java_Programm =====> Output for example Header2Reflection
                       |
                       +======> JZcmd =============> Any execution and output conversation
                       |
                       +==>Java_Progr===> JZcmd ===> More complex but script controlled output
                       |
                       +==> JZcmd zmake ===========> Supports making processes for software generation

With this capabilities the Zmake approach found in the version 1.0 already is changed:


7.1 Changes ZBNF Parser-core

Topic:.readme_ZBNF...

From 1.0 to 1.1

From 1.1 to 1.2:


7.2 Changes zbnfjax

Topic:.readme_ZBNF...

From 1.0 to 1.1

From 1.1 to 1.2


7.3 Changes in sources

Topic:.readme_ZBNF...


7.4 Changes examples

Topic:.readme_ZBNF...

The example for using Zmake for file copying is adapted to the new Zmake approach.

New examples with the new features of text generation.