diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml index d912f051c4..3743c5780e 100644 --- a/.github/workflows/markdown-lint.yml +++ b/.github/workflows/markdown-lint.yml @@ -4,6 +4,10 @@ on: push: branches: - master + pull_request: + branches: + - master + paths-ignore: [ 'paper/**', 'sandbox/**' ] concurrency: group: markdown-lint-${{ github.ref }} cancel-in-progress: true diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000000..7bf567f1ae --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,16 @@ +# Default state for all rules +default: true + +# Line length : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md +MD013: + line_length: 100 + +# Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md033.md +MD033: + allowed_elements: [img] + +# Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md040.md +MD040: false + +# First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md041.md +MD041: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 459aa58560..0cd469c6e8 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -118,12 +118,12 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](here). -Community Impact Guidelines were inspired by +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org -For answers to common questions about this code of conduct, see the -[FAQ](https://www.contributor-covenant.org/faq). -Translations are available +For answers to common questions about this code of conduct, see the +[FAQ](https://www.contributor-covenant.org/faq). +Translations are available [https://www.contributor-covenant.org/translations](here). diff --git a/README.md b/README.md index f531fc29f3..cf655191f2 100644 --- a/README.md +++ b/README.md @@ -32,26 +32,26 @@ they are good enough, including: [C#](https://en.wikipedia.org/wiki/C_Sharp_%28programming_language%29). All of them have something **we don't tolerate**: - * types ([why?](https://www.yegor256.com/2020/11/10/typing-without-types.html)) - * static/class methods or attributes ([why?](http://www.yegor256.com/2014/05/05/oop-alternative-to-utility-classes.html)) - * classes ([why?](http://www.yegor256.com/2016/09/20/oop-without-classes.html)) - * implementation inheritance ([why?](http://www.yegor256.com/2016/09/13/inheritance-is-procedural.html)) - * mutability ([why?](http://www.yegor256.com/2014/06/09/objects-should-be-immutable.html) and [why not?](https://www.yegor256.com/2016/09/07/gradients-of-immutability.html)) - * NULL ([why?](http://www.yegor256.com/2014/05/13/why-null-is-bad.html)) - * global scope ([why?](https://www.yegor256.com/2018/07/03/global-variables.html)) - * type casting ([why?](http://www.yegor256.com/2015/04/02/class-casting-is-anti-pattern.html)) - * reflection ([why?](https://www.yegor256.com/2022/06/05/reflection-means-hidden-coupling.html)) - * scalar types and data primitives - * annotations ([why?](http://www.yegor256.com/2016/04/12/java-annotations-are-evil.html)) - * operators - * traits and mixins ([why?](https://www.yegor256.com/2017/03/07/traits-and-mixins.html)) - * flow control statements (`for`, `while`, `if`, etc) - * [syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar) ([why?](https://github.com/objectionary/eo/issues/51)) +* types ([why?](https://www.yegor256.com/2020/11/10/typing-without-types.html)) +* static/class methods or attributes ([why?](http://www.yegor256.com/2014/05/05/oop-alternative-to-utility-classes.html)) +* classes ([why?](http://www.yegor256.com/2016/09/20/oop-without-classes.html)) +* implementation inheritance ([why?](http://www.yegor256.com/2016/09/13/inheritance-is-procedural.html)) +* mutability ([why?](http://www.yegor256.com/2014/06/09/objects-should-be-immutable.html) and [why not?](https://www.yegor256.com/2016/09/07/gradients-of-immutability.html)) +* NULL ([why?](http://www.yegor256.com/2014/05/13/why-null-is-bad.html)) +* global scope ([why?](https://www.yegor256.com/2018/07/03/global-variables.html)) +* type casting ([why?](http://www.yegor256.com/2015/04/02/class-casting-is-anti-pattern.html)) +* reflection ([why?](https://www.yegor256.com/2022/06/05/reflection-means-hidden-coupling.html)) +* scalar types and data primitives +* annotations ([why?](http://www.yegor256.com/2016/04/12/java-annotations-are-evil.html)) +* operators +* traits and mixins ([why?](https://www.yegor256.com/2017/03/07/traits-and-mixins.html)) +* flow control statements (`for`, `while`, `if`, etc) +* [syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar) ([why?](https://github.com/objectionary/eo/issues/51)) ## Quick Start First, install [Java SE](https://www.oracle.com/java/technologies/downloads/), -[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), +[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), [Rust with Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) and [eoc](https://github.com/objectionary/eoc). @@ -66,13 +66,13 @@ Then, start with a simple EO program in `app.eo` file: Compile it like this (may take a minute or so): ``` -$ eoc link +eoc link ``` Then, run it: ``` -$ eoc --alone dataize app +eoc --alone dataize app ``` You should see "Hello, world!" printed. @@ -189,8 +189,8 @@ This is the [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_fo ENBF of 𝜑-calculus -The images were [auto-generated](https://github.com/objectionary/eo/actions/workflows/ebnf.yml). -It's better to use [ebnf/Eo.svg](https://www.eolang.org/ebnf/Eo.svg) +The images were [auto-generated](https://github.com/objectionary/eo/actions/workflows/ebnf.yml). +It's better to use [ebnf/Eo.svg](https://www.eolang.org/ebnf/Eo.svg) and [ebnf/Phi.svg](https://www.eolang.org/ebnf/Phi.svg). ## What's Next? @@ -202,7 +202,8 @@ Watch [video](https://www.youtube.com/watch?v=QaKIw1Bh3Oc) about EOLANG basics. Read [our blog](https://news.eolang.org), especially the section with [recently published papers](https://news.eolang.org/papers.html). -Learn [XMIR](https://news.eolang.org/2022-11-25-xmir-guide.html), a dialect of XML, which we use to represent EO program. +Learn [XMIR](https://news.eolang.org/2022-11-25-xmir-guide.html), a dialect of XML, which we use to +represent EO program. See the full collection of canonical objects: [objectionary](https://github.com/objectionary/home). @@ -222,12 +223,13 @@ provided they don't violate our quality standards. To avoid frustration, before sending us your pull request please run full Maven build: ```bash -$ mvn clean install -Pqulice +mvn clean install -Pqulice ``` You will need [Maven 3.3+](https://maven.apache.org) and Java 8+ installed. ## Special thanks + We are using the [YourKit Java Profiler](https://www.yourkit.com/java/profiler) to enhance the performance of EO components: diff --git a/eo-maven-plugin/README.md b/eo-maven-plugin/README.md index 0588aadc2e..f3da683d73 100644 --- a/eo-maven-plugin/README.md +++ b/eo-maven-plugin/README.md @@ -81,15 +81,15 @@ The entire process of turning an `.eo` program into an executable binary code consists of a few high-level steps, which must be done one after another: - * **Parsing**. +* **Parsing**. It's done by the `org.eolang.parser.EoSyntax` class in the `eo-parser` module. It takes the source code in a plain text format and parses into XML document, using [ANTLR4](https://www.antlr.org/) and [Xembly](https://www.xembly.org). The output of the parser you can find in the `target/eo/parse` directory. - Parsed objects which are versioned (normally pulled from - [Objectionary](https://github.com/objectionary/home)) are cached in `.eo/parsed` folder. + Parsed objects which are versioned (normally pulled from + [Objectionary](https://github.com/objectionary/home)) are cached in `.eo/parsed` folder. - * **Optimization**. +* **Optimization**. There are a number of [XSL transformations](https://en.wikipedia.org/wiki/XSLT) that need to be done with the XML document in order to make it ready for compilation. @@ -99,7 +99,7 @@ one after another: `org.eolang.parser.Pack` class. Some of XLST files are sanity checks (or linters). The output of each transformation you can find in the `target/eo/optimize` directory. - * **Compilation**. +* **Compilation**. The class `org.eolang.maven.TranspileMojo` in the `eo-maven-plugin` module is responsible for taking parsed and optimized XMIRs and then transforming the XML document into a collection of `.java` files. There are a number @@ -117,35 +117,40 @@ If any external object is used in EO program it will be pulled from [Objectionar By default, during compilation the plugin will check local cache (`~/.eo`) for required objects and only download (and cache) them in case they are not found locally. -This behaviour can be changed to always download objects from remote by providing +This behaviour can be changed to always download objects from remote by providing Maven option `-U` (see [Maven CLI docs](https://maven.apache.org/ref/3.1.0/maven-embedder/cli.html)): ```shell mvn -U clean install ``` -If you want to build your project or run your tests which use eo-maven-plugin, you can change stack size for your purposes by stack-size option: +If you want to build your project or run your tests which use eo-maven-plugin, you can change stack +size for your purposes by stack-size option: ```shell mvn clean install -Pqulice -Dstack-size=1M ``` + where 1M is size of stack. By default stack-size = 256M in eo-maven-plugin, maximum size is 1G. ## How to run Integration Tests only -If you want to run a specific integration test without waiting until other unit or integration tests are executed you need to go to `eo-maven-plugin` -directory and execute the next command: +If you want to run a specific integration test without waiting until other unit or integration tests +are executed you need to go to `eo-maven-plugin` directory and execute the next command: ```shell mvn clean integration-test invoker:run -Dinvoker.test=fibonacci -DskipTests ``` -Here `fibonacci` is the name of the desired integration test, `-DskipTests` is used in order to skip `eo-maven-plugin` unit tests. +Here `fibonacci` is the name of the desired integration test, `-DskipTests` is used in order to skip +`eo-maven-plugin` unit tests. ## How to disable Integration Tests -It is sometime necessary to temporary disable the integration tests (for example for introducing braking changes into plugin or EO runtime). -This can be achieved by disabling `maven-invoker-plugin` execution within `eo-maven-plugin/pom.xml`: +It is sometime necessary to temporary disable the integration tests (for example for introducing +braking changes into plugin or EO runtime). This can be achieved by disabling `maven-invoker-plugin` +execution within `eo-maven-plugin/pom.xml`: + ```xml ... diff --git a/eo-maven-plugin/src/it/README.md b/eo-maven-plugin/src/it/README.md index 0688a6db09..88f397bef1 100644 --- a/eo-maven-plugin/src/it/README.md +++ b/eo-maven-plugin/src/it/README.md @@ -1,6 +1,7 @@ - + +logo [![Maven Central](https://img.shields.io/maven-central/v/org.eolang/eo-maven-plugin.svg)](https://maven-badges.herokuapp.com/maven-central/org.eolang/eo-maven-plugin) This directory contains integration tests for eolang-maven-plugin, -but you can use them as examples of EO-to-Java transformations. \ No newline at end of file +but you can use them as examples of EO-to-Java transformations. diff --git a/eo-maven-plugin/src/it/duplicate_classes/README.md b/eo-maven-plugin/src/it/duplicate_classes/README.md index 12c0da42c9..5b92c3a807 100644 --- a/eo-maven-plugin/src/it/duplicate_classes/README.md +++ b/eo-maven-plugin/src/it/duplicate_classes/README.md @@ -1 +1 @@ -logo \ No newline at end of file +logo diff --git a/eo-maven-plugin/src/it/hash_package_layer/README.md b/eo-maven-plugin/src/it/hash_package_layer/README.md index 66042cee45..58dd04224e 100644 --- a/eo-maven-plugin/src/it/hash_package_layer/README.md +++ b/eo-maven-plugin/src/it/hash_package_layer/README.md @@ -1,3 +1,3 @@ logo -This test checks if one more package layer is added successfully to all source files. \ No newline at end of file +This test checks if one more package layer is added successfully to all source files. diff --git a/eo-maven-plugin/src/it/rewritten_sources/README.md b/eo-maven-plugin/src/it/rewritten_sources/README.md index 7ce0cd7420..21ec21c433 100644 --- a/eo-maven-plugin/src/it/rewritten_sources/README.md +++ b/eo-maven-plugin/src/it/rewritten_sources/README.md @@ -1,4 +1,4 @@ logo The main goal of the integration test is to check that `mvn test-compile` step does not rewrite -files in `target/classes` which were generated from `src` folder. \ No newline at end of file +files in `target/classes` which were generated from `src` folder. diff --git a/eo-maven-plugin/src/it/simple/README.md b/eo-maven-plugin/src/it/simple/README.md index 9dad15ea3a..7198071fd2 100644 --- a/eo-maven-plugin/src/it/simple/README.md +++ b/eo-maven-plugin/src/it/simple/README.md @@ -1,4 +1,4 @@ This is the simplest possible example of a program written in EO. Don't make it more complex than it is right now. The purpose of this integration test is to keep it running no matter -how much we change the eo-maven-plugin or the eo-runtime modules. \ No newline at end of file +how much we change the eo-maven-plugin or the eo-runtime modules. diff --git a/eo-parser/README.md b/eo-parser/README.md index 7307b53fb6..5ffc440197 100644 --- a/eo-parser/README.md +++ b/eo-parser/README.md @@ -5,24 +5,39 @@ # How to Test -This documentation provides a step-by-step guide to test the `EO` code in `eo-parser` package. There are two files provide -testing `EO` files: `PacksTest` and `TypoTests`. +This documentation provides a step-by-step guide to test the `EO` code in `eo-parser` package. There +are two files provide testing `EO` files: `PacksTest` and `TypoTests`. The `PacksTest` class contains two test methods: -1. `parsesPacks()` - This method tests if the packs are parsed correctly. It reads YAML files from the `org/eolang/parser/packs/` directory and checks if there are any failures. If there are any failures, the test is aborted. -2. `createsXaxStoryWithXslStylesheets()` - This method tests if the XSL stylesheets are created correctly. It reads YAML files from the `org/eolang/parser/xax/` directory and creates an XaxStory object. The test passes if the object is created successfully. +1. `parsesPacks()` - This method tests if the packs are parsed correctly. It reads YAML files from +the `org/eolang/parser/packs/` directory and checks if there are any failures. If there are any +failures, the test is aborted. +2. `createsXaxStoryWithXslStylesheets()` - This method tests if the XSL stylesheets are created +correctly. It reads YAML files from the `org/eolang/parser/xax/` directory and creates an XaxStory +object. The test passes if the object is created successfully. -`TypoTests` contains only `checksPacks()` method with same functionality as `parsesPacks()`. But it takes YAML files from `org/eolang/parser/typos/` directory. +`TypoTests` contains only `checksPacks()` method with same functionality as `parsesPacks()`. But it +takes YAML files from `org/eolang/parser/typos/` directory. To create YAML file, you can follow the following steps: -1. Start by creating a brief introduction to the file and its purpose. In this case, the YAML file is used for defining the XSLT stylesheets and the tests for a program, as well as defining aliases and the main function. -2. Next, provide a section that explains the different sections of the YAML file. In this case, there are three sections: `xsls`, `tests`, and `eo`. -3. For the `xsls` section, explain that it is used to define the XSLT stylesheets that will be used for transforming the input program. Provide a brief explanation of each stylesheet listed in the section. -4. For the `tests` section, explain that it is used for defining the tests that will be run on the program. Provide a brief explanation of each test listed in the section. -5. For the `eo` section, explain that it is used for defining aliases and the main function for the program. Provide a brief explanation of each alias listed in the section, and how they can be used in the program. Also, explain the purpose of the `main` function and how it works. -6. Finally, provide a conclusion that summarizes the purpose and contents of the YAML file. You can also include any additional information that might be helpful for users who are working with the file. +1. Start by creating a brief introduction to the file and its purpose. In this case, the YAML file +is used for defining the XSLT stylesheets and the tests for a program, as well as defining aliases +and the main function. +2. Next, provide a section that explains the different sections of the YAML file. In this case, +there are three sections: `xsls`, `tests`, and `eo`. +3. For the `xsls` section, explain that it is used to define the XSLT stylesheets that will be used +for transforming the input program. Provide a brief explanation of each stylesheet listed in the +section. +4. For the `tests` section, explain that it is used for defining the tests that will be run on the +program. Provide a brief explanation of each test listed in the section. +5. For the `eo` section, explain that it is used for defining aliases and the main function for the +program. Provide a brief explanation of each alias listed in the section, and how they can be used +in the program. Also, explain the purpose of the `main` function and how it works. +6. Finally, provide a conclusion that summarizes the purpose and contents of the YAML file. You can +also include any additional information that might be helpful for users who are working with the +file. Here is an example of what the YAML file might look like: @@ -63,27 +78,36 @@ eo: | ### Sections -This YAML file is used to define the XSLT stylesheets and tests for a program, as well as defining aliases and the main function. -It consists of three sections: `xsls`, `tests`, and `eo`. The `xsls` section is used to define the XSLT stylesheets, the `tests` section is used for defining the tests, and the `eo` section is used for defining aliases and the main function. +This YAML file is used to define the XSLT stylesheets and tests for a program, as well as defining +aliases and the main function. It consists of three sections: `xsls`, `tests`, and `eo`. The `xsls` +section is used to define the XSLT stylesheets, the `tests` section is used for defining the tests, +and the `eo` section is used for defining aliases and the main function. #### xsls -This section is used to define the XSLT stylesheets that will be used for transforming the input program. The following stylesheets are defined in this section: -- `/org/eolang/parser/add-refs.xsl`: This stylesheet is used to add references to the program. -- `/org/eolang/parser/expand-aliases.xsl`: This stylesheet is used to expand aliases in the program. -- `/org/eolang/parser/resolve-aliases.xsl`: This stylesheet is used to resolve aliases in the program. -- `/org/eolang/parser/add-default-package.xsl`: This stylesheet is used to add a default package to the program. +This section is used to define the XSLT stylesheets that will be used for transforming the input +program. The following stylesheets are defined in this section: + +- `/org/eolang/parser/add-refs.xsl`: This stylesheet is used to add references to the program. +- `/org/eolang/parser/expand-aliases.xsl`: This stylesheet is used to expand aliases in the program. +- `/org/eolang/parser/resolve-aliases.xsl`: This stylesheet is used to resolve aliases in the +program. +- `/org/eolang/parser/add-default-package.xsl`: This stylesheet is used to add a default package to +the program. #### tests -This section is used for defining the tests that will be run on the program. The following tests are defined in this section: -- `/program/errors[count(*)=0]`: This test checks that there are no errors in the program. -- `/program/objects[count(o)=1]`: This test checks that there is only one object in the program. -- `//o[@base='org.eolang.and' and @line='8']`: This test checks that there is an object with the base `org.eolang.and` and the line number `8`. -- `//o[@base='foo']`: This test checks that there is an object with the base `foo`. -- `//o[@base='$']`: This test checks that there is an object with the base `$`. -- `//o[@base='^']`: This test checks that there is an object with the base `^`. -- `//o[@base='Q']`: This test checks that there is an object with the base `Q`. +This section is used for defining the tests that will be run on the program. The following tests are +defined in this section: + +- `/program/errors[count(*)=0]`: This test checks that there are no errors in the program. +- `/program/objects[count(o)=1]`: This test checks that there is only one object in the program. +- `//o[@base='org.eolang.and' and @line='8']`: This test checks that there is an object with the +base `org.eolang.and` and the line number `8`. +- `//o[@base='foo']`: This test checks that there is an object with the base `foo`. +- `//o[@base='$']`: This test checks that there is an object with the base `$`. +- `//o[@base='^']`: This test checks that there is an object with the base `^`. +- `//o[@base='Q']`: This test checks that there is an object with the base `Q`. #### eo diff --git a/eo-runtime/README.md b/eo-runtime/README.md index 1cd6c2c726..8522542bd2 100644 --- a/eo-runtime/README.md +++ b/eo-runtime/README.md @@ -6,18 +6,23 @@ This is runtime for EO. ## How to run tests + You can run tests just like this: + ``` mvn clean test ``` If you want to run tests separately, you can run: + ``` mvn clean test -Dtest="{test}" ``` -Here the variable `{test}` is the full name of the test, or several test names separated by commas (`,`). + +Here the variable `{test}` is the full name of the test, or several test names separated by commas (`,`). For example, this `EO` test: + ``` [] > prints-itself assert-that > @ @@ -27,6 +32,7 @@ For example, this `EO` test: ``` you can run just like this: + ``` mvn clean test -Dtest="EOorg.EOeolang.EOprints_itselfTest" ``` @@ -36,19 +42,23 @@ mvn clean test -Dtest="EOorg.EOeolang.EOprints_itselfTest" By default, logging within tests is limited since it produces quite extensive logs which affect performance. However, for debugging/analysis purposes extended (debug) logs can be enabled. -For that both JUL and Logback levels need to be set to `FINE`. This is +For that both JUL and Logback levels need to be set to `FINE`. This is accomplished by amending the following two files: _test\resources\jul.properties_: + ``` .level=FINE ``` + _test\resources\logback.xml_: + ``` ``` + For the latter `FINE` level must be set to desired object. `Dataized` will -produce extensive logging for dataization process and `PhDefault` for +produce extensive logging for dataization process and `PhDefault` for attributes retrieval process. By default, dataization will be logged up until nesting level 3. If for some reason deeper dataization log is required it can be @@ -59,21 +69,32 @@ where `N` is an integer representing desired nesting level to log. Here is some steps to release eo-runtime: -1.To run `.rultor.yml` script in `objectionary/eo`. It is better to do it by [rultor](https://www.yegor256.com/2014/07/24/rultor-automated-merging.html) command in any github comment: +1.To run `.rultor.yml` script in `objectionary/eo`. It is better to do it by +[rultor](https://www.yegor256.com/2014/07/24/rultor-automated-merging.html) command in any github +comment: + ``` @rultor release, tag is `{new-version}` ``` - Running this script will update the `gh-pages` git branch. Which contains only `.eo` objects from the `eo-runtime` package and the file required by the script: [objectionary.lst](https://github.com/objectionary/eo/blob/gh-pages/objectionary.lst). + + Running this script will update the `gh-pages` git branch. Which contains only `.eo` objects from + the `eo-runtime` package and the file required by the script: + [objectionary.lst](https://github.com/objectionary/eo/blob/gh-pages/objectionary.lst). This script also will create several files in Maven central repository (eg `.jar`, `.pom` etc.). -2.To create a pull request in `objectionary/home` by `pull.sh` script in a separate git branch (the name of the branch doesn't matter): +2.To create a pull request in `objectionary/home` by `pull.sh` script in a separate git branch +(the name of the branch doesn't matter): + ```shell ./pull.sh objectionary/eo ``` - This will update all `.eo` files in `gh-pages` from `objectionary/eo`. It will also change the corresponding versions of the eo objects (e.g. from the `+version` metadata) in the `objectionary/home` repository. + + This will update all `.eo` files in `gh-pages` from `objectionary/eo`. It will also change the + corresponding versions of the eo objects (e.g. from the `+version` metadata) in the + `objectionary/home` repository. 3.To check and to remove manually either unused or old files. Script didn't do it. 4.To update `eo.version` in `pom.xml` in `objectionary/home`. -5.Finally, all `todo` must be removed manually. \ No newline at end of file +5.Finally, all `todo` must be removed manually. diff --git a/paper/README.md b/paper/README.md index 3be98594af..54d585f6cb 100644 --- a/paper/README.md +++ b/paper/README.md @@ -1,4 +1,4 @@ - +logo [![make](https://github.com/objectionary/eo/actions/workflows/latexmk.yml/badge.svg)](https://github.com/objectionary/eo/actions/workflows/latexmk.yml) @@ -7,7 +7,7 @@ This is a more or less formal description of EOLANG and φ-calculus. To build it, just run: ```bash -$ make +make ``` You need to have