README.md 11.2 KB
Newer Older
1
[![Maven Central](https://img.shields.io/maven-central/v/fr.inria.gforge.spoon/spoon-core.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22fr.inria.gforge.spoon%22%20AND%20a%3A%22spoon-core%22)
2
[![GHA tests Workflow Status](https://github.com/INRIA/spoon/actions/workflows/tests.yml/badge.svg)](https://github.com/INRIA/spoon/actions/workflows/tests.yml)
3
[![Coverage Status](https://coveralls.io/repos/INRIA/spoon/badge.png)](https://coveralls.io/r/INRIA/spoon)
4
[![Maintainability Rating](https://sonarqube.ow2.org/api/project_badges/measure?project=fr.inria.gforge.spoon%3Aspoon-core&metric=sqale_rating)](https://sonarqube.ow2.org/dashboard?id=fr.inria.gforge.spoon%3Aspoon-core)
5

6
# Spoon
Martin Monperrus's avatar
Martin Monperrus committed
7

8 9 10 11 12
Spoon is an open-source library to analyze, rewrite, transform, transpile Java source code. It parses source files to build a well-designed AST with powerful analysis and transformation API. It fully supports modern Java versions up to Java 11, 12, 13, 14. Spoon is an official Inria open-source project, and member of the [OW2](https://www.ow2.org/) open-source consortium.

## Documentation

The latest official documentation is available at <http://spoon.gforge.inria.fr/> and a regularly updated PDF version is as <https://projects.ow2.org/download/spoon/WebHome/spoon-user-manual.pdf>.
Martin Monperrus's avatar
Martin Monperrus committed
13

14 15
### Academic usage

16
If you use Spoon for academic purposes, please cite: Renaud Pawlak, Martin Monperrus, Nicolas Petitprez, Carlos Noguera, Lionel Seinturier. “[Spoon: A Library for Implementing Analyses and Transformations of Java Source Code](https://hal.archives-ouvertes.fr/hal-01078532/document)”. In Software: Practice and Experience, Wiley-Blackwell, 2015. Doi: 10.1002/spe.2346.
Martin Monperrus's avatar
Martin Monperrus committed
17 18 19

```
@article{pawlak:hal-01169705,
20
  TITLE = "{Spoon: A Library for Implementing Analyses and Transformations of Java Source Code}",
Martin Monperrus's avatar
Martin Monperrus committed
21
  AUTHOR = {Pawlak, Renaud and Monperrus, Martin and Petitprez, Nicolas and Noguera, Carlos and Seinturier, Lionel},
22 23
  JOURNAL = "{Software: Practice and Experience}",
  PUBLISHER = "{Wiley-Blackwell}",
24 25 26
  PAGES = {1155-1179},
  VOLUME = {46},
  URL = {https://hal.archives-ouvertes.fr/hal-01078532/document},
Martin Monperrus's avatar
Martin Monperrus committed
27 28 29 30
  YEAR = {2015},
  doi = {10.1002/spe.2346},
}
```
martin's avatar
martin committed
31

32 33 34
### Professional support

If you need professional support on Spoon (development, training, extension), you are welcome to post a comment on https://github.com/INRIA/spoon/issues/3251
35

36
## Getting started in 2 seconds
37

38
Get latest stable version with Maven, see <https://search.maven.org/artifact/fr.inria.gforge.spoon/spoon-core>
39

40 41 42 43
And start using it:

```java
CtClass l = Launcher.parseClass("class A { void m() { System.out.println(\"yeah\");} }");
44 45
```

46 47 48 49 50 51
Documentation:

- Reference documentation: <http://spoon.gforge.inria.fr/> (contains the content of the [doc folder](https://github.com/INRIA/spoon/tree/master/doc))
- Code examples: <https://github.com/SpoonLabs/spoon-examples>
- Videos: [Spoon: Getting Started - Simon Urli @ OW2Con'18 (Paris)](https://www.youtube.com/watch?v=ZZzdVTIu-OY), [Generate Test Assertion with Spoon - Benjamin Danglot @ OW2Con'17 (Paris)](https://www.youtube.com/watch?v=JcCIbjnkfD4)

52 53

## Contributing in 2 seconds
54

55
Create your first pull-request to improve the documentation, see [doc](https://github.com/INRIA/spoon/tree/master/doc)! Proceed with your first bug fix! The community is open-minded, respectful and patient. All external contributions are welcome.
Martin Monperrus's avatar
Martin Monperrus committed
56

57
## Design Philosophy
Martin Monperrus's avatar
Martin Monperrus committed
58 59 60 61 62 63 64 65 66 67 68 69 70

R1) The Spoon metamodel is as close as possible to the language concepts.

R2) The Spoon model of a program is complete and sound.

R3) The text version of a Spoon model is well-formed and semantically equivalent to the original program.

R4) The analysis and transformation API is intuitive and regular.

R5) Transformation operators are designed to warn as fast as possible about invalid programs. This is done either with static type checking or with dynamic checks when the operators are used.

R6) When feasible, the text version of a Spoon model is close to the original one.

71
### Compiling
Martin Monperrus's avatar
Martin Monperrus committed
72

73
To compile Spoon, you need a Java Development Kit (JDK) and Maven:
74

75 76 77 78 79 80 81 82 83 84
```
git clone https://github.com/INRIA/spoon
cd spoon
mvn compile
```

To run the tests:
```
mvn test
```
85

86
### Download
87

88
Latest version: <https://search.maven.org/remote_content?g=fr.inria.gforge.spoon&a=spoon-core&v=LATEST&c=jar-with-dependencies> - [Javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/index.html)
Martin Monperrus's avatar
Martin Monperrus committed
89

90
Maven:
91

92 93 94 95
```xml
<dependency>
    <groupId>fr.inria.gforge.spoon</groupId>
    <artifactId>spoon-core</artifactId>
96
    <!-- See rendered release value at http://spoon.gforge.inria.fr/ -->
97 98 99
    <version>{{site.spoon_release}}</version>
</dependency>
```
aryan's avatar
aryan committed
100

101 102 103
## Releases

<!-- .* Marker comment. -->
104 105
- July 2020: Spoon 8.2.0 [(changelog)](https://github.com/INRIA/spoon/pull/3501)
- March 2020: Spoon 8.1.0 [(changelog)](https://github.com/INRIA/spoon/pull/3310)
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
- November 2019, Spoon 8.0.0 [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-8.0.0)
- July 2019: Spoon 7.5.0 is released [(changelog)](https://github.com/INRIA/spoon/pull/3057)
- May 2019: Spoon 7.4.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-7.4.0)
- Februray 10, 2019: Spoon 7.3.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-7.3.0) 
- December 4, 2018: Spoon 7.2.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-7.2.0) 
- October 10, 2018: Spoon 7.1.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-7.1.0) 
- July 4, 2018: Spoon 7.0.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-7.0.0) 
- March 8, 2018: Spoon 6.2.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-6.2.0)
- December 20, 2017: Spoon 6.1.0 is released, merry christmas! :christmas_tree: [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-6.1.0)
- November 17, 2017: Spoon 6.0.0 is released! Check the [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-6.0.0) as there are few non backward-compatible changes :warning:
- September 6, 2017: Spoon 5.9.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.9.0) *back-to-work* release!
- July 11, 2017: Spoon 5.8.0 is released  [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.8.0) Summer release :beer: To be prefered wrt the previous one: fix lot of bugs.
- June 01, 2017: Spoon 5.7.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.7.0)
- March 16, 2017: Spoon 5.6.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.6.0) Spring release :-)
- January 11, 2017: Spoon 5.5.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.5.0). Happy new year!
- October 27, 2016: Spoon 5.4.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.4.0).
- September 19, 2016: Spoon 5.3.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.3.0).
- June 30, 2016: Spoon 5.2.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.2.0).
- June 22, 2016: Spoon 5.1.1 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.1.1).
- March 21, 2016: Spoon 5.1.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.1.0).
- February 12, 2016: Spoon 5.0.2 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.0.2).
- February 3, 2016: Spoon 5.0.1 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.0.1).
- January 25, 2016: Spoon 5.0.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.0.0).
- November 18, 2015: Spoon 4.4.1 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-5.5.0).
- November 16, 2015: Spoon 4.4.0 is released [(changelog)](https://github.com/INRIA/spoon/releases/tag/spoon-core-4.4.0).
- September 22, 2015: Spoon 4.3.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2015-September/001803.html).
- June 15, 2015: Spoon 4.2.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2015-June/001781.html).
- May 7, 2015: Spoon 4.1.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2015-May/001774.html).
- April 8, 2015: Spoon 4.0.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2015-April/001769.html).
- February 11, 2015: Spoon 3.1 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2015-February/001741.html).
- December 9, 2014: Spoon 3.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2014-December/001721.html).
- November 12, 2014: Spoon 2.4 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2014-November/001710.html).
- October 9, 2014: Spoon 2.3.1 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2014-October/001688.html).
- September 12, 2014: Spoon 2.1 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2014-September/001683.html).
- April 2, 2014: Spoon 2.0 is released [(changelog)](https://lists.gforge.inria.fr/pipermail/spoon-discuss/2014-March/001639.html).
- September 30, 2013: Spoon 1.6 is released.
- April 12, 2012: Spoon 1.5 is released.
143

144 145 146
## License

Spoon is Free and Open Source, double-licensed under the ([CeCILL-C license](https://cecill.info/licences.en.html) - French equivalent to LGPL) and the MIT license.
147

148
## Github Contributors
martin's avatar
martin committed
149

150
This list is generated by `chore/generate-contributor-list.py`. If you're not listed or you'd like to have your full name, please post to https://github.com/INRIA/spoon/issues/3909.
martin's avatar
martin committed
151

152 153 154 155 156 157 158 159 160
* adamjryan
* Alcides Fonseca
* Alexander Shopov
* André Cruz
* andrewbwogi
* Antoine Mottier
* argius
* Arnaud Blouin
* Artamm
161
* Artur Bosch
162 163 164
* aryan
* Ashutosh Kumar Verma
* aveuiller
martin's avatar
martin committed
165
* Benoit Cornu
166
* Benjamin DANGLOT
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
* César Soto Valero
* Charm
* ChrisSquare
* Christopher Stokes
* Clemens Bartz
* Clément Fournier
* Darius Sas
* Diorcet Yann
* dufaux
* dwayneb
* dya-tel
* Eddie T
* Egor Bredikhin
* Fabien DUMINY
* fangzhen
182
* Fan Long
183 184 185 186 187 188 189 190 191 192 193 194 195
* fav
* Fernanda Madeiral
* Filip Krakowski
* Gérard Paligot
* gibahjoe
* GluckZhang
* Gregor Zeitlinger
* Haris Adzemovic
* HectorSM
* Horia Constantin
* jakobbraun
* Jan Galinski
* jon
196
* Kai Luo
197 198 199 200 201
* Lakshya A Agrawal
* leventov
* Lionel Seinturier
* lodart
* Lukas Krejci
202
* Luke Merrick
203 204
* Marcel Manseer
* Marcel Steinbeck
martin's avatar
martin committed
205
* Martin Monperrus
206 207 208 209 210 211 212 213 214 215 216
* MartinWitt
* Matias Martinez
* Maxime CLEMENT
* Maxim Stefanov
* Mehdi Kaytoue
* Michael Täge
* Mickael Istria
* Miguel Sozinho Ramalho
* Mikael Forsberg
* Muhammet Ali AKBAY
* Nicolas Harrand
martin's avatar
martin committed
217
* Nicolas Petitprez
218 219 220 221 222
* Noah Santschi-Cooney
* Carlos Noguera
* Ondřej Šebek
* Pavel Vojtechovsky
* peroksid90
223
* Phillip Schichtel
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
* Quentin LE DILAVREC
* raymogg
* Renaud Pawlak
* Rhys Compton
* Rick Kellogg
* Rijnard van Tonder
* Rohitesh Kumar Jain
* Roman Leventov
* santos-samuel
* scootafew
* Scott Dickerson
* Scott Pinwell
* Sébastien Bertrand
* Sergey Fedorov
* Shantanu
* Simon Larsén
240
* Simon Urli
241 242
* srlm
* ST0NEWALL
243
* Stefan Wolf
244 245 246 247 248 249 250 251 252 253 254
* Thomas Durieux
* tiagodrcarvalho
* Tomasz Zieliński
* Urs Keller
* Vincenzo Musco
* Wolfgang Schmiesing
* Wouter Smeenk
* Wreulicke
* Yann Diorcet
* Zhang Xindong
* Дмитрий