2016-08-25 23:40 GMT+02:00 Tudor Girba <tu...@tudorgirba.com>: > Hi Nicolai, > > Thanks a lot for the feedback. Please let’s continue. See more inline. > > > On Aug 25, 2016, at 6:34 PM, Nicolai Hess <nicolaih...@gmail.com> wrote: > > > > > > > > 2016-08-25 8:47 GMT+02:00 Tudor Girba <tu...@tudorgirba.com>: > > Hi, > > > > Hi Doru, > > some questions and feedback ( I am sorry for my tone or if this sounds > negative, it isn't meant to be) > > > > Over the last coupe of years Stefan Reichhart and the rest of the GT > team worked on an implementation of examples. The work is inspired from > previous work done by Markus Gaelli and Adrian Kuhn. > > > > As one of the goals of GT is to offer a live programming environment, > > > > Isn't this what we already have, a live programming environment, I think > for newcomers (and maybe others) this needs to make be more clear, how is > different, what gap are you trying to fill. > > > > one important issue is how to move from the static code to live objects > as fast as possible. > > > > Isn't code always "static" and aren't objects always "live", how do play > gtExamples any role in this? > > What I meant is that I want to be as little as possible in the static code > browser. Instead I want to write code in the presence of a bounded “self” > which happens either in a debugger or in an inspector. > > The gap that examples fill is that when I look at a static code and I have > examples about it, I can possibly jump to those examples and code against > their result. So, instead of coding a method about a FileReference in the > code browser, I will code it against an instance of a FileReference. Hence, > we make live programming easier to achieve. > > > > That is why we worked on this library as a solution to provide a link > between the static code and live objects. > > > > From my understanding, I think this "link" between code an objects is > the real valuable new point. This is the great thing about gtExamples. link > from code (the example methods itself or methods refering a class > > to an example object/instance that can be inspected (the raw object or > an object specific inspector pane). > > This is what I would consider the real step forward. You see a method > refering to class TextModel and Nautilus or any other tool not only offers > a method to browse all Users of this class, but too, a dedicated > > list of "example methods" where every example has a view for this > example instance that let the user show and interact (even for non-visual > objects through the "evaluater pane", or just see the code creating this > > example. > > Exactly. > > > We really miss examples, I often see questions on the mailing list > (especially about spect) that can be explained easily with an example. And > even worse, often the examples already exists, they just aren't as visible. > > Exactly. These examples are particularly amplified by the fact that we > have an inspector that can provide a reacher experience through different > views. > > > > Furthermore, this examples library also enables the definition of > assertions on the examples, and this provides the possibility of rethinking > the way we construct tests throughout our system. Tests are great as they > help us create live objects and then to assert live properties. > > > > This whole thing sounds as if Unit-Test were a good idea but not the way > that they are used today, I strongly disagree. I don't see this as a > "rethinking the way we construct tests", yes, we can > > augment the current set of tests with addtional assertions on live > objects, but this is not a replacement. > > "Tests are great as they help us create live objects" This is not my > only purpose for writing tests, often unit-tests cover methods and > "private-apis" not even considered to be used on live objects. You can not > (or I don't want to > > ) write tests only on "finished lived objects" sometimes we need tests > for initialiazation/private code or exception handling I don't see how we > can offer this only by using example instances (yes your "rethinking" > sounds like "this > > is the better way to do tests”). > > I think there is a misunderstanding here. > > When I test, (1) I create one or more objects, (2) I assert against them > and then (3) I potentially cleanup. At least the objects from step 1 are > potentially interesting for documentation purposes as well. However, > because tests are built in a completely different environment than examples > are, and because they are not casually linked to the code they are about, > we cannot exploit them to the maximum potential. > > The GT-Examples model offers a unification. This means that you can use > the same mechanism for expressing both a test scenario and a documentation > one. There is potential to be exploited here. For example, there is > research that aims to take the all sorts of objects and try to infer types > for code out of these. We could make this much simpler. > > I understand that this is a departure from the classic way of testing, but > we have already expressed more than 1 thousand examples both from a > documentation and from testing point of view, and it does seem to work. > > > > However, they do not allow us to leverage the objects we create, and > this can be a tremendous resource for understanding systems. > > > > In our vision, examples should be everywhere and they should be > explicitly linked to the static code they exemplify. That is why the > library comes with an initial integration in existing tools (such as > Nautilus, Spotter, Inspector). > > > > The current solution works well and it is the result of several > rewrites. We think that the solution is complete in terms of features, but > there are still several things to improve and iterate on. To this end, I > kindly ask you to take a look at it while distinguishing between the > concrete implementation choice (e.g., the current extensive use of pragmas) > and the conceptual benefits of the approach. > > > > To ease the discussion, we put together a short documentation: > > > > Everytime I see a gtExample method on a class I first think, shouldn't > this go to a Help or Doc or Exampels class instead. I don't know how others > thinks about this but this is my first impression. > > For example, the example on your page: > > > > FileSystem class >> #createFileOnDisk > > > > <gtExample> > > < > > description: 'Create a new file or override an existing file with some > contents. Open and close the stream safely' > > > > > ^ > > FileSystem workingDirectory / 'test.txt' > > > > > > writeStreamDo: [ :stream | stream nextPutAll: self > > comment ]; > > yourself > > > > Nice, now the user can see how to use FileSystem to create a file, open > *and* close the stream safely. But for me, this method does *not* belong > to the FileSystem class it just not make any sense to me, to have a method > (*in this class*) that opens and closes a stream. Even if this is just an > example, I would put it in a doc-page or a tutorial that can execute code. > But again , this is just my point of view. > > I can not really explain it, having a example method on Morph or a > widget ui or a widget model class, that opens an example morph or widget in > the world, is for me something completly different and a valid example. > > Having the same for the method above - is not, at least not as > executable code on the FileSystm class). > > I do not understand this last point. > > Just because an object does not have a visual appearance like a Morph > does, does not make it uninteresting from an interaction point of view. The > inspector already can provide the views. We also have the possibility of > adding custom actions that can be installed as menu items. Even for a > morph, I sometimes want to not look at its default appearance, but at its > submorphs. Thus, I do not see the confusion. > > Nevertheless, the example does not have to be on the class side. It can be > in any class you want and you can associate it with a subject. For example, > all Roassal examples are in dedicated classes. There are hundreds of > methods, so putting them all on the class side of a domain class would not > work at all. We showed the example on the class side because that is a > pattern that people used for a long time and it is a reasonable place when > you have only a handful of examples. The rationale is that an example is a > way to instantiate a class, so having it on the class side is not far > fetched. Also, if you put it on the class side, you get by default the > class as a subject for the examples it contains which is quite natural. > > > > http://gtoolkit.org/doc/Examples/examples.html > > > > That being said, you can get it with the full GToolkit in Pharo 6.0: > > > > Is this based on the recent Pharo 6.0? > > > > GTExamplesReleaseTests are failing for me > > Yes, these are yellow. > > > > Where did you test this? I get some Object>>#name deprecation warnings > when browsing for examples refering a class, for example on > > class FileSystem and menu entry "Browse Examples refering FileSystem" > (maybe a Pharo 5.0 version?) > > I tested in Pharo 6.0 (60188), but we just got a problem that was reported > related to Epicea and Martin is looking at it. > > > > The example on the examples.html side isn't actually in the image right? > > Yes, it’s not there yet. > > > > The browsing examples of a package (context menu on nautilus package > pane) does not work or I don't understand why it does not find any examples > at all. > > The World menu "Browse All Examples" does not contain the class > FileSystem, although FileSystem>>gtExampleZip is a gtExample, this is > because > > the example method is in an extension package, should all gtExample > methods be class extensions ? This is handled differently for different > packages. > > Hmm. When I "Browse All Examples" I get a Nautilus with FileSystem > class>>gtExampleZip in my image. But, indeed, in the latest GToolkit image, > this example is missing. > > > > The code pane context menu of a sendersOf Message browser is broken > (debug menu). > > I do not understand what menu item you refer to. Could provide a > screenshot. > > > > > From the web-side: > > > > "Furthermore, Nautilus, the World-Menu, all Rub-Text-Editors as well as > Spotter and Inspector provide access to retrieve, browse and navigate > examples from entities within the world" > > I can not find it, not in inspector, Rub-Text-Editors, only in Nautilus. > > In Nautilus and in RubText you get it in the GT-Examples menu (Browse > examples with subject …). > > The Inspector is not yet there, but we are adding it. > > > > And the menu entries are ... unfortunate (see screenshot), what you put > in, the whole source as menu label? > > Hmm. Something is strange there. I get the name of a method, not the > source code. What image are you in? >
Ah, it always uses the "selected text" for building the menu label, in this example screenshot, I 've selected the whole method. Hm. But I don't know how it would find the selected method anyway. If I selecte the method #append: and select Browse examples with subject #append: or Browse examples with literal: #append: it opens a browser on class Text ander there is a Text class>>#gtExampleSimple, but it does not contain #append: not as a literal or as a message send. I did another test: select the message "asText" and choose Browse Examples with literal #asText It opens a browse with some more classes/example methods but I can not see *any* relation between this example methods and the text I selected. > > > > run "run the example and return its return-value" > > > > debug > > "same run, but open debugger if the example fails” > > returnValue > > "the return-value" > > Executing run/debug/inspect returnValue does not seem to make any > different when called from nautilus. It always gives > > an inspector on a dictionary holding the gtexample and its > gtexampleresult (is this a bug?) > > Yes. > > > > Glossary: > > "Example: an example is a tiny stub object representing a GT-Example. It > holds the references to its dependencies, subjects and many other entities. > " > > What are "many other entities" this is a bit unclear > > Icon, Label, Provider, and others that you can add through custom > annotations if you want to. This part is not yet clear. > > > > "After-method: the after-method is a method that is performed right > after the example." > > After the example ? I thought an example is a "tiny stub *object*", how > can it run? > > How it is run after I run an example for inspection, after I closed the > inspector? > > Not yet. At this point, inspecting does not prevent triggering of the > cleanup method, but it would certainly be interesting to get there. > > Cheers, > Doru > > > http://gtoolkit.org/#install > > (easiest is to download the ready made image for now) > > > > For those that are at ESUG, I will try to provide a short overview > during the Show Us Your Project session from today. > > > > Cheers, > > Doru > > > > > > -- > > www.tudorgirba.com > > www.feenk.com > > > > "Reasonable is what we are accustomed with." > > > > > > > > <gtexample_menu.png> > > -- > www.tudorgirba.com > www.feenk.com > > "No matter how many recipes we know, we still value a chef." > > > > > > > > >
