[ANN] Guile-SMC 0.6.2 released

[ANN] Guile-SMC 0.6.2 released

[Artyom V. Poptsov]

[-- Attachment #1: Type: text/plain, Size: 4525 bytes --]

Hello Guilers,

I'm pleased to announce Guile State Machine Compiler (Guile-SMC), version
0.6.2:
  https://github.com/artyom-poptsov/guile-smc/releases/tag/v0.6.2

This release fixes some new-found bugs, namely in the state-machine
profiler.  Also now it's possible to specify "pre-action" and
"post-action" procedures in PlantUML "legend" block.

Please see the list of notable changes below.

Guile-SMC 0.6.2 is backward-compatible with 0.6.0 and 0.6.1.


* What is Guile-SMC?

Guile-SMC is a state machine compiler that allows to describe finite
state machines (FSMs) in Scheme in terms of transition tables.  It is
capable to generate such transition tables from a PlantUML state
diagrams. [1]

Some of the key features:
- A transition table can be verified and checked for dead-ends and
  infinite loops.
- Guile-SMC FSMs gather statistics when they run (steps/transitions);
  the statistics can be used can be used to compare/analyze FSMs..
- There's an FSM profiler that runs on FSMs trace logs.  The profiler
  output shows how much time the FSM spends in each state.  This can be
  useful for optimization.
- The state machine compiler supports three "targets" for compilation: a
  regular "guile" target where the output FSM depends on Guile-SMC;
  "guile-standalone" target that produce an FSM that does not depend on
  Guile-SMC.
- Guile-SMC allows to run a FSM on-the-fly with a single "smc run"
  command -- see the docs and the examples for more information.
- Common context code for parsers that work with characters or bytes.
  This includes special data structures to provide memory for FSMs
  (although it is not required to use them; FSMs can use custom
  procedures and data structures.)

Guile-SMC comes with a Scheme program called 'smc' -- a state machine
compiler itself.  It produces a Scheme code for an FSM from the PlantUML
format.  This tool is meant to be called on a PlantUML file when a
program with a FSM is being built (for example, from a Makefile.)

I'm hoping that it will ease the burden of writing format parsers and
other useful GNU Guile libraries for the community.


* User-visible changes

--8<---------------cut here---------------start------------->8---
* Version 0.6.2 (2023-08-11)
** Bugfixes
*** =(smc context functional char)=: =pre-action= now always returns context
The procedure would return an undefined value when the input character is an
EOF object.  Now =pre-action= procedure always returns a context instance.

Also now the procedure handles cases when the input character is equal to
=#f=.
*** =(smc trace-context)=: Fix timestamp calculation
Procedures from the module now ensure that timestamps are always have positive
values.  When a negative value is detected then an error is issued.
*** =(smc cli command-profile)=: Fix time calculation
The profiler would fail to calculate correct time ranges.  Now the time is
calculated properly.
*** =(smc context oop generic)=: Add missing =(smc core log)= import
** Allow to set the FSM pre- and post-action in a PlantUML "legend" block
Guile-SMC now allows to set the pre/post actions for an FSM in the PlantUML "legend" block.
#+BEGIN_EXAMPLE plantuml
legend
pre-action:  custom-pre-action
post-action: custom-post-action
endlegend
#+END_EXAMPLE
** Add missing procedures for the =<fsm>= to get/set pre/post actions
Now the =(smc fsm)= module provides procedures to get and set pre- and post-actions.
** =(smc core log)= now registers the default logger
=(smc core log)= now registers the default logger under the name "guile-smc".
** =(smc core log)=: New procedure: =smc-log-default-logger=
This procedure allows to get the default logger instance.
** Update the documentation
--8<---------------cut here---------------end--------------->8---


* Usage examples

- Guile-INI -- INI[2] format parser:
  https://github.com/artyom-poptsov/guile-ics
- Guile-ICS -- iCalendar (RFC 5545) and vCard (RFC 6350) parser:
  https://github.com/artyom-poptsov/guile-ics
- Guile-PNG -- Pure Scheme Portable Network Graphics (PNG, RFC 2083)
  library:
  https://github.com/artyom-poptsov/guile-png

Happy hacking,

- Artyom

References:
1: https://plantuml.com/state-diagram
2: https://en.wikipedia.org/wiki/INI_file

-- 
Artyom "avp" Poptsov <poptsov.artyom@gmail.com>
Home page: https://memory-heap.org/~avp/
CADR Hackerspace co-founder: https://cadrspace.ru/
GPG: D0C2 EAC1 3310 822D 98DE  B57C E9C5 A2D9 0898 A02F

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]

Re: [ANN] Guile-SMC 0.6.2 released

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 669 bytes --]


"Artyom V. Poptsov" <poptsov.artyom@gmail.com> writes:

> I'm pleased to announce Guile State Machine Compiler (Guile-SMC), version
> 0.6.2:
>   https://github.com/artyom-poptsov/guile-smc/releases/tag/v0.6.2

Very cool!

> This release fixes some new-found bugs, namely in the state-machine
> profiler.  Also now it's possible to specify "pre-action" and
> "post-action" procedures in PlantUML "legend" block.

> - A transition table can be verified and checked for dead-ends and
>   infinite loops.

Can Guile-SMC be used as a linter for plantuml?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: [ANN] Guile-SMC 0.6.2 released

[Artyom V. Poptsov]

[-- Attachment #1: Type: text/plain, Size: 979 bytes --]

Hello Dr. Arne Babenhauserheide!

> Very cool!

Thanks.

> Can Guile-SMC be used as a linter for plantuml?

Yes, to some extent.  The thing is that Guile-SMC currently supports
only a small subset of PlantUML format.  Namely it can read PlantUML
state diagrams (obviously that was first priority for me to implement),
but even here not all diagram features are supported.

For example, Guile-SMC does not understand multi-line commends, "legend"
parameters, styles etc.

With that said, I'm planning to expand the supported subset of PlantUML
state diagram features in the near future.  As the core parser of
PlantUML format itself is compiled from PlantUML description with
Guile-SMC, it is quite easy to add new features from my experience.

- avp

-- 
Artyom "avp" Poptsov <poptsov.artyom@gmail.com>
Home page: https://memory-heap.org/~avp/
CADR Hackerspace co-founder: https://cadrspace.ru/
GPG: D0C2 EAC1 3310 822D 98DE  B57C E9C5 A2D9 0898 A02F

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]

Re: [ANN] Guile-SMC 0.6.2 released

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1215 bytes --]

Hello Artyom,

"Artyom V. Poptsov" <poptsov.artyom@gmail.com> writes:

> Hello Dr. Arne Babenhauserheide!
>
>> Very cool!
>
> Thanks.
>
>> Can Guile-SMC be used as a linter for plantuml?
>
> Yes, to some extent.  The thing is that Guile-SMC currently supports
> only a small subset of PlantUML format.  Namely it can read PlantUML
> state diagrams (obviously that was first priority for me to implement),
> but even here not all diagram features are supported.
>
> With that said, I'm planning to expand the supported subset of PlantUML
> state diagram features in the near future.

That sounds great.

> As the core parser of PlantUML format itself is compiled from PlantUML
> description with Guile-SMC, it is quite easy to add new features from
> my experience.

Just out of interest: can you post a part of the code you really like?

(I’m currently working on a webservice for work that has a state machine
in the background and it would be interesting to me to see whether I
could build a simple version of it with Guile for fun ☺ — trying to find
more elegance in this)

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: [ANN] Guile-SMC 0.6.2 released

[Artyom V. Poptsov]

[-- Attachment #1: Type: text/plain, Size: 5234 bytes --]

> Just out of interest: can you post a part of the code you really like?

Well, as Guile-SMC is a tool for making tools, I think that Guile-INI
could serve as a good example of what Guile-SMC can do.

Here, you can see the finite state machine (FSM) description in PlantUML
format:
  https://github.com/artyom-poptsov/guile-ini/blob/master/modules/ini/fsm.puml

Here's an excerpt from the file:

--8<---------------cut here---------------start------------->8---
read: The entry point
read ---> [*]: char:eof-object?
read --> read_global_comment: ini:comment/read?
read --> skip_global_comment: char:semicolon?
read --> read_section_title: char:left-square-bracket?
read --> read_property_key: char:letter? -> push-event-to-buffer
read -> read
--8<---------------cut here---------------end--------------->8---

"read" is a state, and the state has one transition to the final state
("[*]"), four transitions to another states and one transition to
itself.  This representation is basically is like a "cond" directive in
Scheme (or "switch..case" in C) that checks in turn each condition
(e.g. "char:letter?".)  Take this line for example:

--8<---------------cut here---------------start------------->8---
read --> read_property_key: char:letter? -> push-event-to-buffer
--8<---------------cut here---------------end--------------->8---

When a condition ("guard") returns "#t" the action assigned to this
transition is executed (in our example its "push-event-to-buffer") and
the FSM proceeds to the next state ("read_property_key".)

Note that most of the checks and all the actions here are provided by
Guile-SMC core context, and there's no need to implement it again and
again in each project.  In pre-Guile-SMC times I used to manually write
FSMs with those guards and actions for each project and this was real
PITA.  Also FSMs generated by Guile-SMC have embedded logging and this
helps too (with debugging/profiling.)

In that way Guile-SMC could serve as the basis for various parsers (I
already wrote FSMs for Guile-INI, Guile-ICS and Guile-PNG; and I'm
currently working on porting Guile-DSV FSM to Guile-SMC -- this work is
almost done.)

The only procedure that does not belongs to Guile-SMC is
"ini:comment/read?" -- this procedure is provided by Guile-INI custom
context:
  https://github.com/artyom-poptsov/guile-ini/blob/master/modules/ini/fsm-context-ini.scm

If you take a look at this file you'll find that there's not so much
custom code written.

Also when you describe your FSMs in terms of formal notation such as
PlantUML (or Graphiz for that matter, but Guile-SMC does not support
Graphiz yet), you get transition diagram visualization "for free":
  https://www.plantuml.com/plantuml/uml/jPV1Rji-3CRlVWe2_ziVS7RFOUqpRBqDGw0uJAp5aJo9RfSz_MANJWFjYsRNswL0P7u_Mnz5YdsCOe9qfwRuylzNAikF5DZiYgB_kwQdcecTX3ErtZePLgdieoxHQwfg4zRizwNVVkDA7lIvGZQ7nczDiwdywSHErcITNUkF3tt0JNmysZQ9LtpaawryurrAZro9zMuZLXhMu8RtKiRldGbSReEfZYofh0s-vI3dpP7FLvK8XmUwXBHTh4j-PYUb-7BRxVSS530w0oYV-W13uo9T5bU_nsMCw-bI1_zInhCJywFa47puCyBnIsCTpz3tWS6Ua0snDHK_J18zcwPZbV75xYQMqHxSrK9rhlSmYd4_3Q3YX1mw4tRh_-HkCWhm-P-FjYNJD2J1sCQw0mrxYMJsme6avY4bAbsK4e1OxWwWeZmL1NpFqsNnkk7WEzUVnTTQUZkIG-mA0PPwe11D9tOXNs6OY6qj2lWMhK2yQoHPK8nWrw0SpT2TrgPjsUtAKOSfsBe9jO3QfbO3wM-IsWZPI6rZAjvHrthtMYira_RGY43tDeTZOGil2d0FfCaQ4SRjA8eFJ5PMI9XFMMAuQZ07Rsm-1AnFoHguljIJgmLcJ0qDpu7adGSOCu0J4m7fRLnv9s-NTx27EhsGRtqUXezIjHFukZpRPFqgjLdhp7Aabs15s95rRvQle3RZDuuVFpq__q2X5bDs40AonAhvamu6pv-uC0QV56rYzxgNTT7k-3Ovj-5qFoTf67mvR6r9JqkQMTB5CkrhST-Q-VbJQGfxTyU2iwy-H3CmqYthNejdOkNWGGuy1JFoHCZYcHc-1PJw_1bQnGjcwR-JskaeRLyPpBzFIkOjcUC3BKz6U1tAHh-tlFU1RySqFCrZve8i0DWq0xKuSg2qaq6Gbl12rFos1lwboBYlwhdkvsJlR_GZ9qjVRDWZkrrtQdu1

(Sorry for such a long link; it has the diagram encoded in the URL.)

In my experience, visualization helps in many cases to grasp the problem
at hand, and you would write such formal state diagram anyways.  But
with Guile-SMC you'll get the diagram and the auto-generated code from
it at the same time.

> (I’m currently working on a webservice for work that has a state machine
> in the background and it would be interesting to me to see whether I
> could build a simple version of it with Guile for fun ☺ — trying to find
> more elegance in this)

I think that Guile-SMC is not bound to parsers realm and can be used to
create other state machines that handle network events, for example.
Even the standard library of procedures (the "context" in terms of
Guile-SMC) is written in such way that it does not enforce "the only
true way" of doing things.  For example, you can use anything as a
context memory for FSM, and you can write your own set of guards and
actions.

With all that said, please note that although I have some good
experience with state machines, I'm not considering myself as an expert
in this field; there are lots of nuances that I may not see yet.  So any
help with testing and developing the project will be appreciated indeed.

- avp

-- 
Artyom "avp" Poptsov <poptsov.artyom@gmail.com>
Home page: https://memory-heap.org/~avp/
CADR Hackerspace co-founder: https://cadrspace.ru/
GPG: D0C2 EAC1 3310 822D 98DE  B57C E9C5 A2D9 0898 A02F

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]