Code overview - or maybe not
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 <https://www.plantuml.com/plantuml/svg/ZLfFZzks4h_lfp1oUdieG54aHVNmq6IJea4RTD...> . 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,
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
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) <https://github.com/moosetechnology/Moose-Easy/blob/f7967b310021147792858c576...> 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 <hilaire@drgeo.eu> 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)*
My issue with the background color was how to make a TextAttribute to set the background color of individual characters, not the overall background of the text. I succeeded, and Pharo 8 has a background text attribute - at least using Rubric - see https://github.com/pharo-project/pharo/pull/5326 Christopher - thanks for the hint on doing background colors based on theme. I did do it for the two main themes, and did not try out the larger set of themes. I needed it because I am working on an in-image pillar renderer for class and package comments, and I wanted to be able to do the inline code as done in github markdown. There is a preview of this at: https://github.com/kasperosterbye/PillarRichTextRender Best, Kasper On 19 December 2019 at 23.07.38, Christopher Fuhrman ( christopher.fuhrman@etsmtl.ca) 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) <https://github.com/moosetechnology/Moose-Easy/blob/f7967b310021147792858c576...> 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 <hilaire@drgeo.eu> 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)*
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
Am 19.12.2019 um 19:22 schrieb tbrunz <wild.ideas@gmail.com>:
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...
Do you know https://github.com/fuhrmanator/PlantUMLPharoGizmo <https://github.com/fuhrmanator/PlantUMLPharoGizmo> ? Norbert
-Ted
-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
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
On 20 December 2019 at 19.59.05, tbrunz (wild.ideas@gmail.com) 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
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 <https://github.com/shd101wyy/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 <kasper.osterbye@gmail.com> wrote:
On 20 December 2019 at 19.59.05, tbrunz (wild.ideas@gmail.com) 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*
I fully planned to do something about this over Christmas, but alas, family had other plans, and thanks for that. Now however I got a working prototype of what I wanted to build: https://github.com/kasperosterbye/PlantUMLDiagrams The tools are intended as investigation tools. Similar or better tools might be out there, but I mistook this to be a minor thing, and ended up spending too much time on this. And thanks to Christopher Fuhrman for the plantuml gizmo. I extracted a minimal interface out of his code, which I have put up as a separate project (https://github.com/kasperosterbye/PlantUMLBridge) simply because it is such cool code, and I wanted to be able to do the minimal plantuml integration possible without commitment to any pharo tooling. Best, Kasper On 20 December 2019 at 21.30.00, Christopher Fuhrman ( christopher.fuhrman@etsmtl.ca) 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 <https://github.com/shd101wyy/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 <kasper.osterbye@gmail.com> wrote:
On 20 December 2019 at 19.59.05, tbrunz (wild.ideas@gmail.com) 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*
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
Do you know https://github.com/fuhrmanator/PlantUMLPharoGizmo ? Norbert Indeed I know that tool, I actually base my stuff on the transformation Furhman makes in that program, only I did not use the whole tool, but just the source to url part. On 19 December 2019 at 19.15.39, tbrunz (wild.ideas@gmail.com) wrote: 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... I tried to reduce the pharo to plantUML to its barebone. Take a look at 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
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 clas//s name/). The new object inspector with state and behavior. The new /Transcript //show:xx/ with the stack. On 19.12.2019 15:28, Kasper Osterbye wrote:
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 <https://www.plantuml.com/plantuml/svg/ZLfFZzks4h_lfp1oUdieG54aHVNmq6IJea4RTD...>.
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,
-- /The essence of object orientation is that objects collaborateto achieve a goal. / Trygve Reenskaug mailto: trygver@ifi.uio.no <mailto:%20trygver@ifi.uio.no> Morgedalsvn. 5A http://folk.uio.no/trygver/ N-0378 Oslo http://fullOO.info Norway                     Tel: (+47) 468 58 625
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
Examples. (Top line/[OOP]object name if any/. Bottom line /://Object's clas//s name/).
The new object inspector with state and behavior.
The new /Transcript //show:xx/ with the stack.
participants (8)
-
Christopher Fuhrman -
David T. Lewis -
Hilaire -
Kasper Osterbye -
Kasper Ãsterbye
-
Norbert Hartl -
tbrunz -
Trygve Reenskaug