Skip to content

Commit c88cc9e

Browse files
alexey-pelykhalexey-pelykh
committed
(feat) java.utils.regex-alike minimum viable API
1 parent ddda144 commit c88cc9e

File tree

7 files changed

+1229
-14
lines changed

7 files changed

+1229
-14
lines changed

‎README.md

+113-14
Original file line numberDiff line numberDiff line change
@@ -11,24 +11,82 @@ library author [Philip Hazel](https://github.com/PhilipHazel) and its contributo
1111

1212
## Usage
1313

14-
To use the PCRE4J library in your project, add the following dependency to your `pom.xml` file:
14+
The PCRE4J library provides several APIs to interact with the PCRE library:
15+
- `java.util.regex`-alike API via `org.pcre4j.regex.Pattern` and `org.pcre4j.regex.Matcher`
16+
- The PCRE4J API via `org.pcre4j.Pcre2Code` and related classes
17+
- The `libpcre2` direct API via backends that implement `org.pcre4j.api.IPcre2`
18+
19+
### Quick Start with `java.util.regex`-alike API
20+
21+
Add the following dependencies to your `pom.xml` file:
22+
23+
```xml
24+
<dependencies>
25+
<dependency>
26+
<groupId>org.pcre4j</groupId>
27+
<artifactId>regex</artifactId>
28+
<version>0.0.0</version>
29+
</dependency>
30+
<dependency>
31+
<groupId>org.pcre4j</groupId>
32+
<!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
33+
<artifactId>jna</artifactId>
34+
<!-- <artifactId>ffm</artifactId> -->
35+
<version>0.0.0</version>
36+
</dependency>
37+
</dependencies>
38+
```
39+
40+
Proceed using the PCRE4J library in your Java code similarly like if you were using the `java.util.regex` package:
41+
42+
```java
43+
import org.pcre4j.Pcre4j;
44+
// TODO: Select one of the following imports for the backend you want to use:
45+
import org.pcre4j.jna.Pcre2;
46+
// import org.pcre4j.ffm.Pcre2;
47+
import org.pcre4j.regex.Pattern;
48+
49+
public class Usage {
50+
static {
51+
Pcre4j.setup(new Pcre2());
52+
}
53+
54+
public static String[] example(String pattern, String subject) {
55+
final var matcher = Pattern.compile(pattern).matcher(subject);
56+
if (matcher.find()) {
57+
final var groups = new String[matcher.groupCount() + 1];
58+
for (var i = 0; i < groups.length; i++) {
59+
groups[i] = matcher.group(i);
60+
}
61+
return groups;
62+
}
63+
return null;
64+
}
65+
}
66+
```
67+
68+
### Advanced Usage via PCRE4J API
69+
70+
Add the following dependencies to your `pom.xml` file:
1571

1672
```xml
17-
<dependency>
18-
<groupId>org.pcre4j</groupId>
19-
<artifactId>lib</artifactId>
20-
<version>0.0.0</version>
21-
</dependency>
22-
<dependency>
23-
<groupId>org.pcre4j</groupId>
24-
<!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
25-
<artifactId>jna</artifactId>
26-
<!-- <artifactId>ffm</artifactId> -->
27-
<version>0.0.0</version>
28-
</dependency>
73+
<dependencies>
74+
<dependency>
75+
<groupId>org.pcre4j</groupId>
76+
<artifactId>lib</artifactId>
77+
<version>0.0.0</version>
78+
</dependency>
79+
<dependency>
80+
<groupId>org.pcre4j</groupId>
81+
<!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
82+
<artifactId>jna</artifactId>
83+
<!-- <artifactId>ffm</artifactId> -->
84+
<version>0.0.0</version>
85+
</dependency>
86+
</dependencies>
2987
```
3088

31-
Then, you can use the PCRE4J library in your Java code as follows:
89+
Proceed using the PCRE4J library in your Java code:
3290

3391
```java
3492
import org.pcre4j.Pcre2Code;
@@ -65,6 +123,47 @@ public class Usage {
65123
}
66124
```
67125

126+
### Low-Level Usage
127+
128+
Add the following dependencies to your `pom.xml` file:
129+
130+
```xml
131+
<dependencies>
132+
<dependency>
133+
<groupId>org.pcre4j</groupId>
134+
<!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
135+
<artifactId>jna</artifactId>
136+
<!-- <artifactId>ffm</artifactId> -->
137+
<version>0.0.0</version>
138+
</dependency>
139+
</dependencies>
140+
```
141+
142+
Proceed using the `libpcre2` API in your Java code:
143+
144+
```java
145+
// TODO: Select one of the following imports for the backend you want to use:
146+
import org.pcre4j.jna.Pcre2;
147+
// import org.pcre4j.ffm.Pcre2;
148+
149+
public class Usage {
150+
public static void example() {
151+
final var pcre2 = new Pcre2();
152+
153+
final var errorcode = new int[1];
154+
final var erroroffset = new long[1];
155+
final var code = pcre2.compile("pattern", 0, errorcode, erroroffset, 0);
156+
if (code == 0) {
157+
throw new RuntimeException(
158+
"PCRE2 compilation failed with error code " + errorcode[0] + " at offset " + erroroffset[0]
159+
);
160+
}
161+
162+
api.codeFree(code);
163+
}
164+
}
165+
```
166+
68167
## Backends
69168

70169
The PCRE4J library supports several backends to invoke the `pcre2` API.

‎regex/build.gradle.kts

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
/*
2+
* Copyright (C) 2024 Oleksii PELYKH
3+
*
4+
* This file is a part of the PCRE4J. The PCRE4J is free software: you can redistribute it and/or modify it under the
5+
* terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the
6+
* License, or (at your option) any later version.
7+
*
8+
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
9+
* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
10+
* details.
11+
*
12+
* You should have received a copy of the GNU Lesser General Public License along with this program. If not, see
13+
* <https://www.gnu.org/licenses/>.
14+
*/
15+
plugins {
16+
`java-library`
17+
`maven-publish`
18+
signing
19+
}
20+
21+
repositories {
22+
mavenCentral()
23+
}
24+
25+
dependencies {
26+
api(project(":api"))
27+
api(project(":lib"))
28+
testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
29+
testImplementation(project(":jna"))
30+
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
31+
}
32+
33+
configurations {
34+
implementation {
35+
resolutionStrategy.failOnVersionConflict()
36+
}
37+
}
38+
39+
sourceSets {
40+
main {
41+
java.srcDir("src/main/java")
42+
}
43+
}
44+
45+
java {
46+
sourceCompatibility = JavaVersion.VERSION_21
47+
targetCompatibility = JavaVersion.VERSION_21
48+
49+
toolchain {
50+
languageVersion = JavaLanguageVersion.of(21)
51+
}
52+
53+
withSourcesJar()
54+
withJavadocJar()
55+
}
56+
57+
tasks.withType<Test> {
58+
useJUnitPlatform()
59+
}
60+
61+
tasks.named<Jar>("sourcesJar") {
62+
duplicatesStrategy = DuplicatesStrategy.INCLUDE
63+
}
64+
65+
publishing {
66+
publications {
67+
create<MavenPublication>("mavenJava") {
68+
from(components["java"])
69+
70+
groupId = "org.pcre4j"
71+
artifactId = project.name
72+
version = findProperty("pcre4j.version") as String? ?: "0.0.0-SNAPSHOT"
73+
74+
pom {
75+
name = "org.pcre4j:${project.name}"
76+
description = "PCRE4J java.util.regex-alike API"
77+
url = "https://pcre4j.org"
78+
79+
licenses {
80+
license {
81+
name = "GNU Lesser General Public License v3.0"
82+
url = "https://www.gnu.org/licenses/lgpl-3.0.txt"
83+
}
84+
}
85+
developers {
86+
developer {
87+
name = "Alexey Pelykh"
88+
email = "[email protected]"
89+
organization = "The PCRE4J Project"
90+
organizationUrl = "https://pcre4j.org"
91+
92+
}
93+
}
94+
scm {
95+
connection = "scm:git:git://github.com/alexey-pelykh/pcre4j.git"
96+
developerConnection = "scm:git:ssh://github.com:alexey-pelykh/pcre4j.git"
97+
url = "https://github.com/alexey-pelykh/pcre4j"
98+
}
99+
}
100+
}
101+
}
102+
103+
repositories {
104+
maven {
105+
name = "GitHubPackages"
106+
url = uri("https://maven.pkg.github.com/" + System.getenv("GITHUB_REPOSITORY"))
107+
credentials {
108+
username = System.getenv("GITHUB_ACTOR")
109+
password = System.getenv("GITHUB_TOKEN")
110+
}
111+
}
112+
113+
maven {
114+
name = "OSSRH"
115+
url = uri("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
116+
credentials {
117+
username = System.getenv("OSSRH_USERNAME")
118+
password = System.getenv("OSSRH_TOKEN")
119+
}
120+
}
121+
}
122+
}
123+
124+
signing {
125+
useInMemoryPgpKeys(
126+
System.getenv("GPG_PRIVATE_KEY"),
127+
System.getenv("GPG_PASSPHRASE")
128+
)
129+
sign(publishing.publications["mavenJava"])
130+
}

0 commit comments

Comments
 (0)