Skip to content

Commit de953a4

Browse files
leventovleventov
committed
More Readme fixes
1 parent b1d11e1 commit de953a4

1 file changed

Lines changed: 98 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ be source options), the occurrences in the template that correspond to the speci
252252
are recognized as neutral, other occurrences are recognized as deliberately long or short:
253253

254254
Source option | Occurrence in template | Recognized as | Target option | Specialization outcome
255-
---
255+
------------- | ---------------------- | ------------- | ------------- | ----------------------
256256
"char" | `CharCursor` | neutral | "bool" | `BoolCursor`
257257
"char" | `CharCursor` | neutral | "boolean" | `BooleanCursor`
258258
"char" | `CharacterCursor` | long | "bool" | `BooleanCursor`
@@ -274,11 +274,11 @@ and `/* define */` blocks.
274274

275275
Options of non Java type dimensions intended for specialization must start with a capital letter:
276276
`/* with Foo|Bar myDimension */`, not `/* with foo|bar myDimension */` (but lowercase non Java type
277-
options can be used to mask outer dimensions - see the [section about `/* with */` blocks below](
278-
#-with--blocks), and in conjunction with generics structures like `/*<>*/` - see the [corresponding
279-
section below](#generics-structures--extends-super-)). Options can include several words in camel
280-
case: `/* with NoElements|SomeElements numElements */`. JPSG replaces textual occurrences of source
281-
non Java type options in three forms:
277+
options can be used to mask outer dimensions - see the [section about `/* with */` blocks below
278+
](#-with--blocks), and in conjunction with generics structures like `/*<>*/` - see the
279+
[corresponding section below](#generics-structures--extends-super-)). Options can include several
280+
words in camel case: `/* with NoElements|SomeElements numElements */`. JPSG replaces textual
281+
occurrences of source non Java type options in three forms:
282282
- Camel case: "NoElements", "Foo".
283283
- Lower case: "noElements", "foo".
284284
- Upper case with underscores between words: "NO_ELEMENTS", "FOO".
@@ -824,98 +824,102 @@ configure([generateJavaSpecializations, generateTestJavaSpecializations]) {
824824
```
825825

826826
#### Properties
827+
##### `String defaultTypes`
828+
For all template files without `/* with */` blocks in the beginning JPSG attempts to deduce
829+
dimensions from the name of the template file, taking possible options from this `defaultTypes`
830+
configuration. See [more details](#with-default-types) in the section about `/* with */` blocks.
827831

828-
- **`String defaultTypes`** <br>
829-
&nbsp;&nbsp;&nbsp;&nbsp;For all template files without `/* with */` blocks in the beginning JPSG
830-
attempts to deduce dimensions from the name of the template file, taking possible options from
831-
this `defaultTypes` configuration. See [more details](#with-default-types) in the section about
832-
`/* with */` blocks. <br>
833-
Format: [`<javaTypeOptions>`](#dimensions-bnf). <br>
834-
Default value: `byte|char|short|int|long|float|double`
835-
- **`File source`** <br>
836-
&nbsp;&nbsp;&nbsp;&nbsp;Source directory which JPSG traverses and considers all files in it as
837-
template files. <br>
838-
Default value: <code>src/<i>sourceSet</i>/javaTemplates/</code> or
839-
<code>src/<i>sourceSet</i>/resourceTemplates/</code>, see the [directory layout
840-
](#directory-layout).
841-
- **`File target`** <br>
842-
&nbsp;&nbsp;&nbsp;&nbsp;Target directory where JPSG puts specialized sources. <br>
843-
Default value: `${project.buildDir}/generated-src/jpsg/${sourceSet.name}`.
832+
Format: [`<javaTypeOptions>`](#dimensions-bnf).
833+
834+
Default value: `byte|char|short|int|long|float|double`.
835+
836+
##### `File source`
837+
Source directory which JPSG traverses and considers all files in it as template files.
838+
839+
Default value: <code>src/<i>sourceSet</i>/javaTemplates/</code> or
840+
<code>src/<i>sourceSet</i>/resourceTemplates/</code>, see the [directory layout](#directory-layout).
841+
842+
##### `File target`
843+
Target directory where JPSG puts specialized sources.
844+
845+
Default value: `${project.buildDir}/generated-src/jpsg/${sourceSet.name}`.
844846

845847
#### Methods
846-
- **`never(String... options)`** <br>
847-
&nbsp;&nbsp;&nbsp;&nbsp;For all dimensions, defined in the beginnings of template files in
848-
`/* with */` blocks, or deduced automatically by JPSG (see `defaultTypes` property above), or
849-
defined inside template files at any level of nesting, JPSG will skip generating code for the
850-
specified options. `never()` may be called several times, adding more options to skip.
851-
852-
`options` parameter format: [`<options>`](#dimensions-bnf).
853-
854-
Example:
855-
```groovy
856-
never("byte|short", "char") // Never generate code for byte, short, char types
857-
never "Assert" // Additionally, don't generate code for non-Java type `Assert` option
858-
```
859-
- **`exclude(String... conditions)`** <br>
860-
&nbsp;&nbsp;&nbsp;&nbsp;JPSG doesn't generate specialization files for dimension contexts (either
861-
determined by `/* with */` blocks in the beginnings of the template files, or deduced using
862-
`defaultTypes`) that match any of the conditions passed to `exclude()`. In other words, each
863-
exclusion condition is virtually added to [an `/* if */` block in the beginning of each template
864-
file](#template-file-beginning-if) like the following:
865-
```java
866-
/* with <some explicitly defined dimensions (may be absent)> */
867-
/* if !(exclusionCondition1) && ... && !(exclusionConditionN) */
868-
/* if <some explicit, file-specific condition (may be absent) > */
869-
... The rest of the template file
870-
```
871-
While conditions in explicit `/* if */` blocks can only reference the existing (defined or deduced)
872-
dimensions, exclusion conditions specified via `exclude()` may reference some dimensions that are
873-
not present in every template file. Such exclusion conditions don't match and therefore don't make
874-
JPSG to skip any context specialization for the template files which don't define some dimensions
875-
from these exclusion conditions.
876-
877-
Semantics of conditions are described in detain in the section about [`/* if */` blocks](
878-
#if-blocks).
879-
880-
Exclusion conditions are useful when you want to suppress generation for some combinations of
881-
dimension options consistently in all template files. `exclude()` allows to not write the same
882-
`/* if */` block in the beginning of each template file.
883-
884-
`conditions` parameter format: [`<simple-condition>`](#conditions-bnf).
885-
886-
Example:
887-
```groovy
888-
exclude("object key byte|short|char|object value", "byte key short|char value")
889-
exclude "Disabled extraChecks Enabled advancedStatistics"
890-
```
891-
- **`with(String... dimensions)`** <br>
892-
&nbsp;&nbsp;&nbsp;&nbsp;JPSG adds the provided dimensions to the generation contexts in each
893-
template file. Each dimension must have a single option.
894-
895-
Note that JPSG adds the provided dimensions to the context of a template file after applying the
896-
exclusion conditions (specified via `exclude()`) and before filtering specializations with the
897-
explicit `/* if */` block in the beginning of the template file (if present). So the beginning of
898-
each template file virtually looks like the following:
899-
```java
900-
/* with <some explicitly defined dimensions (may be absent)> */
901-
/* if !(exclusionCondition1) && ... && !(exclusionConditionN) */
902-
/* with providedDimension1 ... providedDimensionM */
903-
/* if <some explicit, file-specific condition (may be absent) > */
904-
... The rest of the template file
905-
```
848+
#####`never(String... options)`
849+
For all dimensions, defined in the beginnings of template files in `/* with */` blocks, or deduced
850+
automatically by JPSG (see `defaultTypes` property above), or defined inside template files at any
851+
level of nesting, JPSG will skip generating code for the specified options. `never()` may be called
852+
several times, adding more options to skip.
853+
854+
`options` parameter format: [`<options>`](#dimensions-bnf).
855+
856+
Example:
857+
```groovy
858+
never("byte|short", "char") // Never generate code for byte, short, char types
859+
never "Assert" // Additionally, don't generate code for non-Java type `Assert` option
860+
```
861+
862+
##### `exclude(String... conditions)`
863+
JPSG doesn't generate specialization files for dimension contexts (either determined by `/* with */`
864+
blocks in the beginnings of the template files, or deduced using `defaultTypes`) that match any of
865+
the conditions passed to `exclude()`. In other words, each exclusion condition is virtually added to
866+
[an `/* if */` block in the beginning of each template file](#template-file-beginning-if) like the
867+
following:
868+
```java
869+
/* with <some explicitly defined dimensions (may be absent)> */
870+
/* if !(exclusionCondition1) && ... && !(exclusionConditionN) */
871+
/* if <some explicit, file-specific condition (may be absent) > */
872+
... The rest of the template file
873+
```
874+
While conditions in explicit `/* if */` blocks can only reference the existing (defined or deduced)
875+
dimensions, exclusion conditions specified via `exclude()` may reference some dimensions that are
876+
not present in every template file. Such exclusion conditions don't match and therefore don't make
877+
JPSG to skip any context specialization for the template files which don't define some dimensions
878+
from these exclusion conditions.
879+
880+
Semantics of conditions are described in detain in the section about [`/* if */` blocks
881+
](#-if--blocks).
882+
883+
Exclusion conditions are useful when you want to suppress generation for some combinations of
884+
dimension options consistently in all template files. `exclude()` allows to not write the same
885+
`/* if */` block in the beginning of each template file.
886+
887+
`conditions` parameter format: [`<simple-condition>`](#conditions-bnf).
888+
889+
Example:
890+
```groovy
891+
exclude("object key byte|short|char|object value", "byte key short|char value")
892+
exclude "Disabled extraChecks Enabled advancedStatistics"
893+
```
894+
895+
##### `with(String... dimensions)`
896+
JPSG adds the provided dimensions to the generation contexts in each template file. Each dimension
897+
must have a single option.
906898

907-
`with()` allows to enrich the generation contexts in all template files without adding them in to
908-
the `/* with */` block in the beginning of each template file.
899+
Note that JPSG adds the provided dimensions to the context of a template file after applying the
900+
exclusion conditions (specified via `exclude()`) and before filtering specializations with the
901+
explicit `/* if */` block in the beginning of the template file (if present). So the beginning of
902+
each template file virtually looks like the following:
903+
```java
904+
/* with <some explicitly defined dimensions (may be absent)> */
905+
/* if !(exclusionCondition1) && ... && !(exclusionConditionN) */
906+
/* with providedDimension1 ... providedDimensionM */
907+
/* if <some explicit, file-specific condition (may be absent) > */
908+
... The rest of the template file
909+
```
910+
911+
`with()` allows to enrich the generation contexts in all template files without adding them in to
912+
the `/* with */` block in the beginning of each template file.
909913

910-
`with()` dimension may also be used in conjunction with [`/* print */` structures
911-
](#print-the-current-option-for-a-dimension) to "macro print" something in template files during
912-
generation.
914+
`with()` dimension may also be used in conjunction with [`/* print */` structures
915+
](#print-the-current-option-for-a-dimension) to "macro print" something in template files during
916+
generation.
913917

914-
`dimensions` parameter format: [`<dimensions>`](#dimensions-bnf). Every dimension must have only
915-
a single option.
918+
`dimensions` parameter format: [`<dimensions>`](#dimensions-bnf). Every dimension must have only a
919+
single option.
916920

917-
Example:
918-
```groovy
919-
with("Enabled extraChecks Disabled advancedStatistics", "Assert extraCheckStyle")
920-
with "java8 minSupportedJavaVersion"
921-
```
921+
Example:
922+
```groovy
923+
with("Enabled extraChecks Disabled advancedStatistics", "Assert extraCheckStyle")
924+
with "java8 minSupportedJavaVersion"
925+
```

0 commit comments

Comments
 (0)