コミット: 0a19ae72ffee29f969aa58f518b813a2b8b17a3c - DocIdeas (hg)

コミットメタ情報

• リビジョン: 0a19ae72ffee29f969aa58f518b813a2b8b17a3c (tree)
• 日時: 2023-11-09 06:11:16
• 作者: Albert Mietus < albert AT mietus DOT nl >
• コミッター: Albert Mietus < albert AT mietus DOT nl >

ログメッセージ

more AR docs

変更サマリ

• modified: CCastle/DocParts/Design/01.Architecture/01.AIGR_pipeline.rst
• modified: CCastle/DocParts/Design/01.Architecture/AIGR_Transformers.puml
• modified: CCastle/DocParts/Design/01.Architecture/AR_skins.inc
• add: CCastle/DocParts/Design/01.Architecture/AIGR-exampleSieve.puml
• delete: CCastle/DocParts/Design/50.notes/231009a_TD-AIGR_3protocols.rst

差分

diff -r 4a39e9695548 -r 0a19ae72ffee CCastle/DocParts/Design/01.Architecture/01.AIGR_pipeline.rst
--- a/CCastle/DocParts/Design/01.Architecture/01.AIGR_pipeline.rst	Wed Nov 08 16:17:52 2023 +0100
+++ b/CCastle/DocParts/Design/01.Architecture/01.AIGR_pipeline.rst	Wed Nov 08 22:11:16 2023 +0100
@@ -28,7 +28,7 @@
 |BR|
 Alternatively, each component can be a process, where te several processes communicate with e.g. unix-pipes, or
 network-connections). And there are many more option, not only separated in space, but also in time: As the AIGR can be
-serialised [#pickle]_, it is possible to save it in file, and read it for the next component, later ... 
+serialised [#pickle]_, it is possible to save it in file, and read it for the next component, later ...
 
 .. Important:: Although it is possible to saving a (pickled) AIGR, that component (nor action) is **NOT** a `Writer`!
 
@@ -67,10 +67,10 @@
 
 .. uml:: AIGR_Transformers.puml
    :align: right
+   :scale: 50%
 
 FSM
 ---
-
 In Castle, one can directly describe a FSM (see: :ref:`FSMs-are-needed`) including advance/extended variants. Like
 the non-deterministic “NFA”s, and the “State-Charts” (known from UML), with orthogonale regions and hierarchically
 ‘superstates’. See :need:`U_FSM_Syntax` for the demands.
@@ -104,7 +104,7 @@
 the receiving event-handler expect a traditional call, will not work. By choosing one Machinery-Transformer, all
 bolt-and nuts will fit.
 
-.. caution:: This is not an requirement
+.. caution:: This is **not** an requirement!
 
    One can imagine, that (eventually) a Mixed-Machinery is used. Ultimately, only the details of each (individual)
    connection should be aligned.
@@ -163,11 +163,49 @@
 
 .. _AIGR_component:
 
+The AIGR auxiliary component
+============================
+
+The `AIGR` *auxiliary* component describes & handles the ‘:ref:`AIGR`’ and is used by all regulair components. Sometimes
+it (the `AIGR`) is called an `“intermediate language” (‘IM’), or “intermediate representation” (‘IR’)
+<https://en.wikipedia.org/wiki/Intermediate_representation>`__.  Many existing IMs are quite “flat”, low-level and very
+operational, like `RTL <https://en.wikipedia.org/wiki/Register_transfer_language>`__ or `SSA
+<https://en.wikipedia.org/wiki/Static_single-assignment_form>`__ -- they are great to convert code to assembly.
 
 
-The AIGR auxiliary component
-============================
-ToDo
+
+.. uml:: AIGR-exampleSieve.puml
+   :align: right
+   :scale: 70%
+   :caption: The *Sieve Protocols*, as example of a AIGR (part)
+
+For the *CCastle Workshop Tools*, a more abstract representation is chosen, with more structure. Visually, it resembles
+a tree, but without the need to have a single root (making it a “forest”), and with interconnects (making it a
+graph). Structurally, it is not dissimular to the XLM/DOM, known by many webpages; but again without the “single
+document-root” -- the DOM has interconnects, known as “links” (a term not used in the AIGR).
+|BR|
+The AIGR reminds also to the AST (of CCastle), after all, each language construct is “stored” in the AIGR. Some see it as a
+semantically parsed AST. A namedID (like a variable, or function) in the source, when in the same namespace denotes the
+same artifact -- even it is mention at several places (and can have aliases). In the AIGR it is the same ‘node’ having
+multiple incoming ‘edges’ -- and so, violates the tree’s non-cycle rule.
+
+The AIGR-component describes all possible elements, and the relations (so it is a bit like the XML `DTD
+<https://en.wikipedia.org/wiki/Document_type_definition>`__ or `Schema
+<https://en.wikipedia.org/wiki/XML_schema>`__). And has (will have) general routines to facilitate handling the AIGR.
+|BR|
+By example, you can expect routines to “save” an AIGR to file, and “load” is later.
+
+.. warning:: Although the AIGR is a graph, the AIGR-component will **not** be able to visualize that graph.
+
+   Other workshop tools may do that, and probably use the AIGR-component to read it. The visualising is part of that
+   tool
+
+
+Currently, the AIGR is in the design phase, and may change.
+|BR|
+For that reason, only a Python dataclass reference model is available (Work-in-Progress). The (unit & behaviour) tests
+and TesDoubles make it quite understandable. Once, it will be fully documented (and versioned) And available for
+multiple languages (including Castle :-)
 
 
 

diff -r 4a39e9695548 -r 0a19ae72ffee CCastle/DocParts/Design/01.Architecture/AIGR-exampleSieve.puml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CCastle/DocParts/Design/01.Architecture/AIGR-exampleSieve.puml	Wed Nov 08 22:11:16 2023 +0100
@@ -0,0 +1,40 @@
+@startuml
+!include AR_skins.inc
+
+folder "AIGR example" #c0c0c0 {
+object StartSieve <<EventProtocol>>
+object runTo <<Event>>{
+    max: int
+}
+object newMax <<Event>> {
+    max: int
+}
+ StartSieve *-- runTo
+ StartSieve *-- newMax
+
+
+object SlowStart << EventProtocol>>
+object queue_max <<TypedParameter>> {
+    :int
+}
+object setMax <<Event>> {
+    setMax :int
+}
+ SlowStart *-- setMax
+ SlowStart *- queue_max
+
+object "SlowStart(1)" as SlowStart_1 <<ProtocolWrapper>> {
+    queue_max=1
+}
+ SlowStart <-- SlowStart_1: based on
+
+
+object SimpleSieve <<EventProtocol>>
+ SlowStart_1 <-- SimpleSieve: based_on
+
+object input <<Event>> {
+    try :int
+}
+ SimpleSieve *--input
+}
+@enduml

diff -r 4a39e9695548 -r 0a19ae72ffee CCastle/DocParts/Design/01.Architecture/AIGR_Transformers.puml
--- a/CCastle/DocParts/Design/01.Architecture/AIGR_Transformers.puml	Wed Nov 08 16:17:52 2023 +0100
+++ b/CCastle/DocParts/Design/01.Architecture/AIGR_Transformers.puml	Wed Nov 08 22:11:16 2023 +0100
@@ -1,8 +1,8 @@
 @startuml
 skin rose
-'!include AR_skins.inc
+!include AR_skins.inc
 left to right direction
-scale 0.5
+
 
 ''NOTE: Old RTD/plantuml.1.2020.2.jar syntax!
 

diff -r 4a39e9695548 -r 0a19ae72ffee CCastle/DocParts/Design/01.Architecture/AR_skins.inc
--- a/CCastle/DocParts/Design/01.Architecture/AR_skins.inc	Wed Nov 08 16:17:52 2023 +0100
+++ b/CCastle/DocParts/Design/01.Architecture/AR_skins.inc	Wed Nov 08 22:11:16 2023 +0100
@@ -27,3 +27,9 @@
     BorderColor #000066
     BackgroundColor #eeeeff
 }
+
+skinparam object {
+    BorderColor #000066
+    BackgroundColor white
+    FontColor #000066
+}

diff -r 4a39e9695548 -r 0a19ae72ffee CCastle/DocParts/Design/50.notes/231009a_TD-AIGR_3protocols.rst
--- a/CCastle/DocParts/Design/50.notes/231009a_TD-AIGR_3protocols.rst	Wed Nov 08 16:17:52 2023 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,50 +0,0 @@
-.. -*- plantuml -*-
-
-TestDoubles/AIGR: The protocols of the Sieve
-============================================
-
-.. uml::
-
-   @startuml
-
-   object StartSieve <<EventProtocol>>
-   object runTo <<Event>>{
-    max: int
-   }
-   object newMax <<Event>> {
-     max: int
-   }
-   StartSieve *-- runTo
-   StartSieve *-- newMax
-
-   '---
-
-   object SlowStart << EventProtocol>>
-   object queue_max <<TypedParameter>> {
-       :int
-    }
-   object setMax <<Event>> {
-     setMax :int
-   }
-   SlowStart *-- setMax
-   SlowStart *- queue_max
-
-   '---
-
-   object "SlowStart(1)" as SlowStart_1 <<ProtocolWrapper>> {
-   queue_max=1
-   }
-   SlowStart <-- SlowStart_1: based on
-
-
-   '---
-
-   object SimpleSieve <<EventProtocol>>
-   SlowStart_1 <-- SimpleSieve: based_on
-
-   object input <<Event>> {
-     try :int
-   }
-   SimpleSieve *--input
-
-   @enduml