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.
zbnfjax - tools contained in this download, which uses ZBNF and XML, ready to work.
header2Reflection - Tool to generate reflection-information from C-language header files. The reflection will be present as C-source ready
to embed in user projects.
C-header to XMI conversion - Tool to convert C-language header files to a XMI-file (XMI Version 1.3) to import as UML-model in an UML-tool. This represents
structures of C-written software in graphical UML-form.
Java to XMI conversion - Tool to convert Java-language source files to a XMI-file (XMI Version 1.3). Adequate presentation of software structures
from java source in UML.
ZmakeAnt - Tool in this download which creates ANT-XML-makefiles from a plain-text-making-prescript.
Zmake - Tool in this download to generate make control files from a plain-text-making-prescript.
Docu generation via XML tools contained in this download, which supports writing the source of documentation in plain text and convert it to html
or word-2003-XML.
ByteDataAccess - Generation of java-code from C-language header files to access structure binary data.
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:
Parsing of Java source files and C header files, convert via _XSLT_(Wikipedia) techniques to a _XMI_(Wikipedia)-File. The XMI-File is inputted in a _UML_(Wikipedia)-Tool. The author uses Rhapsody from IBM yet (Version 7.3). The XMI-format is still 1.3, newer formats will be supported later.
Conversion of some sources, especially XMI and plain text topics to generate documentation. The documentation generation process
is controlled with a simple text script which is parsed with ZBNF, converted to an XSL script to control the XSLT-process.
The output format of the text is XHTML and Word-2003-XML which can inputted to the original Microsoft Word 2003 but to open
office too.
Parsing C headerfiles to generate C-sourcefiles which presents Reflection information. Therewith an access to embedded devices via ethernet, serial or dual-port-interface is done. The libraries to access it
are not part of this download but are available as open-source in the Java2C-download.
Describing state machine behavior in plain texts, parsing it and generate C-sources and documentation to execute and present
the state machines. It is a opposite technique to usage of UML-Tools respectively the XMI-format of a UML-designed state machine
is used for code generation and documentation.
Parsing of _Structured_text_(Wikipedia)-sources (SCL-Files) to build derived secondary sources for variable access.
The ZBNF parser is used in some more applications outside this download, especially from the author direct for
parsing a script to present graphical information GRAL.
parsing Java sources to translate it to C-soources: Java2C.
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):
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.
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.
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.
The jar-file is contained in zbnfjax/Zbnf.jar, though it isn't depend from other parts of zbnfjax. The user can post-process the XML-result with any XML-system after whish.
The srcJava_Zbnf-Folder contains the Java-Sources for Zbnf. There are all sources for Zbnf, not more, not less. The compilation of this sources
to the Zbnf.jar is controlled with the make/makejar_Zbnf.bat
The Conversion text to XML using ZBNF (Zbnf2Xml) is described yet only in german language in ZBNFdocu:Zbnf2Xml.html, but see the software documentation javadoc-Zbnf/org/vishia/zbnf/Zbnf2Xml.
The invocation of the parser in a Java environment is described yet only in german language in ZBNFdocu:ZbnfJava.html, but see the software documentation javadoc-Zbnf/org/vishia/zbnf/ZbnfJavaOutput.
The javadoc-Zbnf/org/vishia/zcmd/Zbnf2Text parses an input text and produces one or more output texts. It uses the capability of Chapter: 6.6 JZcmd, Text generation.
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.
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.
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: Since about 2016 the focus is the JZtxtcmd capabilities. Another focus is Header2Reflection for the Inspector concept and documentation generation. See zbnfjax-readme
In the past often a XML-environment is used. ZBNF translates text-files to XML, further processing may be done using XSLT.
For the XSLT translation SAXON is recommended. But it is not part of the zbnfjax folder. The user, who want to use the XML-processing
features should download this parts from its originally internet pages.
For dayly working with ZBNF only the zbnfjax-folder is 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...
XSL-Scripts, ZBNF-Scripts. Batches and the Zmake.jar for Zmake, the standard Zmake-System is supplied here.
XSL-Scripts, ZBNF-Scripts, Batches and the Xslt.jar for XML-Documentation-Generation.
XSL-Scripts, ZBNF-Scripts, Batches for conversion to XMI from Headerfiles and Java-Files. The XMI-File presents an UML-Model and it can be inputted to any UML-Tool.
Xslt.jar for free XSL-Translation using mulitple inputs and Wikiformat-Conversion.
6.4.2 Which other tools and sources are needed ?
Topic:.readme_ZBNF.content...
The XSLT-translation uses the SAXON-XSLT. The zbnfjax is tested with the last version of Saxon-B, available under http://saxon.sourceforge.net in chapter Older Products as open-source-product. Saxonica has changed its licence conditions. In the past the Saxon-B was open-source, but Saxon-SA
was the commercial product including Xschema and others. The newer versions knows three levels of licence: The open-source
Home Edition, a low-cost Professional Edition and a Enterprise-Edition. The new Home-Edition doesn't support the <saxon:call-template ... instruction, which is used in the Xslt-Scripts. Therefore the last Saxon-B is proper for using zbnfjax in open-source-conditions.
But it is recommended to use the newer Saxon's commercial editions if further support of saxon may be need. See http://www.saxonica.com.
The JDOM-Java-Sources or the jdom.jar, which are available as open source under http://www.jdom.org.
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:
The syntax for the users Input data, as free textual part in the JZcmd script.
Definition of the files which should be read.
Invocation of the parser.
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.
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
A Windows-Batch-file or shell-script, which calls the compiler, linker, translator. Maybe there is a check of presence of
the output files with or without timestamp check to accelerate the making process - prevent translation if the result is present
already.
A make-file for any GNU-maker etc.
An ANT-Make-script.
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:
The Version 1.0 supports only using ANT for the Zmake idea. An proper zbnf file and a centralistic XSLT-script generates an ANT-make file which was executes with
ANT.
But a new approach uses Zmake supports the generation of make execution files in any form. Producing of an ANT file is not used yet in examples but it
should be work too. On the other hand a JZcmd-script can execute the make process directly.
A new tool CheckDeps combined with the new Zmake helps to decide whether a translation process should be run or not. This basic capability of
any maker (ANT or classic) is supported with them, but in a more universal approach. Not only the comparison older/newer time
stamp but comparison of the time stamp of the source with a list of the last translation time, and also the comparison of
content decides the necessity of translation. This tool works fine in praxis since 3 years.
ZBNF-Syntax: supports <* |endstring?semantic>: The parse result is trimmed without leading and trailing white spaces.
Parser: Now stores instances of XmlNodeSimple for the parse result, able to use for text generation immediately. Calling of
getResultTree()} returns this representation.
7.2 Changes zbnfjax
Topic:.readme_ZBNF...
From 1.0 to 1.1
The text generation was introduced. New file zbnfjax/xsl/ZmakeGenctrl.zbnf But this is the older version, use the new one!
The BugsAndFeatures directory is moved outside of zbnfjax
From 1.1 to 1.2
The text generation was improved and changed substantially. The text generation is mutated to an execution script. It is JZcmd.
Zmake was improved from only ANT support to a generally approach (see Zmake). The CheckDeps was created:
XmlDocu_Xsl
* AsciiTopics.zbnf supports more attributes for chapters additional to ident: date, obsolete, class. This attributes are read from the textual input text and provided in the XML representation of the text. It can be used
in special scripts.
* DocuGenCtrl2Ant.xslp: capability to generate from StateMachine description.
* Pre2Word.xsl: Minor change of handling size of an image.
* Pre2Xhtml.xsl: Some experience with generate-id().
* TopixXhtml.xsl: Some experience with inset
* XmiDocu.xslp: Some changes in apearance.
batch_template
* setZBNFJAX_HOME.bat: better divided in a part which should be adapted by user and a part which checks and prepares.
