Document for TL development for high-level user

[TomyYamy]

We need to consider Paser Lexser side usability around ANTLR and python wrapper.

We agreed the tool architecture is well supports this use-case as much as possible.

Probably, problem is explanation. we will provide several sample ceases.

1. add new operation to online-STL in python

2. How to make C++ wrapper At first prototype, in python is enough. It is for when developer needs a faster code.

3. Build a completly new language. Propbably a simple language is good.

[TomyYamy]

I can work for it while working for issue #28

[TomyYamy]

It think now here we can discuss only document for that.
I'm working for it in doc4TLimp branch.

[TomyYamy]

@nickovic
Could you commit your draft of doc4TLimp?
Just I would like to read to I can revise it.

[TomyYamy]

@nickovic
I think the progress is very nice. I pushed small things. Once I will share it to Jyo's lab.

[TomyYamy]

@nickovic I'm trying it. I did not understand what the difference between /node and /operation. We can write explanation.

[TomyYamy]

@nickovic
Do yout think the warning is problem?

$ antlr4 StlParser.g4 -Dlanguage=Python3 -no-listener -visitor -o ../../parser/stl_ab/ 
warning(109): /mnt/data/repos/rtamt/rtamt/grammar/tl/LtlParser.g4:3:0: options ignored in imported grammar LtlParser

[TomyYamy]

@nickovic
I think in last section, we can explain not only specification_parser.py, but also specification.py too.
I know it is now under construction.

[TomyYamy]

I think my question is difference or functionality between,
/spec, /node, /operation, /evaluator...
I can clarify while leading the code.

[TomyYamy]

I'm trying to implement somehow different version of dense time offline STL.
It seems to be not distinct where we need to change that.
because the mapping /spec and /node is done in discrete time folder /spec/stl/discrete_time.
It can not change form /spec/stl/dense_time because those are inhering from discrete_time. But it is right way to avoid code duplication and copy as much as possible.

I think problem is I did not understand the architecture 100%. Once we can go thorough the extension then look back again.

[TomyYamy]

I think all of codes are needed and well split. I think we need some restructuring folder structure.

• Visitor(in spec), evaluation, node, operation are confusing.
  I think, some how visitor's instance is evaluation
  and node's instance is operation.
  But user need to copy all of them in different folder.

• Really all operator needs different node class?
  I know we need node. that what I suggested. I think, we need UnnaryNode, BinaryNode and TimeBound. but do we need each Abs, Always,TimedAlways? I feel TimedUniaryNode and Timed BinaryNode is good enough.
  I feel why we can not decide here is we did not implement abstclass for densetime, discretetime. (now operation directly handle it)
  

• Perhaps enumerations, interval can merge into node?
  Perhaps, not node, but somewhere.

[TomyYamy]

Now I understand your /node structure is correct.

[TomyYamy]

@nickovic
I think now I understand your intention of implementation more. Everything is correct.
Once I need to go though current implementation and document. I think potentially we may think,

1. Explain Visitor and AST(node)
   I understand Visitor and AST sturcture.
   Dejan already mentioned /node. But especially tree side is not mentioned so much. we can explain it in addition Node.
   We can explain something like CIL visior
   https://people.eecs.berkeley.edu/~necula/cil/api/Cil.cilVisitor.html

2. Relation between visitor->evaluator->operation
   Everything is based on visitor class.
   Visitor class: parents. pastify() is included in here.
   Evaluator class (inherits Visitor): it handling offline or online evaluation sofar.
   Operation class (inherits Evaluator): Here we can implement semantic. So far we did not have any abstract class for Dense and Discrete time.
   Perhaps we can call them all visitor, like visitor->offlineVisitor->STLdenseTimeVisitor or something. because even designer knows "visitor" there is missing link between visitor and final evaluator.

3. The location of /enumerations, /interval,
   I feel perhaps in /operation

4. The location of /exception
   perhaps internal of /spec. maybe problem is which is good ordering
   -> or ->
   If many user can copy and paste original code, we can follow the last option.

[TomyYamy]

@nickovic
I know naming change and folder relocation, we need to do those very carefully. The good thing is you are holding test case and fixed application layer API.
I think what good use-cases to cover are,

1. only change semantics without any syntax change.
   It is the first step, and I'm doing.
2. extend a few operator to STL.
   It needs both of syntax and semantics change. you are doing right now.
3. STQL
   It has many extensions but is very practical for RTAMT.

[TomyYamy]

Let me update the expected use-case a bit.
I think so far, we need to look back coding itself.

1. only change semantics without any syntax change.
   It is the first step, and I'm doing. I think I copy the code too much. If I can understand the current architecture correctly, I don't need to copy a lot.

2. extend a few operator to existed TL (like STL).
   We expect new predicate that is still an extension of binary, unary or time bound.
   I think here difficultly what is covering area of ANTRL AST and our defined AST. Still parser, the designer need to now what he need to here, and what we need to do for to generate our AST too.

3. extend STL fully (like STQL)
   More aggressive extension than 2, like adding "existing" for STQL.

[TomyYamy]

@nickovic Let's drop out 3. first.
We may aim only 1. and 2. in this refactoring.

[TomyYamy]

@nickovic
Do you think IA-STL is good for explain RTAMT library, especially use-case 1? because it does not change syntax.
I did not come up with good example for use-case 2. Perhaps we may think add algebraic expression?

[TomyYamy]

We are writing it in syntax-extension-tutorial branch.