add package matcher section to user guide#1672
Conversation
| (exactly one more segment after `com.myapp`). | ||
|
|
||
| | `com.myapp..` | ||
| | All five packages (any number of segments under `com.myapp`, including zero). |
There was a problem hiding this comment.
"including zero" is currently not fully demonstrated as there is no example class in the root package.
Maybe add a class there as well?
I haven't found any referecne of the classes so far, so it might be not relevant
There was a problem hiding this comment.
Not sure if I get this comment: Do you suggest to extend the example by a sixth class e.g. com.myapp.ExampleClass to demonstrate the statement "including zero" better?
Let me rephrase this part and avoid "including zero". However, this does not mean that I'm against adding a class in the com.myapp package at all.
| i.e. any number of package segments (including zero). | ||
|
|
||
| | `(*)` | ||
| | Like `*`, but additionally _captures_ the matched segment, |
There was a problem hiding this comment.
I find no explanation of what it means that it is captured.
Can you access it later froim somewhere in the test? can you have a back reference in the match string?
apart from
`com.myapp.controller` (group 1 = `controller`) and
`com.myapp.service` (group 1 = `service`).
The deeper packages do not match because `(*)` allows only a single segment.
I find no information about that part.
What is the use of group1?
Is there any beyond allowing
com.myapp.(*)..
which seems to be the only way to exclude the parent package com.myapp. Or is that even excluded because there is no class in it? (I don't think so)
The section in file 8 adds some usage of it. Maybe link to that section as usage hint from here?
There was a problem hiding this comment.
See SlicesRuleDefinition, which can even make use of multiple capturing groups, see Slice.as.
There was a problem hiding this comment.
@hankem the file 8 talks about Slices and tests of them, so I think we mean the same thing.
Just from documentation here, I have no idea what these groups are used for
There was a problem hiding this comment.
The immediate effect is that captured substrings can be obtained from PackageMatcher.match's Result's getGroup(int) (similar to java.util.regex.MatchResult#group(int)).
Slices according to package identifiers are just a prominent use case.
There was a problem hiding this comment.
First of all: thanks Stefan for raising this question. To me the use-cases for capturing and groups here are also not that clear based on the JavaDoc in PackageMatcher..
Based on this discussion I think we should mention that they can be obtained programmatically, as outlined by Manfred. Furthermore, I like the idea of linking to file 8 where one exemplary use-case of this feature is documented.
There was a problem hiding this comment.
It's absolutely fair to document that capturing groups are relevant for the result of {@link #match}.
Slices are a good example; the architecture rules wouldn't allow a reference from PackageMatcher (in core) to Slices (in library), but the JavaDoc might not be covered... 😅
| infixes, and then write assertions against those slices. At the moment this is for example: | ||
| infixes, and then write assertions against those slices. The `matching(..)` argument follows | ||
| the package pattern syntax described in <<Package Identifiers>>, where the parentheses | ||
| `(*)` / `(**)` mark the captured segment(s) that are used as slice identifiers. |
There was a problem hiding this comment.
this renders weirdly for me as "() / (*)", but
`+++(*)+++` / `+++(**)+++`
instead works fine (+++ means "skip all inline styling).
This is lso works but seems to be the variant for larger blocks
`pass:[(*)]` / `pass:[(**)]`
The parser is confused by multiple stars meaning a bold section
|
Thanks for all the feedback - I implemented it as discussed above. I also fixed the local docs setup as part of this task. This lead to changes in the committed html docs files (see commit f592b4c) which only contains the changes in the generated files. |
* add a detailed section to the core API section, as PackageMatching resides there. * reference the detailed section where the current user guide already touches the topic Signed-off-by: Andreas Zöller <andreas.zoeller@tngtech.com>
The `docker compose up` based dev setup for the ArchUnit website was broken in several independent ways. This commit gets it working again end-to-end. * replace unmaintained base-image with a current ruby base image. Install bundler version according to gemlock.file * avoid incremental jekyll serve mode as it does not rebuild on configuration change * minor changes to docker-compose.yml: ** drop obsolete top-level version ** quote port mapping * add documentation how to rebuild the user guide to README Signed-off-by: Andreas Zöller <andreas.zoeller@tngtech.com>
* add JavaDoc links where reasonable * additional explanation of capturing feature and its usage in slicing * fix rendering errors Signed-off-by: Andreas Zöller <andreas.zoeller@tngtech.com>
3fb2655 to
2259426
Compare
| next section, does not depend on whether the classes were imported from the classpath or | ||
| some JAR / folder. | ||
|
|
||
| === Package Identifiers |
There was a problem hiding this comment.
I feel that Package Identifiers should be inside Domain, not at the same level as Import and Domain.
| === Package Identifiers | |
| ==== Package Identifiers |
3 participants
Closes #1507