fix: Get repository working again

The main actions taking to restore spoofax_prop to correct operation
   are not really reflected in this commit; they consisted of
   switching to a Spoofax distribution of Eclipse and
updating/rebuilding
   the project in various ways. However, all of the steps are now
   documented here, and the narrative is extended to include the
   first examples.

   Resolves #1.
This commit is contained in:
Glen Whitney 2021-01-14 10:19:35 -08:00
parent ba6084513f
commit 8536d6a469
5 changed files with 67 additions and 64 deletions

1
.gitignore vendored
View File

@ -5,6 +5,7 @@
/site
/.classpath
/.project
/.settings
/.factorypath

View File

@ -1,48 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>spoofax_prop</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.m2e.core.maven2Builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.metaborg.spoofax.eclipse.meta.builder.generatesources</name>
<triggers>clean,full,</triggers>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.metaborg.spoofax.eclipse.builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.metaborg.spoofax.eclipse.meta.builder.prejava</name>
<triggers>clean,full,</triggers>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.metaborg.spoofax.eclipse.meta.builder.postjava</name>
<triggers>clean,full,</triggers>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.m2e.core.maven2Nature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.metaborg.spoofax.eclipse.nature</nature>
<nature>org.metaborg.spoofax.eclipse.meta.nature</nature>
</natures>
</projectDescription>

View File

@ -1,20 +1,63 @@
Title: The Spoofax Propositional Language
Next: syntax/Spoofax-Propositional-Language.sdf3
# Stratego Transformations in the Spoofax Eclipse IDE
The Stratego Tutorial/Reference {! docrefs/manual.md !} in the official Spoofax documentation presents a comprehensive overview of the Stratego approach to abstract syntax tree (AST) transformations. It employs a running example of an abstract syntax intended to represent classical Propositional Logic, which we will dub here the "Spoofax Propositional Language." The manual introduces the concepts of rules and strategies for applying them, and then shows how both of those facilities can be created from more primitive operations of term matching and replacement. Every step of the way is illustrated with actual, working Stratego programs.
The Stratego Tutorial/Reference {! docrefs/manual.md !} in the official Spoofax
documentation presents a comprehensive overview of the Stratego approach to
abstract syntax tree (AST) transformations. It employs a running example of an
abstract syntax intended to represent classical Propositional Logic, which we
will dub here the "Spoofax Propositional Language." The manual introduces the
concepts of rules and strategies for applying them, and then shows how both
of those facilities can be created from more primitive operations of
term matching and replacement. Every step of the way is illustrated with actual,
working Stratego programs.
There are, however, two catches for a newcomer trying to learn Spoofax and Stratego for the first time:
There are, however, two catches for a newcomer trying to learn Spoofax and
Stratego for the first time:
1. All of the examples are worked in an older framework ("Stratego/XT") which has a rather different collection of tools than the current implementation of Spoofax in the Eclipse IDE.
1. Unlike with the Calc example language used for the explication of the Syntax Definition Language SDF3, there does not seem to be any publicly available repository containing the worked examples to follow along with.
1. All of the examples are worked in an older framework ("Stratego/XT") which
has a rather different collection of tools than the current implementation
of Spoofax in the Eclipse IDE.
1. Unlike with the Calc example language used for the explication of the
Syntax Definition Language SDF3, there does not seem to be any publicly
available repository containing the worked examples to follow along with.
This [Gitea repository](https://code.studioinfinity.org/glen/spoofax_prop) aims to fill both gaps. It can be cloned as an Eclipse project (note the git root is at the project level rather than in the directory above the project, as may be more common; in other words, this repository should be cloned within an existing Eclipse workspace, rather than as the workspace itself). Within that project, (ultimately) every example from the Stratego Tutorial manual starting from Section 4 on can be executed directly. And this (Mkdocs-generated) documentation seeks to clarify the ways that Stratego transformations may be run in the Spoofax/Eclipse IDE environment, serving as a supplement/replacement for the portions of the manual that were specific to Stratego/XT.
## Preliminaries
I recommend working with a complete pre-built Eclipse installation of Spoofax
as provided by the Spoofax project,
for example one that you can download from their
[development release page](https://www.metaborg.org/en/latest/source/release/development.html).
I have been unable to get the examples in this repository working starting from
plain Eclipse and installing Spoofax in it using the Spoofax update site.
If at any point in using the examples things appear to stop working, and
especially if the Spoofax menu item disappears or the Spoofax menu turns into
a thin white rectangle with no items to select, try the following:
* Build the project and try again.
* Clean the workspace, and when it is done, build the project again and try
again.
* Right click on the project, select Maven > Update Project, make sure
everything is checked except "Offline" and
"Force update of Snapshots/Releases", and then click "OK". When it is done,
clean the workspace, then build the project and try again.
* If that still hasn't done it, restart (the Spoofax version of!) Eclipse and
clean the workspace, then build the project and try again.
Running with a version of Spoofax _later_ than 2.5.13 (I was using a 2.6.0
development snapshot), the Spoofax menu would always come back into proper
operation at some point in the above process.
## Abstract syntax
Let's begin by recalling the abstract syntax of the Spoofax Propositional Language (SPL), as defined at the top of {! docrefs/sec4.1.md !} of the manual. It consists of the following signature of constructors:
With the preliminaries out of the way, let's begin delving into Stratego
transformations by recalling the abstract syntax of the
Spoofax Propositional Language (SPL), as defined
at the top of {! docrefs/sec4.1.md !} of the manual.
It consists of the following signature of constructors:
```stratego
{! src-gen/signatures/Spoofax-Propositional-Language-sig.str ---
@ -23,4 +66,6 @@ Let's begin by recalling the abstract syntax of the Spoofax Propositional Langua
!}
```
<!-- /md -->
Continue reading in the latest released [SPL documentation](http://studioinfinity.org/SPL) to see how to define and run Stratego transformations on ASTs of this language.
Continue reading in the latest released
[SPL documentation](http://studioinfinity.org/SPL)
to see how to define and run Stratego transformations on ASTs of this language.

View File

@ -1,7 +1,4 @@
module Manual
menus
menu: "Manual" (openeditor)
action: "prop-eval" = do-eval
action: "prop-eval" = do-eval (source)

View File

@ -4,7 +4,7 @@ Title: Running a Strategy
## Running a Strategy
The first example of running a Stratego strategy
in the {! ../docrefs/manual.md !} } is that of _evaluating_ an AST,
in the {! ../docrefs/manual.md !} is that of _evaluating_ an AST,
via the `prop-eval-rules` module in {! ../docrefs/sec4.1.md !}. This page
describes the most straightforward way to run this same strategy
in the Spoofax Eclipse IDE.
@ -87,7 +87,7 @@ It's just the one line `Manual` in the `imports` section that we have added. The
{! ../editor/Manual.esv !}
```
Note that the quoted string on the `action` line is the text label of the menu
item in the "Manual" submenu, and the identifier on its right-hand side is the
item in the "Manual" submenu, and the first identifier on its right-hand side is the
Stratego action to call. But note that `do-eval` is not the same identifier as
`eval` in our last Stratego file above. That's because the Stratego invocation
caused by an ESV action item has a specific, multi-item argument list, whereas
@ -129,7 +129,15 @@ file `syntax/examples/sec4.1_test1.spl`:
{! ../syntax/examples/sec4.1_test1.spl !}
```
and select "Spoofax > Manual > prop-eval" from the menu bar to produce:
[CONTINUE HERE ONCE THIS WORKS]
```
{! ../syntax/examples/sec4.1_test1.eval.aterm !}
```
You can do the same with test2:
```SPL
{! ../syntax/examples/sec4.1_test2.spl !}
```
to produce
```
{! ../syntax/examples/sec4.1_test2.eval.aterm !}
```
**/