# Express Compiler

> Compiles EXPRESS schemas into java packages and proprietary binary files with dictionary data

## SYNOPSIS

>     java [java switches] jsdai.expressCompiler.Main [switches]

## Description. Input and output data

> The express compiler compiles files with EXPRESS (ISO 10303-11) schemas into java packages and proprietary binary files with dictionary information, that is necessary for JSDAI applications to work with data based on these EXPRESS schemas.
> For each express schema with the name some_express_schema the following output is created:
> - Java package jsdai.SSome_express_schema. It contains java interfaces and classes corresponding to express entities, types, etc.
> - The corresponding sdai model in ExpressCompilerRepo repository. Physically it is exported into a proprietary binary file with the name mx (where x is one- or multi-digit number) in the ExpressCompilerRepo repository location as specified in jsdai.properties file, and in jsdai.SSome_express_schema java package with the name SOME_EXPRESS_SCHEMA_DICTIONARY_DATA.
> For each express file with the name some_express_file.some_extension, that may contain more than one express schema, the following output is created:
> - Schema Instance some_express_file_INSTANCE containing sdai models of all the express schemas in the file. It is stored in ExpressCompilerRepo repository.
> One additional schema instance ExpressCompilerRepo_INSTANCE is also created that contains all the sdai models in ExpressCompilerRepo repository.

> Each time the express compiler is run, ExpressCompilerRepo_INSTANCE schema instance is updated.
> Each time the compiler is run with -express switch (i.e., compiling an express file, see below the description of the express compiler switches), the corresponding schema instance is also updated.

> ### Input data

> ### 1.

> The ExpressCompilerRepo repository containing at least the dictionary models of sdai_dictionary_schema and sdai_mapping_schema. The ExpressCompilerRepo repository is necesarry data for the express compiler to run, it may also be at the same time the output data as additional sdai models may be created in it by the express compiler. It also may be an input data as the models that are already present in it may be processed even without parsing new files with express schemas. The location of the ExpressCompilerRepo repository must be specified in jsdai.properties file provided for the express compiler.

> ### 2.

> A file that contains all the express schemas interfacing each other that have to be compiled, i.e., all express schemas in short form relationship have to be present in a single file. Each long form express schema or each set of short form express schemas have to be in a separate file and is compiled by the express compiler separately although the same ExpressCompilerRepo repository may be used. The path/name of the files with the express schema(s) is provided after the command line switch -express. See the description of the command line switches. This input data is the main data, but it is still optional. The express compiler can perform some operations on already existing dictionary sdai models in ExpressCompilerRepo repository without parsing any new files with express schemas. See the description of the command line switches.

> ### 3.

> A file that contains the list of all complex entities that have to be generated for the schema(s) that are compiled. Its path/name is provided after the command line switch -complex. See the express compiler switches. The same file with complex entities may be used for different long form schemas and/or different sets of short form schemas if so desired, see the description of the format and the syntax of the list of complex entities. A simpler approach is to use separate files with the list of the complex entities for each long form schema and/or each set of short form express schemas to be compiled. The -complex switch with the list of the complex entities is optional. It is used only when complex entities are needed.

> ### 4.

> A directory with files that contain short name information for entities in express schemas. Each express schema must have the corresponding file with the same name as the name of the express schema and with .SN extension in this directory. Such a file must contain a comma separated list: long_name,short_name - one line = one entity. The short names are generated if -short_names switch is used, see the description of the command line switches. A directory with the name SHORT_NAMES is used for that purpose and is assumed to be a subdirectory in the current directory where the express compiler is run, unless a different directory for short names is specified with -short_name_dir switch. See the description of the command line switches.

> ### Output data

> ### 1.

> A java package is generated for each express schema compiled by the express compiler. In the case of short form schemas, more than one java package is generated for a files compiled by the express compiler. The java packages are created if -java commmand line switch is present, see the description of the command line switches. All the java packages are created in their own subdirectories with corresponding names, see above. All the subdirectories for java packages are created inside jsdai subdirectory in the current directory where the express compiler is run. If the generated java packages are to be compiled in that location, the java CLASSPATH has to include the current directory in which the express compiler is run, represented either by an explicit path or by a dot (".") symbol. The java package can also contain the corresponding binary file with the dictionary sdai model data for that schema if -binaries command line switch is used. See the description of the command line switches. Usually better to run the express compiler with -binaries switch as the binary file is needed to be present in each generated java package if that package is to be used in jsdai applications.

> ### 2.

> An sdai model with dictionary data is created in ExpressCompilerRepo repository for each compiled express schema. Also schema instances are updated and/or created in ExpressCompilerRepo repository as necessary.

> ### 3.

> The contents of the ExpressCompilerRepo repository may be exported to a file in ISO 10303-21 format if -p21 command line switch is used together with the file name. See the descrition of the command line switches. This file is created is the current directory where the express compiler is run.

> ### 4.

> Batch files for compiling of the generated java packages and for making jars can be generated by the express compiler, see the description of the command line switches. These batch files are created in the current directory where the express compiler is run.

> IMPORTANT! The express compiler is JSDAI application itself.
> For the express compiler to run, SExtended_dictionary_schema java package with classes and the binary has to be available on the CLASSPATH. So the jsdai_lib.jar library has to be installed. Also jsdai.properties file has to be present.

> ## The Express Compiler Command Line Switches

> > All express compiler command line switches are optional and can be written in any order.

> > `-express` express_file
> > `-e` express_file
> >   The express file, must contain one or more express schemas, in case of short form schemas interconnected by interface specifications, all these schemas must be present in one file. If this switch is present, only schemas present in the specified file are processed by the express compiler backends. If this switch is absent, no file is parsed, but all schemas (all sdai models in ExpressCompilerRepo repository) are processed by all the backends that are switched on by corresponding switches.

> > `-files` list_file
> > `-f` list_file
> >   Alternative to -express, but may be used together. Allows to provide a list of express files. Does not require merging of all the express files into one file. When reporting errors, the express file names are indicated as well if more than one file is specified. The names of the express files should be on separate lines, although other delimeters also work. # at the beginning of a line comments the whole line out, could be used to write comments or to remove some express files from the list temporarily.

> > `-directory` directory_path [exclude_list]
> > `-dir` directory_path [exclude_list]
> >   Alternative to -express or to -files, but may be used together. If used, the compiler compiles all the express files in the specified directory. Optional file with the list of the express files to be excluded can be excluded. If this exclusion file name is not provided, the default file name is "_exclude", it is used if present.

> > `-recurse` directory_path [exclude_list]
> > `-dr` directory_path [exclude_list]
> >   Similar to -directory, but the directories are recursed, i.e., the express files are also taken from all the subdirectories. The exclusion file in addition to the names of express files may also contain the names of subdirectories to be excluded. The exclusion file is used only at the top directory level. A global exclusion file can also be used with a special -exclude switch.

> > `-exclude` exclude_list [exclude_list]
> > `-ex` exclude_list [exclude_list]
> >   Provides the file with the global list of exclusions, the express files in the list will not be compiled. Directories also can be included in the exclussion list. Absolute directory path may have to be used, depending on the location of the file with the exclusion list itself.

> > `-complex` complex_file
> > `-c` complex_file
> >   The complex generator is invoked. It creates complex entities (definitions and declarations) according to the specified file that contains the list of complex entities. If -express switch is present, the complex generator processes the sdai models of the schemas present in the file, if -express switch is absent, the complex generator processes all the models in ExpressCompilerRepo repository.

> > `-short_names`
> > `-s`
> >   The short name generator is invoked. It adds short names to entity definitions in some or all ExpressCompilerRepo sdai models. If -express switch is present, only sdai models of the express schemas present in the specified file are processed. If this switch is absent, all the sdai models in ExpressCompilerRepo are processed.

> > `-short_name_dir` short_name_directory
> > `-sd` short_name_directory
> >   This switch allows to specify the directory that contains the files with short name information. If absent, the subdirectory SHORT_NAMES of the current directory is assumed.

> > `-java`
> > `-j`
> >   Java backend is invoked. It generates java packages of all schemas in the file specified by -express switch. If -express switch is absent, java packages are generated for all sdai models in ExpressCompilerRepo repository

> > `-p21` physical_file
> > `-p` physical_file
> >   The contents of ExpressCompilerRepo repository is exported to ISO 10303-21 clear text encoded file with the specified name. physical_file

> > `-binaries`
> > `-b`
> >   Inserts corresponding binaries into the directories of generated java packages, only for schemas found in the currently parsed express file. Corresponding binary files from ExpressCompilerRepo repository must be present in java packages for JSDAI to work with these packages. If -express switch is present, only binary files for currently generated sdai models are inserted, if not, binary files are inserted for all sdai models in the ExpressCompilerRepo repository.

> > `-compile` compile_string batch_file [log_file]
> > `-o` compile_string batch_file [log_file]
> >   Generates a batch file to compile the java packages. It requires two mandatory parameters and there also may be the third optional parameter. Parameters:
> >   - compile_string - the string (in double quotes if contains spaces or special symbols) that must include the command line to invoke a java compiler, may also include switches of the java compiler, does not include names of java files to be compiled. Examples:
> >   javac
> >   "C:\winprog\java\symantec\sj -classpath .;C:\winprog\java\java1_1\classes.zip"
> >   - batch_file - the name of the batch file
> >   - log_file - the name of the file to re-direct java compiler messages. This file is appended for each subsequent java package. If not present, the java compiler messages are not logged but rather outputted on the screen. If -express switch is present, the generated batch file contains only the lines to compile the java packages generated for the currently parsed express file. If -express switch is not present, the batch file includes lines to compile all the java packages corresponding to ExpressCompilerRepo repository models.
> >     Examples of the usage of the switch:
> >       -compile javac short_forms.bat short_forms.log
> >       -compile "C:\winprog\java\symantec\sj -classpath .;C:\winprog\java\java1_1\classes.zip" all_packages.bat

> > `-jar` batch_file jar_file add_string [create_string]
> > `-a` batch_file jar_file add_string [create_string]
> >   Generates a batch file to make the jar with the generated library. It requires three mandatory parameters and there also may be the fourth optional parameter. Parameters:
> >   - batch_file - the name of the batch file
> >   - jar_file - the name of the archive file.
> >   - add_string - the string (in double quates if contains spaces or special symbols) that must include the command line to add a file to the jar archive, may include switches of the archivator tool, does not include the name of the archive or the names of files to be added.
> >   - create_string - an optional parameter, similar to the add_string parameter, but holding the string to create the archive. It is needed only if the archivator tool requires a different command line to create new archive than the one used to add files to an already existing archive.
> >   Examples of the usage of the switch to create a batch file to make the jar file with JSDAI library:
> >     -jar make_jar.bat jsdai_lib.jar "jar -uf" "jar -cf"
> >     -jar make_jar.bat jsdai_lib.jar zip

> > `-enable_expressions`
> > `-ee`
> >   Generates java code for evaluation of expressions of derived attributes, local and global rules, functions and procedures

> > `-implicit_select`
> > `-is`
> >   When this switch is used, the rule 1 of ISO 10303-11.11.4.2 is relaxed, implicit declarations are generated for selectable items of interfaced SELECT data types.

> > `-compilation_sn` n
> > `-csn` n
> >   Used to specify compilation sequence number for the compiler. It allows to separate regions of persistent labels in the library modules, thus separate library jars have less chance to interfere. The compilation sequence number parameter is mandatory. Persistent labels of created by compiler instances will be constructed in the following way (bitewise):

> >   63 | 62 | ... | 48 | 47 | ... | 0
> >   sign | compilation sequence number | variable section
> >   always 0 | n | starts from 0

> > `-index_file` [file_name]
> > `-idx` [file_name]
> >   Used to specify the name of the index file (file_name.properties) to be created in jsdai subdirectory. The file_name parameter is optional. If it is not specified then default file_name = "repository" is used. The index file stores information about newly created by compiler schema instances and models.

> > `-verbose`
> > `-v`
> >   Prints more detailed information about the progress of the parser, the complex generator, the short name generator and java generator.

> ## The List-driven Complex Generator. Format and syntax of the list of complex entities

> Each line contains one complex entity.
> It is represented by the names of its leaf entities in alphabetic order and separated by "+" symbol:
>   `length_unit+si_unit`
> Non alphabetic order is also accepted, but not recommended:
>   `si_unit+length_unit`
> Non leaf entities (supertypes) are also accepted, the complex entities are generated, but warnings are printed by the complex generator:
>   `length_unit+named_unit+si_unit`
> The following strategy is used to generate complex entities:
> - If all the leaves are in one schema (entity definitions of all leaves are in one sdai model) then the complex entity is placed in that schema (its entity definition and local declaration is generated in that sdai model).
> - If the leaves are in different schemas (their entity definitions are in different sdai models) then the resulting complex entity is placed in mixed_complex_types schema (MIXED_COMPLEX_TYPES_DICTIONARY_DATA sdai model).
> A complex entity can be used (is visible) in schemas where all its leaves are visible (interfaced declarations of the complex entity are generated in all the sdai models where all the leaves have declarations, and of course, in the model where the complex entity has its definition it also has the local declaration and can be used there).

> There are cases when entities with identical names are present in different schemas.
> If such an entity is a leaf of a complex entity, an ambiguous situation occurs.
> The complex generator has to know, which entity to use as the leaf.
> It is also possible, that more than one complex entity is needed, choosing the ambiguous leaf entity from each schema in turn as its leaf.
> In such a case, when two or more complex entities have to be generated with identical names, they cannot be placed in the same model.
> The obvious solution is to place them into the corresponding models of the leaf entities with the same name.

> There are special syntax extensions to deal with such situations.

> The schema of any leaf entity can be specified.
> For each leaf entity, an optional schema name prefix followed by "." symbol may be given to resolve ambiguity, in case when entities with the same name are present in several schemas:

>   `leaf_1+schema_2.leaf_2`
> The schema where the complex entity must be placed may also be specified.
> For each complex entity, an optional schema name followed by ":" symbol may be given at the beginning of the line.
> It specifies in which schema the complex entity is to be placed:
>   `schema_1:leaf_1+leaf_2`
> Typically, both extensions are used together:
>   `schema_1:schema_2.entity_1+schema_3.entity_2`
> Example:
>   `automotive_design:dimensional_location_with_path+automotive_design.directed_dimensional_location`
>   `electronic_assembly_interconnect_and_packaging_design:dimensional_location_with_path+electronic_assembly_interconnect_and_packaging_design.directed_dimensional_location`
> There are also other ways to control which leaf entity is to be chosen and where the complex entity is to be placed.
> These other ways do not deal with each entity separately but rather establish default schemas in two ways:

> ### 1.

> A default schema may be specified for a section of the complex list file, if a case of an ambiguous leaf entity occurs in the section, the leaf from the default section schema is chosen, if possible, and the complex entity is placed in the default schema, if possible.
> Special symbol "@" followed by an optional schema name establishes such a section.
> "@" symbol without any schema name ends all sections and no default schema is specified further:
>   @ schema_1
>   ...
>   ...
>   @ schema_2
>   ...
>   ...
>   @
>   ...
>   ...
>   @ schema_3
>   ...
>   ...
> If schema prefices are used in a section, the specific leaf or complex entity schema prefix overrides the default section schema.

> ### 2.

> A set of sdai models to be processed can be specified by special directives, the lines with complex entities following the lines with directives are affected by the directives:
>   [ ALL ]
> This directive includes all the models in ExpressCompilerRepo into the set to be processed.
>   [ NONE ]
> This directive excludes all the models from the set to be processed.
>   [ RESTORE ]
> This directive restores the original model set to be processed.
> That set is defined by the schemas in the currently compiled file with express schemas, if -express switch is used. otherwise this set includes all the models in the repository.
>   [ + schema_name ]
> Includes the model of this schema into the set of models to be processed.
> Typically, one or more of such directives follow [ NONE ] directive.
>   [ - schema_name ]
> Excludes the model of this schema from the set of models to be processed.
> Typically, one or more of such directives follow [ ALL ] directive, or may appear just anywhere.

> It is clear that in some cases the ambiguous leaf situations may be avoided by narrowing of the set of the sdai models to be processed.

> ### 3.

> Using separate files with complex entity lists for different files with express schemas may also help to avoid many ambiguous situations:
>   java jsdai.expressCompiler.Main -express file1.exp -complex file1.ce -java -binaries
>   java jsdai.expressCompiler.Main -express file2.exp -complex file2.ce -java -binaries
> Obviously, the effect is that only a subset of all sdai models in the ExpressCompilerRepository is processed by the complex generator.

> ### 4.

> There are special comment, or skip directives:
>   #
> The line is commented out. It is useful to write some explanations, but also to remove a complex entity temporarily, if it is not needed or is causing problems.
>   ^
> All lines until the end of the section (until the next "@" symbol are skipped
>   <
>   ...
>   ...
>   >
> All the lines between "<" and ">" are skipped.

> The comment directive "#" is different from other skip directives:
> "#" is a blind comment, while the other skip directives still perform some syntax check, the lines that are skipped still have to have at least correct syntax.

> Skipping a portion of a file may also be a solotion to resolve some conflicts, for example you can use basicly the same complex list file duplicated for different express schema files, with different portions skipped.
> It is also useful, if a group of complex entities has to be commented out temporarily, but may be needed in the future.

> The following complex list files are provided with the compiler:

> 1. complex entities of the dictionary in dictionary.ce file. Normally, not necessary for the customers that use the provided ExpressCompilerRepo repository.
> 2. short_forms.ce file contains complex entities for the short form AIC, IR, PLIB and AP schemas.
> 3. ap214_arm.ce file contains complex entities needed for AP214 ARM schema.

> Complex entities are not generated in the following cases, but the corresponding warnings are printed:

> 1. If not all leaves are found in the whole set of models to be processed, or in their specified models (overriding).
> 2. If supposed leaves do not have a common root supertype entity - illegal complex entity.
> 3. If the complex entity is already present (if the entity_difinition of a complex entity with the same name is already present in the destination model).
> 4. If not all the leaves have entity declarations in the destination model of the complex entity.