diff --git a/.github/dco.yml b/.github/dco.yml new file mode 100644 index 000000000..0c4b142e9 --- /dev/null +++ b/.github/dco.yml @@ -0,0 +1,2 @@ +require: + members: false diff --git a/.github/labels-manage.yml b/.github/labels-manage.yml index 5939c36cc..986e68c3c 100644 --- a/.github/labels-manage.yml +++ b/.github/labels-manage.yml @@ -118,7 +118,7 @@ description: Something needs to get done - name: type/technical-debt color: D4C5F9 - description: Techical Dept + description: Technical Dept - name: type/question color: D4C5F9 description: Is a question diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 782474543..72fbff57e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -48,18 +48,17 @@ jobs: 17 cache: gradle - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | - jf rt gradlec \ + jf gradlec \ --use-wrapper \ --uses-plugin \ --deploy-ivy-desc=false \ - --server-id-resolve repo.spring.io \ - --server-id-deploy repo.spring.io \ + --server-id-resolve=${{ vars.JF_SERVER_ID }} \ + --server-id-deploy=${{ vars.JF_SERVER_ID }} \ --repo-resolve snapshot \ --repo-deploy snapshot echo JFROG_CLI_BUILD_NAME=spring-shell-main >> $GITHUB_ENV @@ -72,5 +71,5 @@ jobs: GRADLE_ENTERPRISE_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }} GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }} run: | - jf rt gradle build artifactoryPublish + jf gradle build artifactoryPublish jf rt build-publish diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index 738150b25..87f13ce04 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -16,7 +16,7 @@ jobs: graal: latest musl: false - nickname: macos - os: macos-12 + os: macos-latest graal: latest musl: false - nickname: linux @@ -74,12 +74,10 @@ jobs: nickname: win # - os: windows-2019 # nickname: win - - os: macos-12 - nickname: macos - - os: macos-13 - nickname: macos - os: macos-14 nickname: macos + - os: macos-15 + nickname: macos - os: ubuntu-22.04 nickname: linux - os: ubuntu-20.04 @@ -97,10 +95,6 @@ jobs: distribution: adopt java-version: 22 cache: gradle - - name: Use Python 3.11 - uses: actions/setup-python@v4 - with: - python-version: '3.11' - uses: actions/setup-node@v2 with: node-version: '16' diff --git a/.github/workflows/release-ga.yml b/.github/workflows/release-ga.yml index a7165f1d7..a318003cc 100644 --- a/.github/workflows/release-ga.yml +++ b/.github/workflows/release-ga.yml @@ -17,22 +17,18 @@ jobs: java-version: | 22 17 - - uses: jvalkeal/setup-maven@v1 - with: - maven-version: 3.8.4 - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | - jf rt gradlec \ + jf gradlec \ --use-wrapper \ --uses-plugin \ --deploy-ivy-desc=false \ - --server-id-resolve repo.spring.io \ - --server-id-deploy repo.spring.io \ + --server-id-resolve=${{ vars.JF_SERVER_ID }} \ + --server-id-deploy=${{ vars.JF_SERVER_ID }} \ --repo-resolve release \ --repo-deploy libs-staging-local echo JFROG_CLI_BUILD_NAME=spring-shell-main-release >> $GITHUB_ENV @@ -61,7 +57,7 @@ jobs: GRADLE_ENTERPRISE_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }} GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }} run: | - jf rt gradle build artifactoryPublish + jf gradle build artifactoryPublish jf rt build-publish - name: Push Release env: @@ -83,9 +79,8 @@ jobs: steps: - uses: actions/checkout@v3 - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | @@ -159,9 +154,8 @@ jobs: steps: - uses: actions/checkout@v3 - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | diff --git a/.github/workflows/release-milestone.yml b/.github/workflows/release-milestone.yml index bbfc743d0..c0c005638 100644 --- a/.github/workflows/release-milestone.yml +++ b/.github/workflows/release-milestone.yml @@ -20,13 +20,9 @@ jobs: java-version: | 22 17 - - uses: jvalkeal/setup-maven@v1 - with: - maven-version: 3.8.4 - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | @@ -34,8 +30,8 @@ jobs: --use-wrapper \ --uses-plugin \ --deploy-ivy-desc=false \ - --server-id-resolve repo.spring.io \ - --server-id-deploy repo.spring.io \ + --server-id-resolve=${{ vars.JF_SERVER_ID }} \ + --server-id-deploy=${{ vars.JF_SERVER_ID }} \ --repo-resolve milestone \ --repo-deploy libs-staging-local echo JFROG_CLI_BUILD_NAME=spring-shell-main-milestone >> $GITHUB_ENV @@ -87,9 +83,8 @@ jobs: steps: - uses: actions/checkout@v3 - uses: jfrog/setup-jfrog-cli@v3 - with: - version: 2.21.5 env: + JF_URL: 'https://repo.spring.io' JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} - name: Configure JFrog Cli run: | diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index ad8326dab..e3158115f 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,2 +1,6 @@ -If you have not previously done so, please fill out and -submit the https://cla.pivotal.io/sign/spring[Contributor License Agreement]. +### Sign-off commits according to the Developer Certificate of Origin + +All commits must include a Signed-off-by trailer at the end of each commit message to indicate that the contributor agrees to the [Developer Certificate of Origin](https://developercertificate.org). + +For additional details, please refer to the blog post [Hello DCO, Goodbye CLA: Simplifying Contributions to Spring](https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring). + diff --git a/e2e/spring-shell-e2e/package-lock.json b/e2e/spring-shell-e2e/package-lock.json index b71035634..321cdb871 100644 --- a/e2e/spring-shell-e2e/package-lock.json +++ b/e2e/spring-shell-e2e/package-lock.json @@ -9,8 +9,8 @@ "version": "2.1.0", "license": "ISC", "dependencies": { - "node-pty": "0.11.0-beta19", - "xterm-headless": "^4.18.0" + "@xterm/headless": "^5.5.0", + "node-pty": "^1.0.0" }, "devDependencies": { "@types/node": "^18.11.9", @@ -24,21 +24,23 @@ "integrity": "sha512-CRpX21/kGdzjOpFsZSkcrXMGIBWMGNIHXXBVFSH+ggkftxg+XYP20TESbh+zFvFj3EQOl5byk0HTRn1IL6hbqg==", "dev": true }, + "node_modules/@xterm/headless": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-5.5.0.tgz", + "integrity": "sha512-5xXB7kdQlFBP82ViMJTwwEc3gKCLGKR/eoxQm4zge7GPBl86tCdI0IdPJjoKd8mUSFXz5V7i/25sfsEkP4j46g==" + }, "node_modules/nan": { - "version": "2.15.0", - "resolved": "https://registry.npmjs.org/nan/-/nan-2.15.0.tgz", - "integrity": "sha512-8ZtvEnA2c5aYCZYd1cvgdnU6cqwixRoYg70xPLWUws5ORTa/lnw+u4amixRS/Ac5U5mQVgp9pnlSUnbNWFaWZQ==" + "version": "2.20.0", + "resolved": "https://registry.npmjs.org/nan/-/nan-2.20.0.tgz", + "integrity": "sha512-bk3gXBZDGILuuo/6sKtr0DQmSThYHLtNCdSdXk9YkxD/jK6X2vmCyyXBBxyqZ4XcnzTyYEAThfX3DCEnLf6igw==" }, "node_modules/node-pty": { - "version": "0.11.0-beta19", - "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-0.11.0-beta19.tgz", - "integrity": "sha512-1cdUx15rCVYEcvOvqNRO4S52vYM9mnFyTAceut+lW8/+YWcYQl1TQ3naDqtWHDcVjZI/FbDX1j4iQFwypmJSLQ==", + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.0.0.tgz", + "integrity": "sha512-wtBMWWS7dFZm/VgqElrTvtfMq4GzJ6+edFI0Y0zyzygUSZMgZdraDUMUhCIvkjhJjme15qWmbyJbtAx4ot4uZA==", "hasInstallScript": true, "dependencies": { - "nan": "^2.14.0" - }, - "peerDependencies": { - "node-gyp": "^8.3.0" + "nan": "^2.17.0" } }, "node_modules/prettier": { @@ -68,11 +70,6 @@ "engines": { "node": ">=4.2.0" } - }, - "node_modules/xterm-headless": { - "version": "4.18.0", - "resolved": "https://registry.npmjs.org/xterm-headless/-/xterm-headless-4.18.0.tgz", - "integrity": "sha512-VwSPG2cyVOwesVVLBVrybYNY6cUMiVkD2fLnIXcBs/1iJ3M7bhD3lP9HdQOHGtOkbxV2Duf7MZNmEfngBXL/iQ==" } }, "dependencies": { @@ -82,17 +79,22 @@ "integrity": "sha512-CRpX21/kGdzjOpFsZSkcrXMGIBWMGNIHXXBVFSH+ggkftxg+XYP20TESbh+zFvFj3EQOl5byk0HTRn1IL6hbqg==", "dev": true }, + "@xterm/headless": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-5.5.0.tgz", + "integrity": "sha512-5xXB7kdQlFBP82ViMJTwwEc3gKCLGKR/eoxQm4zge7GPBl86tCdI0IdPJjoKd8mUSFXz5V7i/25sfsEkP4j46g==" + }, "nan": { - "version": "2.15.0", - "resolved": "https://registry.npmjs.org/nan/-/nan-2.15.0.tgz", - "integrity": "sha512-8ZtvEnA2c5aYCZYd1cvgdnU6cqwixRoYg70xPLWUws5ORTa/lnw+u4amixRS/Ac5U5mQVgp9pnlSUnbNWFaWZQ==" + "version": "2.20.0", + "resolved": "https://registry.npmjs.org/nan/-/nan-2.20.0.tgz", + "integrity": "sha512-bk3gXBZDGILuuo/6sKtr0DQmSThYHLtNCdSdXk9YkxD/jK6X2vmCyyXBBxyqZ4XcnzTyYEAThfX3DCEnLf6igw==" }, "node-pty": { - "version": "0.11.0-beta19", - "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-0.11.0-beta19.tgz", - "integrity": "sha512-1cdUx15rCVYEcvOvqNRO4S52vYM9mnFyTAceut+lW8/+YWcYQl1TQ3naDqtWHDcVjZI/FbDX1j4iQFwypmJSLQ==", + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.0.0.tgz", + "integrity": "sha512-wtBMWWS7dFZm/VgqElrTvtfMq4GzJ6+edFI0Y0zyzygUSZMgZdraDUMUhCIvkjhJjme15qWmbyJbtAx4ot4uZA==", "requires": { - "nan": "^2.14.0" + "nan": "^2.17.0" } }, "prettier": { @@ -106,11 +108,6 @@ "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.6.4.tgz", "integrity": "sha512-9ia/jWHIEbo49HfjrLGfKbZSuWo9iTMwXO+Ca3pRsSpbsMbc7/IU8NKdCZVRRBafVPGnoJeFL76ZOAA84I9fEg==", "dev": true - }, - "xterm-headless": { - "version": "4.18.0", - "resolved": "https://registry.npmjs.org/xterm-headless/-/xterm-headless-4.18.0.tgz", - "integrity": "sha512-VwSPG2cyVOwesVVLBVrybYNY6cUMiVkD2fLnIXcBs/1iJ3M7bhD3lP9HdQOHGtOkbxV2Duf7MZNmEfngBXL/iQ==" } } } diff --git a/e2e/spring-shell-e2e/package.json b/e2e/spring-shell-e2e/package.json index f71bb9dab..ee3785c25 100644 --- a/e2e/spring-shell-e2e/package.json +++ b/e2e/spring-shell-e2e/package.json @@ -36,7 +36,7 @@ "typescript": "^4.6.4" }, "dependencies": { - "node-pty": "0.11.0-beta19", - "xterm-headless": "^4.18.0" + "node-pty": "^1.0.0", + "@xterm/headless": "^5.5.0" } } diff --git a/gradle.properties b/gradle.properties index 22eb3c6e1..0c46e876f 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,11 +1,11 @@ -version=3.4.0-SNAPSHOT -springBootVersion=3.4.0-M3 -nativeBuildToolsVersion=0.10.1 -commonsIoVersion=2.11.0 -jlineVersion=3.26.3 -st4Version=4.3.3 -jimfsVersion=1.2 -gradleEnterpriseVersion=3.16.2 -springGeConventionsVersion=0.0.15 -findbugsVersion=3.0.2 +version=3.4.1-SNAPSHOT +springBootVersion=3.5.0-SNAPSHOT +nativeBuildToolsVersion=0.10.6 +commonsIoVersion=2.19.0 +jlineVersion=3.29.0 +st4Version=4.3.4 +jimfsVersion=1.3.0 +gradleEnterpriseVersion=3.19.2 +springGeConventionsVersion=0.0.17 org.gradle.caching=true +includeFfm=false \ No newline at end of file diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 0aaefbcaf..37f853b1c 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.1-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME diff --git a/settings.gradle b/settings.gradle index 545cdaed1..5c5591d29 100644 --- a/settings.gradle +++ b/settings.gradle @@ -49,12 +49,18 @@ include 'spring-shell-table' include 'spring-shell-test' include 'spring-shell-test-autoconfigure' +def ffm = settings.properties.hasProperty('includeFfm') && settings.properties.property('includeFfm').asBoolean() + file("${rootDir}/spring-shell-starters").eachDirMatch(~/spring-shell-starter.*/) { - include "spring-shell-starters:${it.name}" + if((!it.name.endsWith('ffm') && !ffm) || ffm) { // skipping + include "spring-shell-starters:${it.name}" + } } file("${rootDir}/spring-shell-samples").eachDirMatch(~/spring-shell-sample.*/) { - include "spring-shell-samples:${it.name}" + if((!it.name.endsWith('ffm') && !ffm) || ffm) { // skipping + include "spring-shell-samples:${it.name}" + } } rootProject.children.each { project -> diff --git a/spring-shell-autoconfigure/spring-shell-autoconfigure.gradle b/spring-shell-autoconfigure/spring-shell-autoconfigure.gradle index 969ba2ddc..528cac102 100644 --- a/spring-shell-autoconfigure/spring-shell-autoconfigure.gradle +++ b/spring-shell-autoconfigure/spring-shell-autoconfigure.gradle @@ -10,6 +10,11 @@ dependencies { implementation project(':spring-shell-core') implementation project(':spring-shell-standard') implementation project(':spring-shell-standard-commands') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor' } diff --git a/spring-shell-core/spring-shell-core.gradle b/spring-shell-core/spring-shell-core.gradle index ae996afbc..5599d6523 100644 --- a/spring-shell-core/spring-shell-core.gradle +++ b/spring-shell-core/spring-shell-core.gradle @@ -17,8 +17,12 @@ dependencies { api('org.jline:jline-terminal') api('org.antlr:ST4') api('commons-io:commons-io') - compileOnly 'com.google.code.findbugs:jsr305' - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' testImplementation 'com.google.jimfs:jimfs' testImplementation 'io.projectreactor:reactor-test' diff --git a/spring-shell-core/src/main/java/org/springframework/shell/command/CommandRegistration.java b/spring-shell-core/src/main/java/org/springframework/shell/command/CommandRegistration.java index 2f1b0edc1..586663a34 100644 --- a/spring-shell-core/src/main/java/org/springframework/shell/command/CommandRegistration.java +++ b/spring-shell-core/src/main/java/org/springframework/shell/command/CommandRegistration.java @@ -750,6 +750,15 @@ public interface Builder { */ OptionSpec withOption(); + /** + * Define an option what this command should user for. Can be used multiple + * times. + * + * @param customizer the option spec consumer + * @return option spec for chaining + */ + Builder withOption(Consumer customizer); + /** * Define a target what this command should execute * @@ -757,6 +766,14 @@ public interface Builder { */ TargetSpec withTarget(); + /** + * Define a target what this command should execute + * + * @param customizer the target spec consumer + * @return target spec for chaining + */ + Builder withTarget(Consumer customizer); + /** * Define an alias what this command should execute * @@ -764,6 +781,14 @@ public interface Builder { */ AliasSpec withAlias(); + /** + * Define an alias what this command should execute + * + * @param customizer the alias spec consumer + * @return alias spec for chaining + */ + Builder withAlias(Consumer customizer); + /** * Define an exit code what this command should execute * @@ -771,6 +796,14 @@ public interface Builder { */ ExitCodeSpec withExitCode(); + /** + * Define an exit code what this command should execute + * + * @param customizer the exit code spec consumer + * @return exit code spec for chaining + */ + Builder withExitCode(Consumer customizer); + /** * Define an error handling what this command should use * @@ -778,6 +811,14 @@ public interface Builder { */ ErrorHandlingSpec withErrorHandling(); + /** + * Define an error handling what this command should use + * + * @param customizer the error handling spec consumer + * @return error handling spec for chaining + */ + Builder withErrorHandling(Consumer customizer); + /** * Define help options what this command should use. * @@ -785,6 +826,14 @@ public interface Builder { */ HelpOptionsSpec withHelpOptions(); + /** + * Define help options what this command should use. + * + * @param customizer the help options spec consumer + * @return help options spec for chaining + */ + Builder withHelpOptions(Consumer customizer); + /** * Builds a {@link CommandRegistration}. * @@ -1407,6 +1456,14 @@ public OptionSpec withOption() { return spec; } + @Override + public Builder withOption(Consumer customizer) { + DefaultOptionSpec spec = new DefaultOptionSpec(this); + customizer.accept(spec); + optionSpecs.add(spec); + return this; + } + @Override public TargetSpec withTarget() { DefaultTargetSpec spec = new DefaultTargetSpec(this); @@ -1414,6 +1471,14 @@ public TargetSpec withTarget() { return spec; } + @Override + public Builder withTarget(Consumer customizer) { + DefaultTargetSpec spec = new DefaultTargetSpec(this); + customizer.accept(spec); + targetSpec = spec; + return this; + } + @Override public AliasSpec withAlias() { DefaultAliasSpec spec = new DefaultAliasSpec(this); @@ -1421,6 +1486,14 @@ public AliasSpec withAlias() { return spec; } + @Override + public Builder withAlias(Consumer customizer) { + DefaultAliasSpec spec = new DefaultAliasSpec(this); + customizer.accept(spec); + this.aliasSpecs.add(spec); + return this; + } + @Override public ExitCodeSpec withExitCode() { DefaultExitCodeSpec spec = new DefaultExitCodeSpec(this); @@ -1428,6 +1501,14 @@ public ExitCodeSpec withExitCode() { return spec; } + @Override + public Builder withExitCode(Consumer customizer) { + DefaultExitCodeSpec spec = new DefaultExitCodeSpec(this); + customizer.accept(spec); + this.exitCodeSpec = spec; + return this; + } + @Override public ErrorHandlingSpec withErrorHandling() { DefaultErrorHandlingSpec spec = new DefaultErrorHandlingSpec(this); @@ -1435,6 +1516,14 @@ public ErrorHandlingSpec withErrorHandling() { return spec; } + @Override + public Builder withErrorHandling(Consumer customizer) { + DefaultErrorHandlingSpec spec = new DefaultErrorHandlingSpec(this); + customizer.accept(spec); + this.errorHandlingSpec = spec; + return this; + } + @Override public HelpOptionsSpec withHelpOptions() { if (this.helpOptionsSpec == null) { @@ -1443,6 +1532,15 @@ public HelpOptionsSpec withHelpOptions() { return this.helpOptionsSpec; } + @Override + public Builder withHelpOptions(Consumer customizer) { + if (this.helpOptionsSpec == null) { + this.helpOptionsSpec = new DefaultHelpOptionsSpec(this); + } + customizer.accept(this.helpOptionsSpec); + return this; + } + @Override public CommandRegistration build() { Assert.notNull(commands, "command cannot be empty"); diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc index 4af2f9d7a..5f306a12d 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc @@ -1,6 +1,6 @@ [appendix] [#appendix-tech-intro] -= Techical Introduction += Technical Introduction :page-section-summary-toc: 1 This appendix contains information for developers and others who would like to know more about how Spring Shell diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/tui/catalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/tui/catalog.adoc index 8c0bf6205..a474c32d2 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices/tui/catalog.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/tui/catalog.adoc @@ -4,10 +4,10 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] -Catalog application is showing various ways how Terminal UI Framework can be used. -In this section we discuss how this application works. It can be considered to be +Catalog application shows various ways how the Terminal UI Framework can be used. +In this section, we discuss how this application works. It can be considered as a reference application as it's using most of the features available and tries -to follow best practices. +to follow the best practices. [[create-scenario]] == Create Scenario diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/tui/index.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/tui/index.adoc index 2c7b353e1..ac5088f93 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices/tui/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/tui/index.adoc @@ -5,9 +5,9 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] -This is a technical introduction to _UI Framework_. +This is a technical introduction to the _UI Framework_. -_UI Framework_ is a toolkit to build rich console apps. +The _UI Framework_ is a toolkit to build rich console apps. diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/tui/viewdev.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/tui/viewdev.adoc index d47b2007a..18f17452f 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices/tui/viewdev.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/tui/viewdev.adoc @@ -2,7 +2,7 @@ = View Development :page-section-summary-toc: 1 -While a _view_ just need to implement `View` it's usually convenient to just +While a _view_ just needs to implement `View`, it's usually convenient to just use `BoxView` as a parent. [[register-bindings]] diff --git a/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc b/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc index fbc3f514a..457f9dbae 100644 --- a/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc +++ b/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc @@ -5,13 +5,13 @@ Throughout this documentation, we make references to configuring something by using annotations or programmatic examples. -NOTE: There are two annotation models, xref:commands/registration/annotation.adoc[annotations] -referred to new annotation model, xref:commands/registration/legacyannotation.adoc[legacy annotations] -referred to old legacy annotation model. +NOTE: There are two annotation models: the xref:commands/registration/annotation.adoc[annotations] model +referred to as the new annotation model, and the xref:commands/registration/legacyannotation.adoc[legacy annotations] +model referred to as the old legacy annotation model. -Old legacy annotation model mostly relates to use of `@ShellMethod` and `@ShellOption` and -new annotation model relates to use of `@Command`. +The old legacy annotation model mostly relates to the use of `@ShellMethod` and `@ShellOption` and +the new annotation model relates to the use of `@Command`. The programmatic model is how things are actually registered, even if you use annotations. -NOTE: The documentation structure is getting revised to clarify how to provide configurations in separate ways. Thank you for understanding while that work is still in progress. +NOTE: The documentation structure is getting revised to clarify how to provide configurations in separate ways. diff --git a/spring-shell-docs/modules/ROOT/pages/building.adoc b/spring-shell-docs/modules/ROOT/pages/building.adoc index 8fbdfe03e..8b407e397 100644 --- a/spring-shell-docs/modules/ROOT/pages/building.adoc +++ b/spring-shell-docs/modules/ROOT/pages/building.adoc @@ -25,17 +25,17 @@ traditionally been relatively complex process while it may look like there's not that much happening as it's all just text. Remember all those old manual typewriters or matrix printers? -A character is printed where a cursor is which then need to be moved +A character is printed then a cursor needs to be moved if printing in a different position. In a nutshell that's how current terminal emulators work. -To access and understand existing terminal emulator environment better +To access and understand existing terminal emulators environment better, JLine can use native code via its own shared libraries. JLine detects which providers are present and then makes a choice which one to use. Traditionally there's been 3 providers, `jansi`, `jni` and `jna` which should all provide same functionalities. -Our starters can be used to spesifically pick some of these JLine +Our starters can be used to specifically pick some of these JLine providers. == FFM @@ -127,7 +127,7 @@ When gradle build is run with `./gradlew nativeCompile` you should get binary under `build/native/nativeCompile` directory. For `maven` use `spring-boot-starter-parent` as parent and you'll get `native` -profile which can be used to do a compilation. You need to configure metadata repository +profile which can be used to do a native compilation. You need to configure metadata repository: [source, xml, subs=attributes+] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/commands/alias.adoc b/spring-shell-docs/modules/ROOT/pages/commands/alias.adoc index b90fa643e..47b179ff1 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/alias.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/alias.adoc @@ -8,10 +8,9 @@ cases where you want to create a shorter version of a command or going through a complete command rename while keeping old one temporarily in place. -Format for _alias_ is slighly different than a _command_. When _command_ +The format of _alias_ is slightly different from a _command_. When _command_ is defined as an array it's concatenated together into a single command. -When _alias_ is defined as an array it's used to create a separate -aliases. +When _alias_ is defined as an array it's used to create separate aliases. Aliases with a plain `CommandRegistration` is simple and clear as you get exactly what you define as there's no "magic" in it. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc index 0d36f1bd5..d1d195500 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc @@ -2,5 +2,5 @@ = Clear :page-section-summary-toc: 1 -The `clear` command does what you would expect and clears the screen, resetting the prompt +The `clear` command clears the screen, resetting the prompt in the top left corner. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc index 1e69a1293..023c1004c 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc @@ -2,8 +2,8 @@ = Completion :page-section-summary-toc: 1 -The `completion` command set lets you create script files that can be used -with am OS shell implementations to provide completion. This is very useful when +The `completion` command lets you create script files that can be used +with an OS shell implementation to provide completion. This is very useful when working with non-interactive mode. -Currently, the only implementation is for bash, which works with `bash` sub-command. +Currently, the only implementation is for bash, which works with the `bash` sub-command. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc index 28e87e51b..682034b78 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc @@ -2,9 +2,7 @@ = Help Running a shell application often implies that the user is in a graphically limited -environment. Also, while we are nearly always connected in the era of mobile phones, -accessing a web browser or any other rich UI application (such as a PDF viewer) may not always -be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help` +environment. This is why it is important that the shell commands are correctly self-documented, and this is where the `help` command comes in. Typing `help` + `ENTER` lists all the commands known to the shell (including xref:commands/availability.adoc[unavailable] commands) diff --git a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc index 76d28871e..e3cef0069 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc @@ -6,13 +6,13 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] `@ShellComponent` classes can have `@ExceptionResolver` methods to handle exceptions from component methods. These are meant for annotated methods. -The exception may match against a top-level exception being propagated (e.g. a direct IOException -being thrown) or against a nested cause within a wrapper exception (e.g. an IOException wrapped -inside an IllegalStateException). This can match at arbitrary cause levels. +The exception may match against a top-level exception being propagated (e.g. a direct `IOException` +being thrown) or against a nested cause within a wrapper exception (e.g. an `IOException` wrapped +inside an `IllegalStateException`). This can match at arbitrary cause levels. For matching exception types, preferably declare the target exception as a method argument, as the preceding example(s) shows. When multiple exception methods match, a root exception match is -generally preferred to a cause exception match. More specifically, the ExceptionDepthComparator +generally preferred to a cause exception match. More specifically, the `ExceptionDepthComparator` is used to sort exceptions based on their depth from the thrown exception type. Alternatively, the annotation declaration may narrow the exception types to match, as the @@ -38,7 +38,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-exitc `@ExceptionResolver` with `void` return type is automatically handled as handled exception. You can then also define `@ExitCode` and use `Terminal` if you need to write something -into console. +into the console: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc index 041ba897c..85dbc52c3 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc @@ -4,15 +4,15 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] -Exceptions happen from a user code wether it is intentional or not. This section describes -how `spring-shell` handles exceptions and gives instructions and best practices how to +Exceptions happen from a user code whether it is intentional or not. This section describes +how Spring Shell handles exceptions and gives instructions and best practices on how to work with it. -Many command line applications when applicable return an _exit code_ which running environment -can use to differentiate if command has been executed successfully or not. In a `spring-shell` -this mostly relates when a command is run on a non-interactive mode meaning one command -is always executed once with an instance of a `spring-shell`. Take a note that _exit code_ -always relates to non-interactive shell. +Many command line applications return an _exit code_ which can be used by the +running environment to differentiate if command has been executed successfully or not. +In Spring Shell, this mostly relates to when a command is run in a non-interactive mode, +meaning one command is always executed once with an instance of a `spring-shell`. Take a note +that _exit code_ always relates to non-interactive shell. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc index b83f91fce..0283e162d 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc @@ -5,15 +5,15 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Default behaviour of an exit codes is as: -- Errors from a command option parsing will result code of `2` -- Any generic error will result result code of `1` -- Obviously in any other case result code is `0` +- Errors from a command option parsing will result to a code of `2` +- Any generic error will result to a code of `1` +- Obviously in any other case will result to a code of `0` Every `CommandRegistration` can define its own mappings between _Exception_ and _exit code_. -Essentially we're bound to functionality in `Spring Boot` regarding _exit code_ and simply +Spring shell uses a similar approach to `Spring Boot` regarding _exit code_ and simply integrate into that. -Assuming there is an exception show below which would be thrown from a command: +Assuming there is an exception shown below which would be thrown from a command: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc index 778d96a26..c30823ff1 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc @@ -5,8 +5,8 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Unhandled exceptions will bubble up into shell's `ResultHandlerService` and then eventually handled by some instance of `ResultHandler`. Chain of `ExceptionResolver` implementations -can be used to resolve exceptions and gives you flexibility to return message to get written -into console together with exit code which are wrapped within `CommandHandlingResult`. +can be used to resolve exceptions and gives you the flexibility to return a message to get +written into the console together with exit code which are wrapped within `CommandHandlingResult`. `CommandHandlingResult` may contain a _message_ and/or _exit code_. [source, java, indent=0] @@ -14,14 +14,14 @@ into console together with exit code which are wrapped within `CommandHandlingRe include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class] ---- -`CommandExceptionResolver` implementations can be defined globally as bean. +`CommandExceptionResolver` implementations can be defined globally as beans: [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class-as-bean] ---- -or defined per `CommandRegistration` if it's applicable only for a particular command itself. +or defined per `CommandRegistration` if it's applicable only to a particular command: [source, java, indent=0] ---- @@ -31,18 +31,18 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=example1] NOTE: Resolvers defined with a command are handled before global resolvers. -Use you own exception types which can also be an instance of boot's `ExitCodeGenerator` if -you want to define exit code there. +You can use your own exception types which can also be instances of Spring Boot's `ExitCodeGenerator` +if you want to define exit code there: [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-class] ---- -Some build in `CommandExceptionResolver` beans are registered to handle common +Some built-in `CommandExceptionResolver` beans are registered to handle common exceptions thrown from command parsing. These are registered with _order_ -presedence defined in `CommandExceptionResolver.DEFAULT_PRECEDENCE`. +precedence defined in `CommandExceptionResolver.DEFAULT_PRECEDENCE`. As these beans are used in a given order, `@Order` annotation or `Ordered` -interface from can be used just like in any other spring app. This +interface can be used just like in any other Spring app. This is generally useful if you need to control your own beans to get used -either before or after a defaults. +either before or after default ones. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc b/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc index 6c686eefe..de38312d7 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc @@ -5,22 +5,22 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] _Spring Shell_ has a build-in `help` command but not all favour getting command help from it as you always need to call it with arguments for target command. It's -common in many cli frameworks for every command having options _--help_ and _-h_ +common in many CLI frameworks for every command having options _--help_ and _-h_ to print out command help. Default functionality is that every command will get modified to have options _--help_ and _-h_, which if present in a given command will automatically -short circuit command execution into a existing `help` command regardless -what other command-line options is typed. +short circuit command execution into an existing `help` command regardless +what other command-line options are typed. -Below example shows its default settings. +The following example shows its default settings: [source, java, indent=0] ---- include::{snippets}/CommandRegistrationHelpOptionsSnippets.java[tag=defaults] ---- -It is possible to change default behaviour via configuration options. +It is possible to change default behaviour via configuration options: [source, yaml] ---- @@ -33,6 +33,6 @@ spring: command: help ---- -NOTE: Commands defined programmationally or via annotations will automatically add -help options. With annotation model you can only turn things off globally, programmatic -model gives option to modify settings per command. +NOTE: Commands defined programmatically or via annotations will automatically add +help options. With the annotation model you can only turn things off globally, while +with the programmatic model you can modify settings per command. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc b/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc index 7014c8b53..b3c0cb694 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc @@ -4,10 +4,10 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] It is possible to _hide_ a command which is convenient in cases where it is not yet ready for -prime time, is meant for debugging purposes or you have any other reason you dont want to -advertise its presense. +prime time, or is meant for debugging purposes or you have any other reason you don't want to +advertise its presence. -Hidden command can be executed if you know it and its options. It is effectively removed +A hidden command can be executed if you know it and its options. It is effectively removed from: * Help listing @@ -15,7 +15,7 @@ from: * Command completion in interactive mode * Bash completion -Below is an example how to define command as _hidden_. It shows available builder methods +Below is an example of how to define _hidden_ command. It shows available builder methods to define _hidden_ state. [source, java, indent=0] diff --git a/spring-shell-docs/modules/ROOT/pages/commands/index.adoc b/spring-shell-docs/modules/ROOT/pages/commands/index.adoc index 2662bfe83..6a5a73ee3 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/index.adoc @@ -5,7 +5,7 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] In this section, we go through an actual command registration and leave command options -and execution for later in a documentation. You can find more detailed info in +and execution for a later section in the documentation. You can find more details in xref:appendices/techintro/registration.adoc[Command Registration]. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc b/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc index baec80077..1ea32f2e9 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc @@ -5,9 +5,9 @@ ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Command registration can define `InteractionMode` which is used to hide commands -depending which mode shell is executing. More about that in xref:execution.adoc#using-shell-execution-interactionmode[Interaction Mode]. +depending on which mode the shell is executing in. More about that in xref:execution.adoc#using-shell-execution-interactionmode[Interaction Mode]. -You can define it with `CommandRegisration`. +You can define the interaction mode with `CommandRegisration`: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc index 928ce9f46..917f04571 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc @@ -4,17 +4,16 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] -There are two different ways to define a command: through an annotation model and -through a programmatic model. In the annotation model, you define your methods -in a class and annotate the class and the methods with specific annotations. -In the programmatic model, you use a more low level approach, defining command -registrations (either as beans or by dynamically registering with a command catalog). +There are two different ways to define a command. through an annotation model and through a programmatic model: -Starting from _3.1.x_ a better support for defining commands using -xref:commands/registration/annotation.adoc[annotations] were added. Firstly because eventually standard +- In the annotation model, you define your methods in a class and annotate the class and the methods with specific annotations. +- In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog). + +Starting from version _3.1.x_, a better support for defining commands using +xref:commands/registration/annotation.adoc[annotations] was added. Firstly because eventually standard package providing xref:commands/registration/legacyannotation.adoc[legacy annotations] will get deprecated and removed. Secondly so that we're able to provide same set of features than using underlying -`CommandRegistration`. Creating new a annotation model allows us to rethink and modernise that +`CommandRegistration`. Creating a new annotation model allows us to rethink and modernise that part without breaking existing applications. diff --git a/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc index ac67f8b98..0a957d012 100644 --- a/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc @@ -19,7 +19,7 @@ a new builder so you don't need to worry about its internal state. IMPORTANT: Commands registered programmatically automatically add _help options_ mentioned in xref:commands/helpoptions.adoc[Help Options]. -If bean of this supplier type is defined then auto-configuration +If a bean of this supplier type is defined then auto-configuration will back off giving you an option to redefine default functionality. [source, java, indent=0] @@ -28,7 +28,7 @@ include::{snippets}/CommandRegistrationBeanSnippets.java[tag=fromsupplier] ---- `CommandRegistrationCustomizer` beans can be defined if you want to centrally -modify builder instance given you by supplier mentioned above. +modify builder instance given to you by a supplier as mentioned below: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/completion.adoc b/spring-shell-docs/modules/ROOT/pages/completion.adoc index e13019c66..91b4fd879 100644 --- a/spring-shell-docs/modules/ROOT/pages/completion.adoc +++ b/spring-shell-docs/modules/ROOT/pages/completion.adoc @@ -18,8 +18,8 @@ methods which takes `CompletionContext` and returns a list of `CompletionProposal` instances. `CompletionContext` gives you various information about a current context like command registration and option. -NOTE: Generic resolvers can be registered as a beans if those are useful -for all commands and scenarious. For example existing completion +NOTE: Generic resolvers can be registered as beans if those are useful +for all commands and scenarios. For example existing completion implementation `RegistrationOptionsCompletionResolver` handles completions for a option names. diff --git a/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc b/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc index 1ddd76dd6..a26492b5a 100644 --- a/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc @@ -21,9 +21,10 @@ include::{snippets}/FlowComponentSnippets.java[tag=snippet1] include::example$component-flow-showcase-1.cast[] ---- -Normal execution order of a components is same as defined with a builder. It's -possible to conditionally choose where to jump in a flow by using a `next` -function and returning target _component id_. If this returned id is aither _null_ +NOTE: Normal execution order of a components is same as defined with a builder. + +It's possible to conditionally choose where to jump in a flow by using a `next` +function and returning target _component id_. If this returned id is either _null_ or doesn't exist flow is essentially stopped right there. [source, java, indent=0] diff --git a/spring-shell-docs/modules/ROOT/pages/components/index.adoc b/spring-shell-docs/modules/ROOT/pages/components/index.adoc index dcbec06b0..d4a20879e 100644 --- a/spring-shell-docs/modules/ROOT/pages/components/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/index.adoc @@ -2,7 +2,7 @@ = Components :page-section-summary-toc: 1 -Components are a set of features which are either build-in or something +Components are a set of features which are either built-in or something you can re-use or extend for your own needs. Components in question are either built-in _commands_ or UI side components providing higher level features within commands itself. diff --git a/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc b/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc index a3ed12f89..f0a951321 100644 --- a/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc @@ -3,7 +3,7 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] -On default a missing command is handled via `CommandNotFoundResultHandler` +By default, a missing command is handled via `CommandNotFoundResultHandler` and outputs a simple message: [source, text] @@ -12,7 +12,7 @@ shell:>missing No command found for 'missing' ---- -Internally `CommandNotFoundResultHandler` is using `CommandNotFoundMessageProvider` +Internally, `CommandNotFoundResultHandler` is using `CommandNotFoundMessageProvider` which is a simple function taking a `ProviderContext` and returning a text message. Below is an example what a custom message provider might look like. diff --git a/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc b/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc index ab3318297..801f55f88 100644 --- a/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc @@ -1,11 +1,11 @@ [[using-shell-customization-logging]] = Logging -On default a _Spring Boot_ application will log messages into a console which +By default, a _Spring Boot_ application logs messages into a console which at minimum is annoying and may also mix output from a shell commands. -Fortunately there is a simple way to instruct logging changes via boot properties. +Fortunately, there is a simple way to instruct logging changes via Spring Boot properties. -Completely silence console logging by defining its pattern as an empty value. +To completely silence console logging, set the console's logging pattern to an empty value: [source, yaml] ---- @@ -14,7 +14,7 @@ logging: console: ---- -If you need log from a shell then write those into a file. +If you need log from a shell then write those into a file: [source, yaml] ---- @@ -23,7 +23,7 @@ logging: name: shell.log ---- -If you need different log levels. +If you need different log levels: [source, yaml] ---- @@ -34,8 +34,8 @@ logging: shell: debug ---- -Passing contiguration properties as command line options is not supported but -you can use any other ways supported by boot, for example. +Passing configuration properties as command line options is not supported, +but you can use other ways supported by Spring Boot, for example: [source, bash] ---- @@ -43,5 +43,5 @@ $ java -Dlogging.level.root=debug -jar demo.jar $ LOGGING_LEVEL_ROOT=debug java -jar demo.jar ---- -NOTE: In a GraalVM image settings are locked during compilation which means +NOTE: In a GraalVM image, settings are locked during compilation which means you can't change log levels at runtime. diff --git a/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc b/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc index 93cfe85d6..f2aa35934 100644 --- a/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc @@ -5,10 +5,9 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] If your shell application is made for exactly a single purpose having only one -command it may be beneficial to configure it for this. Property -`spring.shell.noninteractive.primary-command` if defined will disable all other -runners than `NonInteractiveShellRunner` and configures it to use -defined _Primary Command_. +command, it may be beneficial to configure it for this. If the property +`spring.shell.noninteractive.primary-command` is defined, it will disable all other +runners than `NonInteractiveShellRunner` and configures it to use the defined _Primary Command_. [source, yaml] ---- @@ -18,6 +17,6 @@ spring: primary-command: mycommand ---- -For example if you have a command `mycommand` with option `arg` -it had to be executed with ` mycommand --arg hi`, but with above -setting it can be executed with ` --arg hi`. +For example, if you have a command `mycommand` with option `arg` +that is expected to be executed with ` mycommand --arg hi` in a multi-command app, +then with the above configuration it can be executed with ` --arg hi`. diff --git a/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc b/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc index 242f3964d..ed4b7d942 100644 --- a/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc @@ -4,37 +4,35 @@ ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Current terminal implementations are rich in features and can usually show -something else that just plain text. For example a text can be styled to be +something else that just plain text. For example, a text can be styled to be _bold_ or have different colors. It's also common for terminals to be able -to show various characters from an unicode table like emoji's which are usually +to show various characters from a unicode table like emoji's which are usually used to make shell output more pretty. -Spring Shell supports these via it's theming framework which contains two parts, -firstly _styling_ can be used to change text type and secondly _figures_ how -some characters are shown. These two are then combined together as a _theme_. +Spring Shell supports these via it's theming framework which contains two parts. +Firstly, _styling_ can be used to change text type and secondly, _figures_ are used +to customize how characters are shown. These two parts are then combined as a _theme_. -More about _theming_ internals, see xref:appendices/techintro/theming.adoc[Theming]. +For more detail about _theming_ internals, refer to see xref:appendices/techintro/theming.adoc[Theming]. -NOTE: Default theme is named `default` but can be change using property -`spring.shell.theme.name`. Other built-in theme named `dump` uses -no styling for colors and tries to not use any special figures. +NOTE: Default theme is named `default` but can be changed using the property +`spring.shell.theme.name`. There is also another built-in theme named `dump` +that uses no styling for colors and tries to not use any special figures. -Modify existing style by overriding settings. +You can modify existing styles and figures by overriding the default settings: [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-style-class] ---- -Modify existing figures by overriding settings. - [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-figure-class] ---- -To create a new theme, create a `ThemeSettings` and provide your own _style_ -and _figure_ implementations. +You can also create a new theme, by creating a `ThemeSettings` and provide your own _style_ +and _figure_ implementations: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/execution.adoc b/spring-shell-docs/modules/ROOT/pages/execution.adoc index da91e10fd..b238d4033 100644 --- a/spring-shell-docs/modules/ROOT/pages/execution.adoc +++ b/spring-shell-docs/modules/ROOT/pages/execution.adoc @@ -60,5 +60,5 @@ default boolean run(String[] args) throws Exception { } ---- -IMPORTANT: This will the main api going forward and other existing methods taking boot's -`ApplicationArguments` has been deprecated and will be removed in future. +IMPORTANT: This will be the main api going forward and other existing methods taking boot's +`ApplicationArguments` have been deprecated and will be removed in a future release. diff --git a/spring-shell-docs/modules/ROOT/pages/testing/index.adoc b/spring-shell-docs/modules/ROOT/pages/testing/index.adoc index 9f9bd7ffa..5fa3a24f5 100644 --- a/spring-shell-docs/modules/ROOT/pages/testing/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/testing/index.adoc @@ -4,15 +4,14 @@ ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] -Testing cli application is difficult due to various reasons: +Testing CLI application is difficult due to various reasons: - There are differences between OS's. -- Within OS there may be different shell implementations in use. -- What goes into a shell and comes out from a shell my be totally - different what you see in shell itself due to control characters. -- Shell may feel syncronous but most likely it is not meaning when - someting is written into it, you can't assume next update in - in it is not final. +- Within the same OS there may be different shell implementations in use. +- What goes into a shell and comes out from a shell may be totally + different from what you see in the shell itself due to invisible control characters. +- The shell may feel synchronous but most likely it is not, meaning when + something is written into it, you can't assume next update in it is not final. NOTE: Testing support is currently under development and will be unstable for various parts. diff --git a/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc b/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc index ae6e37c0e..1c9437a48 100644 --- a/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc +++ b/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc @@ -3,11 +3,11 @@ ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] -Built in emulation uses terminal width 80 and height 24 on default. -Changing dimensions is useful if output would span into multiple -lines and you don't want to handle those cases in a tests. +Built-in emulation uses terminal width 80 and height 24 by default. +Changing dimensions is useful if the output would span multiple lines +and you don't want to handle those cases in a tests. -These can be changed using properties `spring.shell.test.terminal-width` +These settings can be changed using properties `spring.shell.test.terminal-width` or `spring.shell.test.terminal-height`. [source, java, indent=0] diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc index d281c9cb7..c5b78f9c1 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc @@ -6,16 +6,16 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/she `EventLoop` is a central place where all eventing will be orchestrated for a lifecycle of a component. Orchestration is usually needed around timings -of redraws and and component state updates. +of redraws and component state updates. -Everything in an event loop is represented as a Spring Message. +Everything in an event loop is represented as a Spring Message: [source, java, indent=0] ---- include::{snippets}/EventLoopSnippets.java[tag=plainevents] ---- -Selecting key events use a build-in filtering method _keyEvents()_. +Selecting key events use a built-in filtering method _keyEvents()_. [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/index.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/index.adoc index 01a249394..52920787b 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/events/index.adoc @@ -4,4 +4,4 @@ ifndef::snippets[:snippets: ../../../../test/java/org/springframework/shell/docs] -This section contains information about eventing. +This section contains information about event handling. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc index 6bb7ff193..4258b9d6b 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc @@ -6,16 +6,16 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/she Views have their own default bindings which can be changed. -You can subscribe into all key events: +You can subscribe to all key events: [source, java, indent=0] ---- include::{snippets}/KeyHandlingSnippets.java[tag=sample] ---- -`KeyEvent` is a record containing info about a binding coming out +`KeyEvent` is a record containing information about a binding coming out from a terminal. Some views allow you to register hot keys which are processed before -normal key handling. More about this can be found from +normal key handling. More about this can be found in xref:appendices/tui/viewdev.adoc#register-bindings[Register Bindings]. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc index b9d2ea4f3..de83add7e 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc @@ -4,12 +4,12 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] -You can subscribe into all mouse events: +You can subscribe to all mouse events: [source, java, indent=0] ---- include::{snippets}/MouseHandlingSnippets.java[tag=sample] ---- -`MouseEvent` is a record wrapping _x_ and _Y_ coordinates and +`MouseEvent` is a record wrapping _X_ and _Y_ coordinates and `org.jline.terminal.MouseEvent` from JLine library. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/index.adoc b/spring-shell-docs/modules/ROOT/pages/tui/index.adoc index 33a2d3753..8d4530988 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/index.adoc @@ -2,13 +2,13 @@ = Terminal UI :page-section-summary-toc: 1 -NOTE: Feature is experimental and subject to breaking changes until foundation +NOTE: This feature is experimental and is subject to breaking changes until foundation and related concepts around framework are getting more stable. _Terminal UI Framework_ is a toolkit to build rich console apps. This section is for those using existing features as is. If you're planning to go deeper possibly -creating your own components xref:appendices/tui/index.adoc[Terminal UI Appendix] -provides more detailed documentation. +by creating your own components, then check xref:appendices/tui/index.adoc[Terminal UI Appendix] +for more detailed documentation. TIP: xref:appendices/tui/catalog.adoc[Catalog Sample App] is a good place to study a real application. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc b/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc index 37d0d3f95..aa295d9a8 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc @@ -4,11 +4,11 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] -Lets start with a simple app which prints "hello world" in a view. +Let's start with a simple app which prints "hello world" in a view. [source, java, indent=0] ---- include::{snippets}/TerminalUiSnippets.java[tag=introsample] ---- There is not much to see here other than `TerminalUI` is a class handling -all logic aroung views and uses `View` as it's root view. +all logic around views and uses `View` as it's root view. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc b/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc index 1a54aeff1..086b734d2 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc @@ -6,8 +6,8 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/she `TerminalUI` is a main implementation to drive ui execution logic. == Create TerminalUI -You can build `TerminalUI` manually but recommended way is to use `TerminalUIBuilder` -build is autoconfigured for you and will set needed services. +You can build `TerminalUI` manually but the recommended way is to use `TerminalUIBuilder` +which is autoconfigured for you and will set needed services. [source, java, indent=0] ---- @@ -34,8 +34,8 @@ include::{snippets}/TerminalUiSnippets.java[tag=uirun] == Exiting App -If you want to exit from an app using normal _CTRL-Q_ key combination listen -events and request _interrupt_. +If you want to exit from an app using normal _CTRL-Q_ key combination, then +you need to register a listener for events and request to _interrupt_ the execution. [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/app.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/app.adoc index 91e6811cf..055613e03 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/app.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/app.adoc @@ -4,9 +4,9 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _AppView_ is a base implementation providing functionality to draw opinionated _application view_. -Inherits xref:tui/views/box.adoc[]. +This view inherits from xref:tui/views/box.adoc[]. -Generic idea is to have menu and status views which typically are xref:tui/views/menubar.adoc[] and +The generic idea is to have menu and status views which typically are xref:tui/views/menubar.adoc[] and xref:tui/views/statusbar.adoc[] respectively. Main content view is then whatever user want to show in it. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/box.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/box.adoc index a00611d4d..ff888d511 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/box.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/box.adoc @@ -5,7 +5,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _BoxView_ is a base implementation providing functionality to draw into a -bounded _Rectancle_. Only direct use of it is its `drawFunction` which +bounded _Rectangle_. Only direct use of it is its `drawFunction` which allows to do simple things without implementing a full custom `View`. @@ -15,10 +15,10 @@ include::{snippets}/BoxViewSnippets.java[tag=sample] ---- == Customisation -_BoxView_ as mostly being a base class contains some useful features -like if it should draw a border and what what are its paddings. +_BoxView_ is mostly being a base class that contains some useful features +like if it should draw a border and what are its paddings. Border can have a title and its color and focused color can be -defined. It's also possible to explicitely set background color +defined. It's also possible to explicitly set a background color which will override one from styling. == Default Bindings diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc index 73db8f641..0cacd035f 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc @@ -5,7 +5,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _ButtonView_ is a base implementation providing functionality to draw a button. -Inherits xref:tui/views/box.adoc[]. +_ButtonView_ inherits from xref:tui/views/box.adoc[]. [source, text] ---- @@ -23,7 +23,7 @@ include::{snippets}/ButtonViewSnippets.java[tag=sample] == Default Bindings -Default _key bindigs_ are: +Default _key bindings_ are: .Key |=== @@ -34,7 +34,7 @@ Default _key bindigs_ are: |=== -Default _mouse bindigs_ are: +Default _mouse bindings_ are: .Mouse |=== diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/dialog.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/dialog.adoc index 241b96923..8ad74e7c6 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/dialog.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/dialog.adoc @@ -5,7 +5,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _DialogView_ is a base implementation providing functionality to draw a dialog. -Inherits xref:tui/views/box.adoc[]. +_DialogView_ inherits from xref:tui/views/box.adoc[]. [source, text] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc index 89b3a693c..108f1c3cb 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc @@ -4,7 +4,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _GridView_ is a special type of view and its purpose is to layout other views -using a grid layout algorithms. Inherits xref:tui/views/box.adoc[]. +using a grid layout algorithms. _GridView_ inherits from xref:tui/views/box.adoc[]. [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/index.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/index.adoc index 9f245114e..3525d24a9 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/index.adoc @@ -4,4 +4,4 @@ ifndef::snippets[:snippets: ../../../../test/java/org/springframework/shell/docs] -Framework provides a build-in views which are documented below. +Spring Shell provides a built-in views which are documented below. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/input.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/input.adoc index b68377b7a..ac41a086e 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/input.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/input.adoc @@ -4,7 +4,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _InputView_ is a base implementation providing functionality to draw and modify -text in a bounded _Rectancle_. +text in a bounded _Rectangle_. [source, java, indent=0] ---- @@ -32,7 +32,7 @@ Default _view commands_ are: |=== -Default _key bindigs_ are: +Default _key bindings_ are: .Key |=== diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc index 0d531a5ab..51a567530 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc @@ -5,10 +5,10 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _ListView_ is a base implementation providing functionality to draw a list of -_items_. Inherits xref:tui/views/box.adoc[]. +_items_. _ListView_ inherits from xref:tui/views/box.adoc[]. _ListView_ is typed as its _item_ and can take any object. Further _item_ -processing happens in a _CellFactory_. For conveniance there is a support +processing happens in a _CellFactory_. For convenience, there is a support for generic higher level list feature showing checked states as normal _check_ and _radio_ types. Essentially what you can have is a list of items which are shown as is, shown where any items can have a checked @@ -63,7 +63,7 @@ Default _view commands_ are: |=== -Default _key bindigs_ are: +Default _key bindings_ are: .Key |=== @@ -83,7 +83,7 @@ Default _key bindigs_ are: |=== -Default _mouse bindigs_ are: +Default _mouse bindings_ are: .Mouse |=== diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/menu.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/menu.adoc index cbab5534a..c17521a39 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/menu.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/menu.adoc @@ -5,10 +5,10 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _MenuView_ is a base implementation providing functionality to draw a menu. -Inherits xref:tui/views/box.adoc[]. +_MenuView_ inherits from xref:tui/views/box.adoc[]. == Default Bindings -Default _key bindigs_ are: +Default _key bindings_ are: .Key |=== @@ -25,7 +25,7 @@ Default _key bindigs_ are: |=== -Default _mouse bindigs_ are: +Default _mouse bindings_ are: .Mouse |=== diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc index 22c443349..3a25c422e 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc @@ -5,7 +5,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _MenuBarView_ is a base implementation providing functionality to draw a menu bar. -Inherits xref:tui/views/box.adoc[]. +_MenuBarView_ inherits from xref:tui/views/box.adoc[]. [source, text] ---- @@ -24,7 +24,7 @@ include::{snippets}/MenuBarViewSnippets.java[tag=snippet1] ---- == Default Bindings -Default _key bindigs_ are: +Default _key bindings_ are: .Key |=== @@ -38,7 +38,7 @@ Default _key bindigs_ are: |=== -Default _mouse bindigs_ are: +Default _mouse bindings_ are: .Mouse |=== diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc index a1d2c2429..40fb891a2 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc @@ -4,25 +4,25 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] -_ProgressView_ is a base implementation providing functionality to draw a progress info. -Inherits xref:tui/views/box.adoc[]. +_ProgressView_ is a base implementation providing functionality to draw a progress information. +_ProgressView_ inherits from xref:tui/views/box.adoc[]. -_ProgressView_ draws its content using concepts described below +_ProgressView_ draws its content using concepts described below: * _ProgressState_ contains various info about a runtime state -** _tickStart_ Lower bound of tick value -** _tickEnd_ Upper bound of tick value -** _tickValue_ Current tick value -** _running_ Running state, either true or false -** _startTime_ Start time in millis when progress was started -** _updateTime_ Last known time in millis when progress has updated +** _tickStart_: Lower bound of tick value +** _tickEnd_: Upper bound of tick value +** _tickValue_: Current tick value +** _running_: Running state, either true or false +** _startTime_: Start time in millis when progress was started +** _updateTime_: Last known time in millis when progress has updated * _ProgressContext_ is a context used with _ProgressViewItem_ -** _description_ The description given to progress -** _state_ The _ProgressState_ -** _view_ The owning _ProgressView_ -** _spinner_ The _Spinner_ representation used with _ProgressView_ +** _description_: The description given to progress +** _state_: The _ProgressState_ +** _view_: The owning _ProgressView_ +** _spinner_: The _Spinner_ representation used with _ProgressView_ ** Other methods to help with item drawing -* _ProgressViewItem_ is a representation of a cell used in _ProgressView_ +* _ProgressViewItem_: is a representation of a cell used in _ProgressView_ There are few build-in items namely `text`, `spinner` and `percent`. @@ -42,7 +42,7 @@ include::example$tui-progress-1.cast[] == Customisation -Here's some examples for various customisations: +Here are some examples for various customisations: [source, java, indent=0] ---- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc b/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc index bee090bbb..0d6657154 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc +++ b/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc @@ -4,7 +4,7 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] _StatusBarView_ is a base implementation providing functionality to draw a status bar. -Inherits xref:tui/views/box.adoc[]. +_StatusBarView_ inherits from xref:tui/views/box.adoc[]. [source, text] ---- @@ -20,15 +20,15 @@ You can create a simple status bar with an item: include::{snippets}/StatusBarViewSnippets.java[tag=simple] ---- -Constructor can take array form which allows to lay out simple -item definitions in a _dsl_ style. +The constructor can take array form which allows to lay out simple +item definitions in a _dsl_ style: [source, java, indent=0] ---- include::{snippets}/StatusBarViewSnippets.java[tag=viaarray] ---- -Items support runnable actions which generally as executed when +Items support runnable actions which generally are executed when item is selected. It can also get attached to a hot key. [source, java, indent=0] diff --git a/spring-shell-docs/spring-shell-docs.gradle b/spring-shell-docs/spring-shell-docs.gradle index 8ec949a5c..e47f5c8ea 100644 --- a/spring-shell-docs/spring-shell-docs.gradle +++ b/spring-shell-docs/spring-shell-docs.gradle @@ -11,7 +11,12 @@ dependencies { implementation project(':spring-shell-starters:spring-shell-starter') implementation project(':spring-shell-starters:spring-shell-starter-test') implementation project(':spring-shell-samples:spring-shell-sample-catalog') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' } diff --git a/spring-shell-management/spring-shell-management.gradle b/spring-shell-management/spring-shell-management.gradle index 72ffb830d..084a39ac9 100644 --- a/spring-shell-management/spring-shell-management.gradle +++ b/spring-shell-management/spring-shell-management.gradle @@ -22,6 +22,5 @@ dependencies { api "org.antlr:ST4:$st4Version" api "commons-io:commons-io:$commonsIoVersion" api "com.google.jimfs:jimfs:$jimfsVersion" - api "com.google.code.findbugs:jsr305:$findbugsVersion" } } diff --git a/spring-shell-samples/spring-shell-sample-catalog/spring-shell-sample-catalog.gradle b/spring-shell-samples/spring-shell-sample-catalog/spring-shell-sample-catalog.gradle index 4a1e5dfcb..6efaa4d97 100644 --- a/spring-shell-samples/spring-shell-sample-catalog/spring-shell-sample-catalog.gradle +++ b/spring-shell-samples/spring-shell-sample-catalog/spring-shell-sample-catalog.gradle @@ -8,6 +8,11 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-starters:spring-shell-starter-jna') testImplementation project(':spring-shell-starters:spring-shell-starter-test') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' } diff --git a/spring-shell-samples/spring-shell-sample-commands/spring-shell-sample-commands.gradle b/spring-shell-samples/spring-shell-sample-commands/spring-shell-sample-commands.gradle index c1397b87a..c478f50cd 100644 --- a/spring-shell-samples/spring-shell-sample-commands/spring-shell-sample-commands.gradle +++ b/spring-shell-samples/spring-shell-sample-commands/spring-shell-sample-commands.gradle @@ -8,6 +8,11 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-starters:spring-shell-starter-jna') testImplementation project(':spring-shell-starters:spring-shell-starter-test') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' } diff --git a/spring-shell-samples/spring-shell-sample-commands/src/main/java/org/springframework/shell/samples/standard/FunctionCommands.java b/spring-shell-samples/spring-shell-sample-commands/src/main/java/org/springframework/shell/samples/standard/FunctionCommands.java index 1912d6288..2db749708 100644 --- a/spring-shell-samples/spring-shell-sample-commands/src/main/java/org/springframework/shell/samples/standard/FunctionCommands.java +++ b/spring-shell-samples/spring-shell-sample-commands/src/main/java/org/springframework/shell/samples/standard/FunctionCommands.java @@ -17,6 +17,7 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; +import org.springframework.shell.command.CommandHandlingResult; import org.springframework.shell.command.CommandRegistration; @Configuration @@ -25,28 +26,28 @@ public class FunctionCommands { @Bean public CommandRegistration commandRegistration1() { return CommandRegistration.builder() - .command("function", "command1") - .description("function sample") - .group("Function Commands") - .withTarget() + .command("function", "command1") + .description("function sample") + .group("Function Commands") + .withTarget() .function(ctx -> { String arg1 = ctx.getOptionValue("arg1"); return String.format("hi, arg1 value is '%s'", arg1); }) .and() - .withOption() + .withOption() .longNames("arg1") .and() - .build(); + .build(); } @Bean public CommandRegistration commandRegistration2() { return CommandRegistration.builder() - .command("function", "command2") - .description("function sample") - .group("Function Commands") - .withTarget() + .command("function", "command2") + .description("function sample") + .group("Function Commands") + .withTarget() .function(ctx -> { Boolean a = ctx.getOptionValue("a"); Boolean b = ctx.getOptionValue("b"); @@ -54,55 +55,163 @@ public CommandRegistration commandRegistration2() { return String.format("hi, boolean values for a, b, c are '%s' '%s' '%s'", a, b, c); }) .and() - .withOption() + .withOption() .shortNames('a') .type(boolean.class) .and() - .withOption() + .withOption() .shortNames('b') .type(boolean.class) .and() - .withOption() + .withOption() .shortNames('c') .type(boolean.class) .and() - .build(); + .build(); } @Bean public CommandRegistration commandRegistration3() { return CommandRegistration.builder() - .command("function", "command3") - .description("function sample") - .group("Function Commands") - .withTarget() + .command("function", "command3") + .description("function sample") + .group("Function Commands") + .withTarget() .consumer(ctx -> { String arg1 = ctx.getOptionValue("arg1"); ctx.getTerminal().writer() - .println(String.format("hi, arg1 value is '%s'", arg1)); + .println(String.format("hi, arg1 value is '%s'", arg1)); }) .and() - .withOption() + .withOption() .longNames("arg1") .and() - .build(); + .build(); } @Bean public CommandRegistration commandRegistration4() { return CommandRegistration.builder() - .command("function", "command4") - .description("function sample") - .group("Function Commands") - .withTarget() + .command("function", "command4") + .description("function sample") + .group("Function Commands") + .withTarget() .consumer(ctx -> { ctx.getTerminal().writer() - .println(String.format("hi, command is '%s'", ctx.getCommandRegistration().getCommand())); + .println(String.format("hi, command is '%s'", ctx.getCommandRegistration().getCommand())); }) .and() - .withOption() + .withOption() .longNames("arg1") .and() - .build(); + .build(); + } + + @Bean + public CommandRegistration commandRegistration5() { + return CommandRegistration.builder() + .command("function", "command5") + .description("function sample") + .group("Function Commands") + .withTarget(targetSpec -> { + targetSpec.function(ctx -> { + String arg1 = ctx.getOptionValue("arg1"); + return String.format("hi, arg1 value is '%s'", arg1); + }); + }) + .withOption(optionSpec -> { + optionSpec.longNames("arg1"); + }) + .build(); + } + + @Bean + public CommandRegistration commandRegistration6() { + return CommandRegistration.builder() + .command("function", "command6") + .description("function sample") + .group("Function Commands") + .withTarget(targetSpec -> { + targetSpec.function(ctx -> { + Boolean a = ctx.getOptionValue("a"); + Boolean b = ctx.getOptionValue("b"); + Boolean c = ctx.getOptionValue("c"); + return String.format("hi, boolean values for a, b, c are '%s' '%s' '%s'", a, b, c); + }); + }) + .withOption(optionSpec -> { + optionSpec.shortNames('a').type(boolean.class); + }) + .withOption(optionSpec -> { + optionSpec.shortNames('b').type(boolean.class); + }) + .withOption(optionSpec -> { + optionSpec.shortNames('c').type(boolean.class); + }) + .build(); + } + + + @Bean + public CommandRegistration commandRegistration7() { + return CommandRegistration.builder() + .command("function", "command7") + .description("function sample") + .group("Function Commands") + .withTarget(targetSpec -> { + targetSpec.consumer(ctx -> { + String arg1 = ctx.getOptionValue("arg1"); + ctx.getTerminal().writer() + .println(String.format("hi, arg1 value is '%s'", arg1)); + }); + }) + .withOption(optionSpec -> { + optionSpec.longNames("arg1"); + }) + .build(); + } + + @Bean + public CommandRegistration commandRegistration8() { + return CommandRegistration.builder() + .command("function", "command8") + .description("function sample") + .group("Function Commands") + .withTarget(targetSpec -> { + targetSpec.consumer(ctx -> { + ctx.getTerminal().writer() + .println(String.format("hi, command is '%s'", ctx.getCommandRegistration().getCommand())); + }); + }) + .withOption(optionSpec -> { + optionSpec.longNames("arg1"); + }) + .build(); + } + + @Bean + public CommandRegistration commandRegistration9() { + return CommandRegistration.builder() + .command("function", "command9") + .description("function sample") + .group("Function Commands") + .withTarget(targetSpec -> { + targetSpec.function(ctx -> { + throw new RuntimeException("Something went wrong"); + }); + }) + .withAlias( + aliasSpec -> { + aliasSpec.command("function", "command10"); + } + ) + .withErrorHandling( + errorHandlingSpec -> { + errorHandlingSpec.resolver((e) -> { + return CommandHandlingResult.of("Error handled: " + e.getMessage() + "\n"); + }); + } + ) + .build(); } } diff --git a/spring-shell-samples/spring-shell-sample-e2e/spring-shell-sample-e2e.gradle b/spring-shell-samples/spring-shell-sample-e2e/spring-shell-sample-e2e.gradle index c0975acc4..83b3ab2f8 100644 --- a/spring-shell-samples/spring-shell-sample-e2e/spring-shell-sample-e2e.gradle +++ b/spring-shell-samples/spring-shell-sample-e2e/spring-shell-sample-e2e.gradle @@ -8,6 +8,11 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-starters:spring-shell-starter-jna') testImplementation project(':spring-shell-starters:spring-shell-starter-test') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' } diff --git a/spring-shell-samples/spring-shell-sample-ffm/spring-shell-sample-ffm.gradle b/spring-shell-samples/spring-shell-sample-ffm/spring-shell-sample-ffm.gradle index 25a6f61fa..1c880bfbd 100644 --- a/spring-shell-samples/spring-shell-sample-ffm/spring-shell-sample-ffm.gradle +++ b/spring-shell-samples/spring-shell-sample-ffm/spring-shell-sample-ffm.gradle @@ -15,6 +15,11 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-starters:spring-shell-starter-ffm') testImplementation project(':spring-shell-starters:spring-shell-starter-test') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' } diff --git a/spring-shell-standard-commands/spring-shell-standard-commands.gradle b/spring-shell-standard-commands/spring-shell-standard-commands.gradle index eea116586..f70d0029a 100644 --- a/spring-shell-standard-commands/spring-shell-standard-commands.gradle +++ b/spring-shell-standard-commands/spring-shell-standard-commands.gradle @@ -8,5 +8,10 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-core') implementation project(':spring-shell-standard') - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') } diff --git a/spring-shell-standard/spring-shell-standard.gradle b/spring-shell-standard/spring-shell-standard.gradle index c471dbd29..4ec55e41b 100644 --- a/spring-shell-standard/spring-shell-standard.gradle +++ b/spring-shell-standard/spring-shell-standard.gradle @@ -7,6 +7,10 @@ description = 'Spring Shell Standard' dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-core') - compileOnly 'com.google.code.findbugs:jsr305' - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') } diff --git a/spring-shell-table/spring-shell-table.gradle b/spring-shell-table/spring-shell-table.gradle index 1e172096d..6d50dfa93 100644 --- a/spring-shell-table/spring-shell-table.gradle +++ b/spring-shell-table/spring-shell-table.gradle @@ -8,6 +8,10 @@ dependencies { management platform(project(":spring-shell-management")) api('org.springframework:spring-core') api('org.springframework:spring-context') - compileOnly 'com.google.code.findbugs:jsr305' - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') } diff --git a/spring-shell-test-autoconfigure/spring-shell-test-autoconfigure.gradle b/spring-shell-test-autoconfigure/spring-shell-test-autoconfigure.gradle index c740156ae..e13f37871 100644 --- a/spring-shell-test-autoconfigure/spring-shell-test-autoconfigure.gradle +++ b/spring-shell-test-autoconfigure/spring-shell-test-autoconfigure.gradle @@ -13,9 +13,10 @@ dependencies { implementation 'org.springframework:spring-test' implementation 'org.springframework.boot:spring-boot-autoconfigure' implementation 'org.springframework.boot:spring-boot-test-autoconfigure' - implementation 'org.springframework.boot:spring-boot-starter-test' - optional 'org.assertj:assertj-core' - optional 'org.junit.jupiter:junit-jupiter-api' + implementation 'org.springframework.boot:spring-boot-test' + implementation 'org.junit.jupiter:junit-jupiter-engine' + implementation 'org.junit.platform:junit-platform-launcher' + testImplementation 'org.assertj:assertj-core' testImplementation 'org.awaitility:awaitility' annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor' } diff --git a/spring-shell-test/spring-shell-test.gradle b/spring-shell-test/spring-shell-test.gradle index bde8d398a..0a8093627 100644 --- a/spring-shell-test/spring-shell-test.gradle +++ b/spring-shell-test/spring-shell-test.gradle @@ -9,6 +9,11 @@ dependencies { implementation project(':spring-shell-core') optional 'org.assertj:assertj-core' optional 'org.junit.jupiter:junit-jupiter-api' - testImplementation 'org.springframework.boot:spring-boot-starter-test' + testImplementation('org.springframework.boot:spring-boot-test') + testImplementation('org.junit.jupiter:junit-jupiter-engine') + testImplementation('org.junit.jupiter:junit-jupiter-params') + testImplementation('org.junit.platform:junit-platform-launcher') + testImplementation("org.mockito:mockito-junit-jupiter") + testImplementation('org.assertj:assertj-core') testImplementation 'org.awaitility:awaitility' }