Code overview - or maybe not

You should use TextMorph.

What about:

|| t |
t := TextMorph new.
t backgroundColor: Color blue.
t contents: 'Hello'.
t lock.
t openInWorld||
|

Le 19/12/2019 à 15:28, Kasper Osterbye a écrit :
> I was struggling for weeks (not every day, but still) to find out how
> to change the system to be able to give background color to text. 
>
--
Dr. Geo
http://drgeo.eu

Works with StringMorph too...

--
Dr. Geo
http://drgeo.eu

Hi Kasper,

PlantUML is an excellent tool for visualizing code structure, design,
behavior...  For both designing it and documenting it.

I think its most interesting feature is that its API is text-based: You
literally "spell out" your diagram in text phrases, and its (Java-based)
engine will render it as a diagram (with the help of GraphViz).

And since it's text-based, there are extensions to text editors and document
processors (e.g., Word, LibreOffice Writer) that allow you to include the
PlantUML text in your document, then will render the diagrams in your
document for you automatically.  No cut-and-paste!

A standardized linkage to PlantUML in Pharo would be an excellent tool -- I
hope you're able to pursue this and make it available on GitHub...

-Ted




--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Such a tool has existed for a long time, it's called Squeak Reverse Engineering (SRE). It's very useful for exploring execution stacks, objects, and object structures. It goes across different kinds of objects. It only works in Squeak 3.10.2.
User manual at
http://folk.uio.no/trygver/themes/SRE/BabySRE.pdf
Latest version of the SRE programs in this image
http://dx.doi.org/10.17632/5xxgzv7fsp.1

Examples. (Top line [OOP]object name if any. Bottom line :Object's class name).




The new object inspector with state and behavior.

In an other thread Steve Davies mentions that Pharo can be a bit overwhelming. Indeed I have had the same feeling.

I was struggling for weeks (not every day, but still) to find out how to change the system to be able to give background color to text. 

As part of my attempt at understanding the code, I ended up looking at Rubric and its Text morphs. I have been working at building a little tool which can help me get an overview of the objects and how the are connected. Not a static code analysis, but a snapshot view. 

What I did was I took a root object, and made the transitive object closure from that object, with the following restrictions:

- Only Rubric, Morphic and Collections are examined, though Strings are excluded

- Only instance variables which has a selector of the same name are included

- The same object only appear once in the diagram, but more than one instance of a class can be present (at different places).

I build on a tool named PlantUML.

When I bring up the morphic halo on a playground and select "inspect morph", and then draw the diagram for that morph, I get this diagram.

Strangely, I find it useful. I use it as a supplement to the inspector.

I hope to be able to pack this tool, and a companion one for generating sequence diagrams based on the execution of a block given as parameter. I see these tools as exploratory tools, not as documentation tools.

Best,

Kasper,

https://github.com/kasperosterbye/PlantUMLBridge

Trygve: Yes, such tools are very useful - I will try to see if I can get that old image up and running and see if there is anything salvageable there. 

— Kasper

On 19 December 2019 at 23.07.38, Christopher Fuhrman ([hidden email]) wrote:

If you want to consider changing background color that takes into consideration the theme background (e.g. dark or light themes), this code (see it on GitHub) can adapt to it:

normalColor := Smalltalk ui theme backgroundColor.
green := normalColor mixed: 0.8 with: Color green.
red := normalColor mixed: 0.8 with: Color red.

I didn't really test it with all possibilities of themes, however. 

On Thu, 19 Dec 2019 at 12:58, Hilaire <[hidden email]> wrote:

You should use TextMorph.

What about:

|| t |
t := TextMorph new.
t backgroundColor: Color blue.
t contents: 'Hello'.
t lock.
t openInWorld||
|

Le 19/12/2019 à 15:28, Kasper Osterbye a écrit :
> I was struggling for weeks (not every day, but still) to find out how
> to change the system to be able to give background color to text. 
>
--
Dr. Geo
http://drgeo.eu

--

Christopher Fuhrman, P.Eng., PhD

Professeur au Département de génie logiciel et des technologies de l'information
ÉTS (École de technologie supérieure)

On Thu, Dec 19, 2019 at 09:57:43PM +0100, Trygve Reenskaug wrote:
> Such a tool has existed for a long time, it's called /Squeak Reverse
> Engineering /(/SRE/). It's very useful for exploring execution stacks,
> objects, and object structures. It goes across different kinds of
> objects. It only works in Squeak 3.10.2.
> User manual at
> http://folk.uio.no/trygver/themes/SRE/BabySRE.pdf
> Latest version of the SRE programs in this image
> http://dx.doi.org/10.17632/5xxgzv7fsp.1


I just downloaded this image from http://dx.doi.org/10.17632/5xxgzv7fsp.1
and it is working fine on my Linux laptop. It does require a suitable VM
(I compile my own). Very interesting stuff, thanks.

Dave

Thank you, Norbert!  

I do recall seeing an earlier version of this, when I was investigating how
to use PlantUML within Google Docs several months ago; that led me to
Christopher's blog,  https://fuhrmanator.github.io/
<https://fuhrmanator.github.io/>   (where I learned about Pharo's LibC class
and how to use it to invoke shell commands in Linux -- which I was quite
pleased to find!)

At the time, though, I didn't really investigate it; I got the impression
that it required Moose and was intended for analyzing other languages (such
as Java).  

What I would find useful (and what I think Kasper has started down the road
to) is the ability to generate PlantUML script from a specified (set of)
packages or classes in Pharo.  That would make it easy not only to examine
the design (in a more synoptic way -- something I've seen several other
newcomers express an interest in), but also to embed diagrams in
documentation such as PDFs & web pages.

Short of that, and probably much easier to implement, is to just add
PlantUML script to Pharo class comments as you write them -- but have a
simple way to trigger the system to parse the comment and render the script
into PlantUML diagrams.  This could be in the form of opening a web browser
in the host and having the diagram appear via the PlantUML server.  But more
useful perhaps would be to have it create PNG file(s) in the host filesystem
(and open them).

How about this? A GUI app in Pharo that allows one to create UML diagrams in
a more point-and-click fashion, which then outputs the equivalent PlantUML
script (with an option to automatically embed it in a selected class
comment).  That, plus the normal text in class comments, would allow anyone
who needs a deeper understanding of the package/class set to easily obtain
UML diagrams as well as descriptions -- all without the need to embed
drawings within an image -- or rely on external PDF booklets and web pages.

Otherwise, being unfamiliar with the implementation details of a class that
seems useful for building something, I find that you end up having to slowly
build your own mental model of the class structure (and its behavior) by
opening and studying class & methods, one after another.  Better would be a
synoptic view of the whole thing in a few UML diagrams.

This could be taken further, of course: A Pharo app that allows one to draw
UML diagrams, then not only renders the PlantUML script, but also constructs
the classes & method templates in your image for you.  Start with UML to
design what you have in mind, then with a few clicks, generate "starter
code" and continue by filling in the details of the methods to implement
your application.

That could be Pharo's "killer app"...

-t



--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

I expect that to be done over the hollidays. I expect to have a working copies of

- Generate object diagram from a root (I will filter on category names and subclasses)

- Generate a sequence diagram by analysing a MessageTally from a block. Filter on categories, subclasses and methods

--

Excellent!  I think Pharo will greatly benefit from having something like
this.

I push for UML tools here where I work, but it tends to fall on deaf ears.
(To be fair, that's probably mainly due to few of us having the
understanding of, and working with, OOD/OOP.  I think both will need to
change in lock-step.  I will not give up...)

I'm also interested in ways to help newcomers (myself included) grasp not
just the tools in Pharo, but the codebase as well.  To build an app in
Pharo, one needs to know what's available in the base in the form of classes
& methods -- because that's what you build your own apps on top of, what you
sometimes extend, and what you include/call from your code, etc.

This is compounded when you factor in libraries outside of Pharo that you
can obtain from GitHub/SmalltalkHub/etc.  More codebases to know about!

Pharo has wonderful search tools...  It's a big selling point.  And examples
help a lot.  So does the wonderful library of booklets, and the many blogs.

But what about having "understanding tools" within the IDE?  Pharo is
explorable (another selling point), and one technique is to browse the
codebase.  Yet browsing by the class & method requires a good memory & the
ability to intuit from the limited view of "one method at a time" to build
up an understanding of what the foundation code is, and how to use it
(properly).  

I'm thinking of such things as Spec, Seaside, etc.  And yes, one tends to
open multiple windows, which helps -- to a point, after which you have a
"window management problem".  Big & multiple monitors were never so useful!

But tools like what you're creating, Kasper, will help that issue by showing
a wider, more integrated view with fewer fine details.  Something between a
top-level class structure such as what we see for Collections in the 'Pharo
by Example' book and reading method code line by line.

This is what UML was designed to address.  A "live environment" that also
has "live UML" would be, for me, the "killer app" that would make Pharo
irresistibly compelling.

-t



--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

On 20 December 2019 at 21.30.00, Christopher Fuhrman ([hidden email]) wrote:

Kasper,

There's a way to run PlantUML to process in a pipe (stdin/out) which gives pretty good performance for rendering:

java -Djava.awt.headless=true -jar plantuml.jar -pipe -tsvg -charset UTF-8 

It takes a PlantUML source as input and generates the format of the file (e.g. SVG) on stdout. The VSCode extension called  markdown-preview-enhanced runs it this way. Because of the pipe complexity (and the fact that your machine needs a JVM, GraphViz and a properly configured path, etc.), I never tried to use it this way in Pharo. 

The markdown-preview-enhanced extension for VSCode does a lot of things (too many?) but I think of pillar when I use it. It shows an HTML version in real-time as you type, which includes PlantUML diagrams. You can use pandoc to get to LaTeX/PDF as final output. I'm using it for my course notes because of this, but also because it does reveal output (useful for presenting), too. If I had a Mac, I would use pillar :) -- I struggled with using it in Windows 10 with MikTeX (which I use very well with LyX).

If my memory serves me, Pavel K. and/or Julien D. had done a visitor in Pharo that would generate PlantUML script from (moose?) (meta)models, but I can't remember the precise details. I didn't aim for the sexy visitor version when I did the Moose support because I wanted people to be able to choose easily what classes to include in the diagram (because there's usually some context for it to be useful). A list with classes inside a hierarchy (the way we did it in Moose) seemed to be adequate. I'm pretty sure you could make an intuitive browser (or reuse the current one) with filters to select the classes for the diagram. 

As for using UML to make diagrams, I also have toyed with the idea of making an editor on top of PlantUMLs SVG, such that you could change the source script intuitively. For example, if you don't want to see the 30+ messages a class supports, you can right click on the class in the SVG and choose a "hide" option. Sadly, the SVG that is generated by PlantUML is more for drawing (it was ported from the PNG code I think) and so things like a bounding box of a class or the IDs for classes don't exist. Classes are "drawn" as a rectangle for the title, a rectangle for the attributes, etc. However, those are all things that could be coded back into PlantUML (it's open source). SVG (in a modern browser at least) can be pretty powerful. 

These days, the only UML diagrams I "draw" are on whiteboards or an electronic sketch pad (Surface pro). Pushing rectangles and lines around in a graphics editor is something that only makes me anxious (I have used some Visio templates a few years ago, but they're all now requiring too many clicks when you're used to PlantUML). Plus, PlantUML also supports many other formats (including DOT, just put @startdot/@enddot). 

On Fri, 20 Dec 2019 at 14:31, Kasper Østerbye <[hidden email]> wrote:

On 20 December 2019 at 19.59.05, tbrunz ([hidden email]) wrote:

What I would find useful (and what I think Kasper has started down the road 
to) is the ability to generate PlantUML script from a specified (set of) 
packages or classes in Pharo. That would make it easy not only to examine 
the design (in a more synoptic way -- something I've seen several other 
newcomers express an interest in), but also to embed diagrams in 
documentation such as PDFs & web pages. 

I expect that to be done over the hollidays. I expect to have a working copies of

- Generate object diagram from a root (I will filter on category names and subclasses)

- Generate a sequence diagram by analysing a MessageTally from a block. Filter on categories, subclasses and methods

Short of that, and probably much easier to implement, is to just add 
PlantUML script to Pharo class comments as you write them -- but have a 
simple way to trigger the system to parse the comment and render the script 
into PlantUML diagrams. This could be in the form of opening a web browser 
in the host and having the diagram appear via the PlantUML server. But more 
useful perhaps would be to have it create PNG file(s) in the host filesystem 
(and open them). 

I have that working in my image. The https://github.com/kasperosterbye/PillarRichTextRender allow pillar to be used and rendered in class and package comments. Again, in my image I have an extension which allow the [[[ … ]]] syntax of pillar (and ```of github) to use a language called ‘plantuml’, which renders the diagram in the documentation. I hope to package it all up over the holidays or early January. The same thing allow latex math to be rendered in those same comments.

Best,

Kasper

--

Christopher Fuhrman, P.Eng., PhD

Professeur au Département de génie logiciel et des technologies de l'information
ÉTS (École de technologie supérieure)

http://profs.etsmtl.ca/cfuhrman

+1 514 396 8638

L'ÉTS est une constituante de l'Université du Québec