<commit_before>= Import ASL Activity

xtUML Project Implementation Note

== 1 Abstract

This note documents the importing of ASL actions.

== 2 Introduction and Background

`MASL dumper` is being employed to export ASL-dialect models from iUML.
MASL dumper will put the ASL activities into separate files as if they
were MASL activities.  This is fine.

However, MASL activities have a MASL activity signature (parameters and
return type) imbedded in the activity file.  ASL does not, and even if it
did, the signature would have a different syntax.  MASL uses an explicit
begin-null-end sequence for "empty" activities.  ASL simply has zero
statements in empty activities.

In addition, ASL activities are to be persisted in BridgePoint differently
than their MASL counterparts (and similarly to their OAL counterparts).
ASL will be persisted in the 'Action_Semantics' field of the metamodel
class representing the function or operation.  MASL activities are
persisted into a file within the current package and having a suffix of
'.masl'.

These differences were not fully considered when the decision was made to
employ the MASL dumper with ASL-dialect models.  The following sections
outline requirements and required work to extend the Import side of
BridgePoint to support ASL-dialect activity import.

== 3 Requirements

=== 3.1 Recognize ASL activities as distinct from MASL

It may be theoretically possible to detect ASL in activity bodies by
syntax.  However, this would require the construction of a separate lexer
/ parser / recognizer, which is significant work.  Instead, the import
process will be given a flag to indicate that ASL is the dialect of
activity being imported.  The import process starts at `masl2xtuml`.
Therefore, this script will gain a command line specification to indicate
ASL.

==== 3.1.1 Distinguish ASL During Parse

`masl2xtuml` will pass the dialect / architecture specification to the
MASL file parser.  This will give the parser the information it needs to
parse the activity bodies differently than MASL.  Thus, `MASLImportParser`
will receive the dialect specification.

==== 3.1.2 Distinguish ASL During Conversion

The `m2x` utility will also need to know that ASL activities are being
processed.  `masl2xtuml` will pass the flag to this conversion processor
as well.

==== 3.1.2 Distinguish ASL During Import

The output of `masl2xtuml` is a legal `.xtuml` file that can be imported
into BridgePoint.  Converted MASL models have labels imbedded inside that
provide hints to the BridgePoint import process to set MASL-specific
parameters for the model.  A similar approach will be taken for
ASL-dialect converted models.

=== 3.2 Clean Up Extraneous MASL

`MASL dumper` includes the function or operation signature in the first
lines of an activity.  This is superfluous and incorrect syntax for ASL
activities.  The MASL dumper also emits a "begin, null, end" sequence
for empty activities which is not useful for ASL.

==== 3.2.1 'Grep out' the MASL Function Signature

Remove the MASL-style signatures from the beginning of the activity
including the boilerplate comment block ("UK Crown").

Recognize that the function signatures are required to identify the
activity body.  So, they must be removed only after they have been parsed
and used to link the activity body with the activity declaration.

==== 3.2.2 'Grep out' begin-null-end

Remove MASL `begin`, `null` and `end` statements that have been inserted
by the MASL dumper.

=== 3.3 Stow Activity Code Block in 'Action_Semantics'

ASL activities will be persisted into the converted '.xtuml' file in
mostly the same way as MASL.  However, upon import into BridgePoint, these
activities will be persisted in the 'Action_Semantic' field of the
containing activity element.  It is required that ASL pass through the
MASL activity parser even though ASL does not follow legal MASL syntax.

==== 3.3.1 Extend Code Block Parser

Extend the MASL grammar at the 'codeBlock' production rule to accept a
block of ASL delimited with tags.  The strategy will be to use a grammar
rule similar to that of multi-line comments.  The tags will be something
like '#ASL-BEGIN' and '#ASL-END'.  ASL comments begin with '#' so that
these tags could be left in the stream.  However, it is most desirable to
strip them out after they have performed their function.

==== 3.3.2 Create Separate ASL Activity Grammar

==== 3.3.1 Insert Tags into ASL Bodies

Insert the tags while loading the ASL activity file and before passing the
stream to the parser.  This can be done by simple substitution detecting
' is' at the end of the function signature and inserting the begin tag
directly afterwards.

The end tag will be concatenated onto the end of the entire activity.

==== 3.3.1 Remove Tags and begin-null-end from ASL Bodies

After the parse is complete and before emitting the serial MASL, simple
substitution can be employed to remove the ASL begin and end tags and omit
the begin-null-end patterns.

=== 3.4 Set Action Dialect to ASL

Upon import into BridgePoint, the dialect for ASL bodies will be set to
ASL.

=== 3.5 Label Model

MASL models are imported with special tags 'masl_project' and 'masl_domain'
in particular model element locations.  This is done to provide a key to
the BridgePoint model import funcitionality.  During import, BridgePoint
detects these keys and performs dialect-specific operations for MASL.

ASL dialect models will need to use a similar approach with different keys.

==== 3.5.1 Add 'asl_project' and 'asl_domain' to `m2x`

Based upon command line input, the `m2x` conversion utility will imbed
the label 'asl_project' and 'asl_domain' in the same locations where it
currently imbeds 'masl_project' and 'masl_domain' for MASL models.

==== 3.5.2 Detect 'asl_project' and 'asl_domain' in Import

During normal xtUML model import processing, BridgePoint will detect the
labels 'asl_project' and 'asl_domain' labels.  Appropriate steps will be
taken to set the 'ActionDialect' enumeration for the imported activities.

== 4 Work Required

The work required is outlined in the requirements above.

An option using '-a <architecture>' (-a to be consistent with a similar
argument on the back end export tool chain) is added to:
* `masl2xtuml`
* `MASLImportParser`
* `x2m`

== 5 Implementation Comments

== 6 Unit Test

. `round_trip` testing of the MASL test suite shall continue to pass.
. `round_trip` importing of SWATS models will execute successfully.

== 7 User Documentation

The command line option must be added to the "man page" documentation of
`masl2xtuml`.

== 8 Code Changes

- fork/repository:  cortlandstarrett/bridgepoint
- branch:  11380_asl_import

----
 Put the file list here
----

- fork/repository:  cortlandstarrett/mc
- branch:  11380_asl_import<commit_msg>job:  #11380  added alternatives section<commit_after>= Import ASL Activity

xtUML Project Implementation Note

== 1 Abstract

This note documents the importing of ASL actions.

== 2 Introduction and Background

`MASL dumper` is being employed to export ASL-dialect models from iUML.
MASL dumper will put the ASL activities into separate files as if they
were MASL activities.  This is fine.

However, MASL activities have a MASL activity signature (parameters and
return type) embedded in the activity file.  ASL does not, and even if it
did, the signature would have a different syntax.  MASL uses an explicit
begin-null-end sequence for "empty" activities.  ASL simply has zero
statements in empty activities.

In addition, ASL activities are to be persisted in BridgePoint differently
than their MASL counterparts (and similarly to their OAL counterparts).
ASL will be persisted in the 'Action_Semantics' field of the metamodel
class representing the function or operation.  MASL activities are
persisted into a file within the current package and having a suffix of
'.masl'.

These differences were not fully considered when the decision was made to
employ the MASL dumper with ASL-dialect models.  The following sections
outline requirements and required work to extend the Import side of
BridgePoint to support ASL-dialect activity import.

== 3 Requirements

=== 3.1 Recognize ASL activities as distinct from MASL

It may be theoretically possible to detect ASL in activity bodies by
syntax.  However, this would require the construction of a separate lexer
/ parser / recognizer, which is significant work.  Instead, the import
process will be given a flag to indicate that ASL is the dialect of
activity being imported.  The import process starts at `masl2xtuml`.
Therefore, this script will gain a command line specification to indicate
ASL.

==== 3.1.1 Distinguish ASL During Parse

`masl2xtuml` will pass the dialect / architecture specification to the
MASL file parser.  This will give the parser the information it needs to
parse the activity bodies differently than MASL.  Thus, `MASLImportParser`
will receive the dialect specification.

==== 3.1.2 Distinguish ASL During Conversion

The `m2x` utility will also need to know that ASL activities are being
processed.  `masl2xtuml` will pass the flag to this conversion processor
as well.

==== 3.1.2 Distinguish ASL During Import

The output of `masl2xtuml` is a legal `.xtuml` file that can be imported
into BridgePoint.  Converted MASL models have labels embedded inside that
provide hints to the BridgePoint import process to set MASL-specific
parameters for the model.  A similar approach will be taken for
ASL-dialect converted models.

=== 3.2 Clean Up Extraneous MASL

`MASL dumper` includes the function or operation signature in the first
lines of an activity.  This is superfluous and incorrect syntax for ASL
activities.  The MASL dumper also emits a "begin, null, end" sequence
for empty activities which is not useful for ASL.

Notem however, that the signature actually serves as the key for the
activity.  It cannot be completely omitted from processing.

==== 3.2.1 'Grep out' the MASL Function Signature

Remove the MASL-style signatures from the beginning of the activity
including the boilerplate comment block ("UK Crown").

Recognize that the function signatures are required to identify the
activity body.  So, they must be removed only after they have been parsed
and used to link the activity body with the activity declaration.

==== 3.2.2 'Grep out' begin-null-end

Remove MASL `begin`, `null` and `end` statements that have been inserted
by the MASL dumper.

=== 3.3 Stow Activity Code Block in 'Action_Semantics'

ASL activities will be persisted into the converted '.xtuml' file in
mostly the same way as MASL.  However, upon import into BridgePoint, these
activities will be persisted in the 'Action_Semantic' field of the
containing activity element.  It is required that ASL pass through the
MASL activity parser even though ASL does not follow legal MASL syntax.

==== 3.3.1 Extend Code Block Parser

Extend the MASL grammar at the 'codeBlock' production rule to accept a
block of ASL delimited with tags.  The strategy will be to use a grammar
rule similar to that of multi-line comments.  The tags will be something
like '#ASL-BEGIN' and '#ASL-END'.  ASL comments begin with '#' so that
these tags could be left in the stream.  However, it is most desirable to
strip them out after they have performed their function.

==== 3.3.2 Create Separate ASL Activity Grammar

==== 3.3.1 Insert Tags into ASL Bodies

Insert the tags while loading the ASL activity file and before passing the
stream to the parser.  This can be done by simple substitution detecting
' is' at the end of the function signature and inserting the begin tag
directly afterwards.

The end tag will be concatenated onto the end of the entire activity.

==== 3.3.1 Remove Tags and begin-null-end from ASL Bodies

After the parse is complete and before emitting the serial MASL, simple
substitution can be employed to remove the ASL begin and end tags and omit
the begin-null-end patterns.

=== 3.4 Set Action Dialect to ASL

Upon import into BridgePoint, the dialect for ASL bodies will be set to
ASL.

=== 3.5 Label Model

MASL models are imported with special tags 'masl_project' and 'masl_domain'
in particular model element locations.  This is done to provide a key to
the BridgePoint model import functionality.  During import, BridgePoint
detects these keys and performs dialect-specific operations for MASL.

ASL dialect models will need to use a similar approach with different keys.

==== 3.5.1 Add 'asl_project' and 'asl_domain' to `m2x`

Based upon command line input, the `m2x` conversion utility will embed
the label 'asl_project' and 'asl_domain' in the same locations where it
currently embeds 'masl_project' and 'masl_domain' for MASL models.

==== 3.5.2 Detect 'asl_project' and 'asl_domain' in Import

During normal xtUML model import processing, BridgePoint will detect the
labels 'asl_project' and 'asl_domain' labels.  Appropriate steps will be
taken to set the 'ActionDialect' enumeration for the imported activities.

== 4 Work Required

The work required is outlined in the requirements above.

An option using '-a <architecture>' (-a to be consistent with a similar
argument on the back end export tool chain) is added to:
* `masl2xtuml`
* `MASLImportParser`
* `x2m`

== 5 Implementation Comments

=== 5.1 Alternatives

Alternatives were explored to accomplish this work.  Here is a summary list.

=== 5.1.1 Override Parser Recovery

The idea here is that ASL activities will cause parse errors in the MASL
activity parser.  The detection and reaction to these could be changed.
`antlr` provides mechanisms to override the error detection and recovery
operations.  These could be changed to "eat until the end of the file".

This was explored and found to be non-trivial.  It also provides no advantage
of the approach chosen.

=== 5.1.2 Pre-Process (`sed/grep/awk`) Activity Files

The ASL bodies could be extracted from the activity files before running
the parser.  Or, the operation signatures and begin-null-end strings could
be stripped from the activity files.  This leaves the problem that the
signature actually serves as the key for the activity.

The fact that both the MASL and ASL in the file is needed renders this
approach less than ideal.

=== 5.1.3 Create a New Parser for ASL

A parser could be created that understands ASL.  It could be invoked from
within the MASL parser.

This is simply a much larger amount of work than other approaches.

=== 5.1.4 Adapt MASL Parser

This is approach chosen.  The MASL parser will be given a single new rule
that parses ASL between two tags inserted around the action statements.
It is a small change to the parser and allows both the MASL portions and
the ASL portions of the files to be processed correctly.

== 6 Unit Test

. `round_trip` testing of the MASL test suite shall continue to pass.
. `round_trip` importing of SWATS models will execute successfully.

== 7 User Documentation

The command line option must be added to the "man page" documentation of
`masl2xtuml`.

== 8 Code Changes

- fork/repository:  cortlandstarrett/bridgepoint
- branch:  11380_asl_import

----
 Put the file list here
----

- fork/repository:  cortlandstarrett/mc
- branch:  11380_asl_import
{'fraction_non_alphanumeric': 0.049908064092461256, 'fraction_numerical': 0.010572629366955608, 'mean_word_length': 4.343508771929825, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4660985', 'n_tokens_mistral': 4286, 'n_tokens_neox': 4045, 'n_words': 2276}