Smalltalk › Pharo › Pharo Smalltalk Developers

Re: [ann] moldable editor - documenter and examples without pragma magic

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

Denis Kudriashov

Re: [ann] moldable editor - documenter and examples without pragma magic

Hi Tudor.

Could you show example with parameters? Is it possible to inspect it and how it works?

And what the difference now from existing <example> methods ?

2017-09-01 23:51 GMT+02:00 Tudor Girba <[hidden email]>:

Hi,

When we announced the GT Documenter as an application for the moldable editor, one of the remarks was that GT Examples implementation relies too much on pragma magic.

We are now happy to announce that this is no longer the case because Andrei did a great job and rebuilt examples without the need for static pragmas for specifying dependencies.

So, now we can example dependencies simply through normal calls:

emptyView
<gtExample>
^ GtMondrian new

twoNodes
<gtExamples>
view := self emptyView
view nodes with: {1 . 2}

... and the engine can figure out the static dependencies. This means that examples can be used both as plain unary methods, and as replacement for tests. We think this should address the worry of examples being too heavy (the current implementation is ~350 lines).

With a bit of extra effort, we also adapted GT Documenter to expand the example dependencies as seen below. This means that examples can now be used directly as units of documentation as well.

We think this is significant.

Cheers,
The feenk team

--
www.tudorgirba.com
www.feenk.com

"We are all great at making mistakes."

Tudor Girba-2

Re: [ann] moldable editor - documenter and examples without pragma magic

Hi,

On Sep 2, 2017, at 10:49 AM, Denis Kudriashov <[hidden email]> wrote:

Hi Tudor.

Could you show example with parameters? Is it possible to inspect it and how it works?

The whole point was to have examples depend on each other without injecting parameters.

One interesting thing about having dependencies between examples inferred statically is that we can build interesting tools. An example is a unit of comprehension and testing. For example, inspecting an example can show all dependencies, and the overall picture can transform into a logical tutorial. You can also have assertions inside examples, and run them as tests.

Below you can see a picture of inspecting the examples from GtMondrian. There are a few red ones in the first pane. Selecting an example shows how it depends on other examples. At the same time, you can also see the sources expanded.

What this means is that we can use the same effort and engine for both testing and documentation purposes. I will show a real case study on Monday in which we used examples as the only mechanism to drive an extensive project. It works remarkably well and we did not need classic tests at all. We call this example-driven development :).

From the same interface, you can also run an example like this (pressing the play button - you can also execute it directly from the list of examples):

And what the difference now from existing <example> methods ?

<example> are rather free form unary methods and are typically used for morphs like this:

exampleListWithExplicitFilterAndActionButton2

<example>
| list |
list := ...
list openInWindow

In contrast, <gtExample> marks a method that returns an object, ideally in a side-effect free manner. This object can then be used both to be viewed in different ways through inspector extensions, and can also serve as a starting point for further explorations.

Cheers,

Doru

2017-09-01 23:51 GMT+02:00 Tudor Girba <[hidden email]>:
Hi,

When we announced the GT Documenter as an application for the moldable editor, one of the remarks was that GT Examples implementation relies too much on pragma magic.

We are now happy to announce that this is no longer the case because Andrei did a great job and rebuilt examples without the need for static pragmas for specifying dependencies.

So, now we can example dependencies simply through normal calls:

emptyView
<gtExample>
^ GtMondrian new

twoNodes
<gtExamples>
view := self emptyView
view nodes with: {1 . 2}

... and the engine can figure out the static dependencies. This means that examples can be used both as plain unary methods, and as replacement for tests. We think this should address the worry of examples being too heavy (the current implementation is ~350 lines).

With a bit of extra effort, we also adapted GT Documenter to expand the example dependencies as seen below. This means that examples can now be used directly as units of documentation as well.

We think this is significant.

<Playground-mondrian-self-send-examples.png>

Cheers,
The feenk team

--
www.tudorgirba.com
www.feenk.com

"We are all great at making mistakes."

--
www.tudorgirba.com
www.feenk.com

"What is more important: To be happy, or to make happy?"