Export Smalltalk code to the exercism exercise directory

[samWson]

User story

As a user, given that:

• I have completed my solution to an exercise

I want to:

• Export my code solution from the Pharo image into text files
• The text files should be in the exercise directory
• The text files should be ready to push to Exercism.io using the exercism command line tool

Related to this issue and this issue.

Description

Two files will need to be exported. One is untouched from the file out process. It needs to stay this way to allow the code to file in to another Pharo image. The second file will be scrubbed of machine readable artifacts and meta data for the sake of readability. This human readable file is what will be displayed on the Exercism.io website. The machine readable file will still need to be uploaded to Exercism.io, to enable other users to download and file in the code to their image.

After the code has been exported from the Pharo image, the directory structure should look something like tree below assuming this is the Hello World exercise:

hello-world/
├── .ghost
│   ├── hello-world-test.st
│   └── hello-world.st
├── hello-world-test.st
└── hello-world.st

The files in the .ghost directory are the machine readable files. The directory is hidden because the code in them should never be edited outside a Pharo image, else they may no longer be machine readable. The directory is named .ghost for lack of a better name and can change later. The human readable files are in the root of the hello-world directory.

Assumptions

• The directory structure will be created when the user enters exercism fetch pharo <exercise-name>
• The *-test.st files will be downloaded from Exercism.io when the fetch command is used

[samWson]

It's been about a week since I got started on this issue so I will add a quick update.

It took some research, a bit of hacking, and now I have a prototype export tool for this issue. I'll push the code here for review tomorrow or the next day (after sleep).

For interest I discovered Pharo's format for filed out Smalltalk code. It's called Chunk format. Basically it's strings of code inside double bangs ! !. The CodeChunk abstract class and its sub-classes, as well as the CodeImporter class are all related to this process.

[samWson]

Merge request #2 pushed. A few tasks are left to be done. I'll leave the merge request up for a few days so others can comment and review. Be sure to read the comments on the merge request for more details.

[bencoman]

Good idea introducing ExercismTest, but I don't think it needs its own package/category. In itself own right, it is a tool.

Also I'm presuming that solutions to some exercises may require multiple classes, so I believe each exercise should be a package. i.e. the exporter should export a package rather than a class.
I propose exercise packages be called: Exercism-HelloWorld, Exercism-Gigasecond, Exercism-Dominos, etc.

Other languages have a convention of a class-per-file, so the exercise directory could contain several files a directory holding multiple classes. For comparison, downloading the Gigasecond exercise for Go shows three *.go files: gigasecond.go; gigasecond_test.go; and cases_test.go

Now if the ExercismPharoTooling repo is installed first, and contains an empty package "Exercism", then all later installed exercises "should" install into a subtree under Exercism (needs to be tested), which will help keep things neat.

As an example of the structure I propose, do the following in a clean image:

Object subclass: #Exercism
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'ExercismPharoTooling'.

TestCase subclass: #ExercismTest
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'ExercismPharoTooling'.

RPackageOrganizer default createPackageNamed: 'Exercism'.

Object subclass: #EXHelloWorld
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Exercism-HelloWorld'.

ExercismTest subclass: #EXHelloWorldTest
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Exercism-HelloWorld'.

Object subclass: #EXDominos
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Exercism-Dominos'.

ExercismTest subclass: #EXDominosTest
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Exercism-Dominos'.

btw, given @macta's demonstration of snapshotting a package to Tonel format, I guess the current PR is out of date(?)

[samWson]

Good idea introducing ExercismTest, but I don't think it needs its own package/category. In itself own right, it is a tool.

@bencoman I thought appending -Test on the end of a package name made it a sort of sub-category. In any case I don't mind including tests with the tested classes in a single package, especially when the project is so small.

Also I'm presuming that solutions to some exercises may require multiple classes, so I believe each exercise should be a package. i.e. the exporter should export a package rather than a class. I propose exercise packages be called: Exercism-HelloWorld, Exercism-Gigasecond, Exercism-Dominos, etc.

I completely agree with you here. Also using the hyphen - for naming the packages seems to visually group all the packages as sub-packages under Exercism. It's makes a nice visual hierachy in the Nautilus browser window.

Now if the ExercismPharoTooling repo is installed first, and contains an empty package "Exercism", then all later installed exercises "should" install into a subtree under Exercism (needs to be tested), which will help keep things neat.

The only problem I have with this is how the current exercism command line tool will find the directory under which all exercises are placed. Will we need to do any modification to the exercism tools to make this happen? If so why not instead just keep it to the current convention in all other language tracks and have the ExercismPharoTooling repo inside HOME/exercism/pharo/ along with all the other exercises?

Question: why subclass ExercismTest for the exercise test cases e.g. EXHelloWorldTest instead of TestCase.

btw, given @macta's demonstration of snapshotting a package to Tonel format, I guess the current PR is out of date(?)

Yes. I'll leave it in place for a few days then close it. If nothing else it shows the high level intent of what I wanted, even if the implementation is now obsolete. Since it looks like using Tonel will be easy I much prefer to use it over the double handling I was doing with chunk format.

[macta]

Guys - I don't think we need to overthink this. As mentioned in the discussion on Prefixes, we are talking 1 - 5 classes at most for these exercises.

I see no real driver for a special ExercismTest - TestCase should be fine shouldn't it? I would stick everything into a single Package (easy to import/export - keeps it easy to review etc.).

I think we've also agree there is no reason for a .ghost directory now.

I'd like to see us get 5-10 exercises working, so we can get a few colleagues to try it out (before launching). They should be really simple.

We should be able to get a simple Exercism world menu (to bring an exercise in), and a context menu on package (to get an Exercise out). And in terminal I should be able to do the exercism submit myex*.st just to get it working.

We can then see about getting tools to avoid the command line (although maybe for the audience - they might like to see the command line?)

[bencoman]

Question: why subclass ExercismTest for the exercise test cases e.g. EXHelloWorldTest instead of TestCase.

Ahhh. I misundertood. @samWson, I thought that was your intent with the ExercismTest class in the PR. I now properly noticed its comment "I am the test suite for the Exercism Pharo Tooling" Before I read your PR I was just subclassing from TestCase, and I withdraw that suggestion. Using "TestCase" is actually better for students to get used to using.

[samWson]

There is definitely no reason for .ghost directory now. By using Tonel as our file format we have one file for machine reading and human reading. Having said that there might be a need for a meta directory in the exercises themselves to hold reference solutions: see the guide here if you haven't already.

I don't see us making a huge amount of tools, so I agree keeping things to one package/category is a good choice.

We should be able to get a simple Exercism world menu (to bring an exercise in), and a context menu on package (to get an Exercise out). And in terminal I should be able to do the exercism submit myex*.st just to get it working.

@macta Would you like to take on this task? I liked the simple solution you showed us for exporting to Tonel files earlier. I don't have any experience extending the world menu. If you want to, go ahead and open any issues you need to track progress, or use this issue here.

[macta]

@samWson sure, I'll have a crack at this (my schedule is a bit hairy at the moment, but I'd really like to get something going particularly as I've got a energetic colleague who is keen to improve his smalltalk and he's done many of the Ruby exercism's and was willing to port some over)

[macta]

@samWson - ok check out this repo: https://gitlab.com/macta/Exercism - instructions on how to download and install it in the readme. We can fold it into the proper place - this just made it easy for me to try something out. But I need access to the exercism/pharo to sent exercism commands to see how it will load. The example I created loads a helloworld in automatically - we possibly wouldn't do that. But you can see how save works (and tries to do a submit) and fetch works (it loads the code you save for now)

Confession: only 1 test, but didn't see the point of testing until I have a sandbox to test against the right things - so this is really a spike

[samWson]

@macta cool! I like what you have done there. I have an idea of your intent now. I'm impressed at what you have working in such a short time.

I like that you have managed to integrate exercism push/fetch into the UI and ignore using the command line completely. I thought that would be much more difficult to do.

Take your time on this. If your schedule is too busy, put this project at the bottom of your priorities. I'll assign this issue to you if you are happy with it. I'll get onto doing some of the other tasks on the long list to getting this language track up and running.

[macta]

I think we can close this issue now (and possibly close this repo - as we've got everything running in the standard exercism/pharo repo).

Aside - its interesting that your intuition of .ghost (at the top) was correct - we've ended up with a .pharo to dump the tonel output into for exercise submissions)

[samWson]

Aside - its interesting that your intuition of .ghost (at the top) was correct - we've ended up with a .pharo to dump the tonel output into for exercise submissions)

I got the idea from Exercism's own guide for making language tracks. I think the term was more like meta or something similar that might clash with Smalltalk in a way.

I'll close this issue down now, and archive the repository.