- Pharo-dev - lists.pharo.org

Re: [Pharo-dev] <example>/<examplar>

by Denis Kudriashov

Hi Why not use <example> pragma in the way you propose for <examplar>? Why we need two? 2016-08-18 14:38 GMT+02:00 stepharo <stepharo(a)free.fr>: > Hi > > In my projects I start to do the following: > > I create <examplar> class method that returns an prototypical instance. > > I use such methods in my tests as fixture. > > Then I would like to have nautilus presenting to me the <examplar> with a > little triangle and when I press > > on them I get an inspector on them. > > This way I get the same behavior than with default <example> methods that > open an widget, image.... > > If we agree on that > > - I can take all the <example> and turn them if necessary into > examplar. > > - extend Nautilus to send an inspect to the result of examplar tagged > method. > > I think that we can achieve a lot in terms of discovery with such simple > changes. > > Stef > > PS: I reread the old thread and I think that this is a reasonable approach > that makes > > the pro instances (like me) and the pro examples showing some things (like > me) happy. > > >

Aug. 18, 2016

Re: [Pharo-dev] About PythonDocTest for Pharo

by Tudor Girba

Hi, > On Aug 18, 2016, at 2:41 PM, stepharo <stepharo(a)free.fr> wrote: > > Hi doru > > >> Hi, >> >> I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions. >> >> I am also happy that you are considering the use of pragmas for this purpose. >> >> As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. > I do not want 5 pragmas and dependencies between methods and examples. KISS. > Pharo tends to forget KISS far too often recently. > You know exactly what I do not want: conceptual (and code) bloat. It think it is KISS. If you only want one feature, you use exactly one pragma <gtExample>. Nothing else. If you want more, as people do, you can get more. But, I wonât go into a debate now. First, I would like to present what exists and then you can form an opinion if you want. Just a note: there already exists in the image a first implementation of GTExample, and this proved very useful for testing the inspector and spotter. However, this was introduced without proper discussion, and as we do not want to impose anything we will remove the whole 1400 lines of code of the GTExample implementation from the GT-Inspector package as it did not belong there anyway, and we will make the new one available separately outside of Pharo. In this way, people can look at it if they want and we can have a discussion if desired. >> Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. > My plate is really full. I have a super long list of things that I want to discuss at ESUG. Ok. Doru > Stef >> Cheers, >> Doru >> >> >>> On Aug 18, 2016, at 1:32 PM, stepharo <stepharo(a)free.fr> wrote: >>> >>> Tx serge >>> >>> - I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily. >>> >>> So any idea instead of >>> <exp: value:> >>> >>> <expression: return: > >>> >>> withExtension: aString >>> >>> "Returns a new file reference with a different file extension" >>> >>> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >>> >>> value: '/tmp/file.log' asFileReference > >>> >>> ^ self withPath: (self path withExtension: aString) >>> >>> >>> - then incrementally we can start taking on system for example FS and use it. >>> >>> Stef >>> >>> >>> Le 18/8/16 Ã 11:51, Serge Stinckwich a Ã©crit : >>>> On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo(a)free.fr> wrote: >>>>> Hi guys >>>>> >>>>> I'm fed up to get methods without comments and without little examples. In >>>> +1 ! >>>> We can setup a small group of people interested to build examples at ESUG. >>>> >>>>> FileSystem, I wrote most of the comments and I tried to add an obvious >>>>> example: >>>>> >>>>> basenameWithIndicator >>>>> "Returns the basename with the indicator appended, i.e. >>>>> /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo >>>>> basenameWithIndicator is 'foo/'" >>>>> >>>>> ^ self basename , self indicator >>>>> >>>>> >>>>> Now let us look at: >>>>> >>>>> withExtension: aString >>>>> ^ self withPath: (self path withExtension: aString) >>>>> >>>>> >>>>> Nice comment :( >>>>> >>>>> I would like to support PythonDoctest (yes we are not the only one to have >>>>> ideas let us face is dear friends) >>>> +1 >>>> >>>> https://en.wikipedia.org/wiki/Doctest >>>> >>>>> def multiply(a, b): >>>>> """ >>>>> >>> multiply(4, 3) >>>>> 12 >>>>> >>> multiply('a', 3) >>>>> 'aaa' >>>>> """ >>>>> return a * b >>>>> >>>>> Because we can make sure that the comments are accurate. >>>>> >>>>> >>>>> withExtension: aString >>>>> >>>>> "Returns a new file reference with a different file extension" >>>>> >>>>> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >>>>> >>>>> value: '/tmp/file.log' asFileReference > >>>>> >>>>> ^ self withPath: (self path withExtension: aString) >>>>> >>>>> >>>>> It will help us to have a distinction between printOn: and displayString >>>>> >>>>> Typically >>>>> >>>>> '/tmp/file.txt' asFileReference withExtension: 'log' >>>>> >>>>> printString is bad >>>>> >>>>> since it returns File @ '/tmp/file.log' which is not an reexecutable >>>>> expression >>>>> >>>>> >>>>> >>>>> So let me know what you think. >>>>> - tell me that we have already test unit (yes the ones I wrote too) >>>>> => they do not have the same purpose >>>>> >>>>> For me this is getting to be important. >>>> Maybe a subset of Pharo could be defined as core with a kind of API >>>> freeze, so we can spend some time >>>> documenting the corresponding methods and classes. >>>> >>> >> -- >> www.tudorgirba.com >> www.feenk.com >> >> "Every thing has its own flow." >> >> >> >> >> >> >> > > -- www.tudorgirba.com www.feenk.com "Next time you see your life passing by, say 'hi' and get to know her."

Aug. 18, 2016

Re: [Pharo-dev] About PythonDocTest for Pharo

by stepharo

Hi doru > Hi, > > I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions. > > I am also happy that you are considering the use of pragmas for this purpose. > > As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. I do not want 5 pragmas and dependencies between methods and examples. KISS. Pharo tends to forget KISS far too often recently. You know exactly what I do not want: conceptual (and code) bloat. > Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. My plate is really full. I have a super long list of things that I want to discuss at ESUG. Stef > Cheers, > Doru > > >> On Aug 18, 2016, at 1:32 PM, stepharo <stepharo(a)free.fr> wrote: >> >> Tx serge >> >> - I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily. >> >> So any idea instead of >> <exp: value:> >> >> <expression: return: > >> >> withExtension: aString >> >> "Returns a new file reference with a different file extension" >> >> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >> >> value: '/tmp/file.log' asFileReference > >> >> ^ self withPath: (self path withExtension: aString) >> >> >> - then incrementally we can start taking on system for example FS and use it. >> >> Stef >> >> >> Le 18/8/16 Ã 11:51, Serge Stinckwich a Ã©crit : >>> On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo(a)free.fr> wrote: >>>> Hi guys >>>> >>>> I'm fed up to get methods without comments and without little examples. In >>> +1 ! >>> We can setup a small group of people interested to build examples at ESUG. >>> >>>> FileSystem, I wrote most of the comments and I tried to add an obvious >>>> example: >>>> >>>> basenameWithIndicator >>>> "Returns the basename with the indicator appended, i.e. >>>> /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo >>>> basenameWithIndicator is 'foo/'" >>>> >>>> ^ self basename , self indicator >>>> >>>> >>>> Now let us look at: >>>> >>>> withExtension: aString >>>> ^ self withPath: (self path withExtension: aString) >>>> >>>> >>>> Nice comment :( >>>> >>>> I would like to support PythonDoctest (yes we are not the only one to have >>>> ideas let us face is dear friends) >>> +1 >>> >>> https://en.wikipedia.org/wiki/Doctest >>> >>>> def multiply(a, b): >>>> """ >>>> >>> multiply(4, 3) >>>> 12 >>>> >>> multiply('a', 3) >>>> 'aaa' >>>> """ >>>> return a * b >>>> >>>> Because we can make sure that the comments are accurate. >>>> >>>> >>>> withExtension: aString >>>> >>>> "Returns a new file reference with a different file extension" >>>> >>>> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >>>> >>>> value: '/tmp/file.log' asFileReference > >>>> >>>> ^ self withPath: (self path withExtension: aString) >>>> >>>> >>>> It will help us to have a distinction between printOn: and displayString >>>> >>>> Typically >>>> >>>> '/tmp/file.txt' asFileReference withExtension: 'log' >>>> >>>> printString is bad >>>> >>>> since it returns File @ '/tmp/file.log' which is not an reexecutable >>>> expression >>>> >>>> >>>> >>>> So let me know what you think. >>>> - tell me that we have already test unit (yes the ones I wrote too) >>>> => they do not have the same purpose >>>> >>>> For me this is getting to be important. >>> Maybe a subset of Pharo could be defined as core with a kind of API >>> freeze, so we can spend some time >>> documenting the corresponding methods and classes. >>> >> > -- > www.tudorgirba.com > www.feenk.com > > "Every thing has its own flow." > > > > > > >

Aug. 18, 2016

by stepharo

Hi In my projects I start to do the following: I create <examplar> class method that returns an prototypical instance. I use such methods in my tests as fixture. Then I would like to have nautilus presenting to me the <examplar> with a little triangle and when I press on them I get an inspector on them. This way I get the same behavior than with default <example> methods that open an widget, image.... If we agree on that - I can take all the <example> and turn them if necessary into examplar. - extend Nautilus to send an inspect to the result of examplar tagged method. I think that we can achieve a lot in terms of discovery with such simple changes. Stef PS: I reread the old thread and I think that this is a reasonable approach that makes the pro instances (like me) and the pro examples showing some things (like me) happy.

Aug. 18, 2016

Re: [Pharo-dev] About PythonDocTest for Pharo

by Tudor Girba

Hi, I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions. I am also happy that you are considering the use of pragmas for this purpose. As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. Cheers, Doru > On Aug 18, 2016, at 1:32 PM, stepharo <stepharo(a)free.fr> wrote: > > Tx serge > > - I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily. > > So any idea instead of > <exp: value:> > > <expression: return: > > > withExtension: aString > > "Returns a new file reference with a different file extension" > > <exp: '/tmp/file.txt' asFileReference withExtension: 'log' > > value: '/tmp/file.log' asFileReference > > > ^ self withPath: (self path withExtension: aString) > > > - then incrementally we can start taking on system for example FS and use it. > > Stef > > > Le 18/8/16 Ã 11:51, Serge Stinckwich a Ã©crit : >> On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo(a)free.fr> wrote: >>> Hi guys >>> >>> I'm fed up to get methods without comments and without little examples. In >> +1 ! >> We can setup a small group of people interested to build examples at ESUG. >> >>> FileSystem, I wrote most of the comments and I tried to add an obvious >>> example: >>> >>> basenameWithIndicator >>> "Returns the basename with the indicator appended, i.e. >>> /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo >>> basenameWithIndicator is 'foo/'" >>> >>> ^ self basename , self indicator >>> >>> >>> Now let us look at: >>> >>> withExtension: aString >>> ^ self withPath: (self path withExtension: aString) >>> >>> >>> Nice comment :( >>> >>> I would like to support PythonDoctest (yes we are not the only one to have >>> ideas let us face is dear friends) >> +1 >> >> https://en.wikipedia.org/wiki/Doctest >> >>> def multiply(a, b): >>> """ >>> >>> multiply(4, 3) >>> 12 >>> >>> multiply('a', 3) >>> 'aaa' >>> """ >>> return a * b >>> >>> Because we can make sure that the comments are accurate. >>> >>> >>> withExtension: aString >>> >>> "Returns a new file reference with a different file extension" >>> >>> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >>> >>> value: '/tmp/file.log' asFileReference > >>> >>> ^ self withPath: (self path withExtension: aString) >>> >>> >>> It will help us to have a distinction between printOn: and displayString >>> >>> Typically >>> >>> '/tmp/file.txt' asFileReference withExtension: 'log' >>> >>> printString is bad >>> >>> since it returns File @ '/tmp/file.log' which is not an reexecutable >>> expression >>> >>> >>> >>> So let me know what you think. >>> - tell me that we have already test unit (yes the ones I wrote too) >>> => they do not have the same purpose >>> >>> For me this is getting to be important. >> Maybe a subset of Pharo could be defined as core with a kind of API >> freeze, so we can spend some time >> documenting the corresponding methods and classes. >> > > -- www.tudorgirba.com www.feenk.com "Every thing has its own flow."

Aug. 18, 2016

Re: [Pharo-dev] About PythonDocTest for Pharo

by stepharo

Tx serge - I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily. So any idea instead of <exp: value:> <expression: return: > withExtension: aString "Returns a new file reference with a different file extension" <exp: '/tmp/file.txt' asFileReference withExtension: 'log' value: '/tmp/file.log' asFileReference > ^ self withPath: (self path withExtension: aString) - then incrementally we can start taking on system for example FS and use it. Stef Le 18/8/16 Ã 11:51, Serge Stinckwich a Ã©crit : > On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo(a)free.fr> wrote: >> Hi guys >> >> I'm fed up to get methods without comments and without little examples. In > +1 ! > We can setup a small group of people interested to build examples at ESUG. > >> FileSystem, I wrote most of the comments and I tried to add an obvious >> example: >> >> basenameWithIndicator >> "Returns the basename with the indicator appended, i.e. >> /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo >> basenameWithIndicator is 'foo/'" >> >> ^ self basename , self indicator >> >> >> Now let us look at: >> >> withExtension: aString >> ^ self withPath: (self path withExtension: aString) >> >> >> Nice comment :( >> >> I would like to support PythonDoctest (yes we are not the only one to have >> ideas let us face is dear friends) > +1 > > https://en.wikipedia.org/wiki/Doctest > >> def multiply(a, b): >> """ >> >>> multiply(4, 3) >> 12 >> >>> multiply('a', 3) >> 'aaa' >> """ >> return a * b >> >> Because we can make sure that the comments are accurate. >> >> >> withExtension: aString >> >> "Returns a new file reference with a different file extension" >> >> <exp: '/tmp/file.txt' asFileReference withExtension: 'log' >> >> value: '/tmp/file.log' asFileReference > >> >> ^ self withPath: (self path withExtension: aString) >> >> >> It will help us to have a distinction between printOn: and displayString >> >> Typically >> >> '/tmp/file.txt' asFileReference withExtension: 'log' >> >> printString is bad >> >> since it returns File @ '/tmp/file.log' which is not an reexecutable >> expression >> >> >> >> So let me know what you think. >> - tell me that we have already test unit (yes the ones I wrote too) >> => they do not have the same purpose >> >> For me this is getting to be important. > Maybe a subset of Pharo could be defined as core with a kind of API > freeze, so we can spend some time > documenting the corresponding methods and classes. >

Aug. 18, 2016

Abotu FileReference objects as autoevaluating ones

by stepharo

about https://pharo.fogbugz.com/f/cases/18956/FileReference-printString-should-be… 'tmp/foo.txt' asFileReference > File @ tmp/foo.txt and it would be much much better to get back 'tmp/foo.txt' asFileReference So that we can get { 'tmp/foo.txt' asFileReference } > { 'tmp/foo.txt' asFileReference } and not "an Array(File @ tmp/foo.txt)" In addition we should turn the current printOn: method into a displayString method so that a list of fileReference can be well display with File @ tmp/foo.txt for example

Aug. 18, 2016

Re: [Pharo-dev] Experience with FileSystem => proposal for improving user experience

by stepharo

>>> Proposal two: >>> >>> We could add withoutBasename >>> >>> withoutBasename >>> >>> ^ self parent >>> >>> >>> I don't see a point of this method, why not just use #parent? >> This is a helper. >> parent is good for navigation now withoutBasename is good for manipulation >> of parts. >> It took me a while to think that I should use parent because I was looking >> for something else. > So the problem then is a documentational one. No I do not want to read a pdf to get it. > >> You convinced me this library is perfect and I will keep these extensions >> for me. > My point is, do we want to add every possible variation and helper for every use case a person can think of? > I believe last year there was a lot of effort put into cleaning up String api; did String end up where it is with similar approach? I don't know, I haven't been here, that's why I am asking. > > Also in other languages it is common to use `dirname` instead of parent => "asking for the directory name of what you have". > > But as you point out in another thread, this is a documentational issue, and not a missing method. I do not want to be forced to read a doc to use a system. The system itself should be discoverable and it is not in this case. This is why I will not write documentation of others code anymore. >>> Proposal three: >>> >>> Not sure that it is worth >>> >>> (note that this is not a rename) >>> >>> withNewExtension: anExtension >>> ^ self parent / self basenameWithoutExtension >>> withExtension: anExtension >>> >>> >>> Is this somehow different than using #withExtension: directly? >> Obviously since I'm with Sven one of the few persons that seem concerned >> with such aspect. > Please, just so there is no misunderstanding. I do care about it and I am not fundamentally against it. > You sent your proposals, I've added my view, and I expect other people will add theirs, so we can collectively discuss this and act on it. You see I could have pushed this change without discussing. I can understand that proposal 3 is useless since this is the same. But the others have a value to me. Now I added them in my private extensions and this is good. > > Peter > >

Aug. 18, 2016

Re: [Pharo-dev] About PythonDocTest for Pharo

by Serge Stinckwich

On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo(a)free.fr> wrote: > Hi guys > > I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG. > FileSystem, I wrote most of the comments and I tried to add an obvious > example: > > basenameWithIndicator > "Returns the basename with the indicator appended, i.e. > /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo > basenameWithIndicator is 'foo/'" > > ^ self basename , self indicator > > > Now let us look at: > > withExtension: aString > ^ self withPath: (self path withExtension: aString) > > > Nice comment :( > > I would like to support PythonDoctest (yes we are not the only one to have > ideas let us face is dear friends) +1 https://en.wikipedia.org/wiki/Doctest > def multiply(a, b): > """ > >>> multiply(4, 3) > 12 > >>> multiply('a', 3) > 'aaa' > """ > return a * b > > Because we can make sure that the comments are accurate. > > > withExtension: aString > > "Returns a new file reference with a different file extension" > > <exp: '/tmp/file.txt' asFileReference withExtension: 'log' > > value: '/tmp/file.log' asFileReference > > > ^ self withPath: (self path withExtension: aString) > > > It will help us to have a distinction between printOn: and displayString > > Typically > > '/tmp/file.txt' asFileReference withExtension: 'log' > > printString is bad > > since it returns File @ '/tmp/file.log' which is not an reexecutable > expression > > > > So let me know what you think. > - tell me that we have already test unit (yes the ones I wrote too) > => they do not have the same purpose > > For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes. -- Serge Stinckwich UCBN & UMI UMMISCO 209 (IRD/UPMC) Every DSL ends up being Smalltalk http://www.doesnotunderstand.org/

Aug. 18, 2016

Re: [Pharo-dev] Experience with FileSystem => proposal for improving user experience

by Peter Uhnak

On Thu, Aug 18, 2016 at 09:35:28AM +0200, stepharo wrote: Just so you don't misunderstandâ¦ I am not opposing those changes, I am just asking. > > > > Proposal one: > > > > We could add withoutExtension > > > > withoutExtension > > > > ^ (self parent / self basenameWithoutExtension) > > > > > > What is the use case for this? > To get everything except the extension. Is it not obvious? > How do you did it else? What I mean is, when would you use such method? The only use case I can see (after using FS libs for years) is to change extension, but we already have a method for that. > > > Proposal two: > > > > We could add withoutBasename > > > > withoutBasename > > > > ^ self parent > > > > > > I don't see a point of this method, why not just use #parent? > This is a helper. > parent is good for navigation now withoutBasename is good for manipulation > of parts. > It took me a while to think that I should use parent because I was looking > for something else. So the problem then is a documentational one. > You convinced me this library is perfect and I will keep these extensions > for me. My point is, do we want to add every possible variation and helper for every use case a person can think of? I believe last year there was a lot of effort put into cleaning up String api; did String end up where it is with similar approach? I don't know, I haven't been here, that's why I am asking. Also in other languages it is common to use `dirname` instead of parent => "asking for the directory name of what you have". But as you point out in another thread, this is a documentational issue, and not a missing method. > > > > Proposal three: > > > > Not sure that it is worth > > > > (note that this is not a rename) > > > > withNewExtension: anExtension > > ^ self parent / self basenameWithoutExtension > > withExtension: anExtension > > > > > > Is this somehow different than using #withExtension: directly? > Obviously since I'm with Sven one of the few persons that seem concerned > with such aspect. Please, just so there is no misunderstanding. I do care about it and I am not fundamentally against it. You sent your proposals, I've added my view, and I expect other people will add theirs, so we can collectively discuss this and act on it. Peter

Aug. 18, 2016