1
0
Fork 0
mirror of https://github.com/pgpainless/pgpainless.git synced 2024-12-23 03:17:58 +01:00

Document SelectUserIds

This commit is contained in:
Paul Schaub 2022-04-04 12:19:07 +02:00
parent 4aaa242d64
commit bfbe03f9e0
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311

View file

@ -9,19 +9,44 @@ import java.util.List;
import org.bouncycastle.openpgp.PGPKeyRing;
import org.pgpainless.PGPainless;
import org.pgpainless.key.info.KeyRingInfo;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* Filter for selecting user-ids from keys and from lists.
*/
public abstract class SelectUserId {
/**
* Return true, if the given user-id is accepted by this particular filter, false otherwise.
*
* @param userId user-id
* @return acceptance of the filter
*/
protected abstract boolean accept(String userId);
public List<String> selectUserIds(PGPKeyRing keyRing) {
/**
* Select all currently valid user-ids of the given key ring.
*
* @param keyRing public or secret key ring
* @return valid user-ids
*/
@Nonnull
public List<String> selectUserIds(@Nonnull PGPKeyRing keyRing) {
List<String> userIds = PGPainless.inspectKeyRing(keyRing).getValidUserIds();
return selectUserIds(userIds);
}
public List<String> selectUserIds(List<String> userIds) {
/**
* Select all acceptable (see {@link #accept(String)}) from the given list of user-ids.
*
* @param userIds list of user-ids
* @return sub-list of acceptable user-ids
*/
@Nonnull
public List<String> selectUserIds(@Nonnull List<String> userIds) {
List<String> selected = new ArrayList<>();
for (String userId : userIds) {
if (accept(userId)) {
@ -31,11 +56,25 @@ public abstract class SelectUserId {
return selected;
}
/**
* Return the first valid, acceptable user-id from the given public or secret key ring.
*
* @param keyRing public or secret key ring
* @return first matching valid user-id or null
*/
@Nullable
public String firstMatch(PGPKeyRing keyRing) {
return firstMatch(selectUserIds(keyRing));
}
public String firstMatch(List<String> userIds) {
/**
* Return the first valid, acceptable user-id from the list of user-ids.
*
* @param userIds list of user-ids
* @return first matching valid user-id or null
*/
@Nullable
public String firstMatch(@Nonnull List<String> userIds) {
for (String userId : userIds) {
if (accept(userId)) {
return userId;
@ -44,6 +83,12 @@ public abstract class SelectUserId {
return null;
}
/**
* Filter that filters for user-ids which contain the given <pre>query</pre> as a substring.
*
* @param query query
* @return filter
*/
public static SelectUserId containsSubstring(@Nonnull CharSequence query) {
return new SelectUserId() {
@Override
@ -53,6 +98,12 @@ public abstract class SelectUserId {
};
}
/**
* Filter that filters for user-ids which match the given <pre>query</pre> exactly.
*
* @param query query
* @return filter
*/
public static SelectUserId exactMatch(@Nonnull CharSequence query) {
return new SelectUserId() {
@Override
@ -62,6 +113,12 @@ public abstract class SelectUserId {
};
}
/**
* Filter that filters for user-ids which start with the given <pre>substring</pre>.
*
* @param substring substring
* @return filter
*/
public static SelectUserId startsWith(@Nonnull CharSequence substring) {
String string = substring.toString();
return new SelectUserId() {
@ -72,55 +129,99 @@ public abstract class SelectUserId {
};
}
/**
* Filter that filters for user-ids which contain the given <pre>email</pre> address.
* Note: This only accepts user-ids which properly have the email address surrounded by angle brackets.
*
* The argument <pre>email</pre> can both be a plain email address (<pre>"foo@bar.baz"</pre>),
* or surrounded by angle brackets (<pre>"<foo@bar.baz>"</pre>, the result of the filter will be the same.
*
* @param email email address
* @return filter
*/
public static SelectUserId containsEmailAddress(@Nonnull CharSequence email) {
String string = email.toString();
return containsSubstring(string.matches("^<.+>$") ? string : '<' + string + '>');
}
/**
* Filter that filters for valid user-ids on the given <pre>keyRing</pre> only.
*
* @param keyRing public / secret keys
* @return filter
*/
public static SelectUserId validUserId(PGPKeyRing keyRing) {
final KeyRingInfo info = PGPainless.inspectKeyRing(keyRing);
return new SelectUserId() {
@Override
protected boolean accept(String userId) {
return PGPainless.inspectKeyRing(keyRing).isUserIdValid(userId);
return info.isUserIdValid(userId);
}
};
}
public static SelectUserId and(SelectUserId... strategies) {
/**
* Filter that filters for user-ids which pass all the given <pre>filters</pre>.
*
* @param filters filters
* @return filter
*/
public static SelectUserId and(SelectUserId... filters) {
return new SelectUserId() {
@Override
protected boolean accept(String userId) {
boolean accept = true;
for (SelectUserId strategy : strategies) {
accept &= strategy.accept(userId);
for (SelectUserId filter : filters) {
accept &= filter.accept(userId);
}
return accept;
}
};
}
public static SelectUserId or(SelectUserId... strategies) {
/**
* Filter that filters for user-ids which pass at least one of the given <pre>filters</pre>>.
*
* @param filters filters
* @return filter
*/
public static SelectUserId or(SelectUserId... filters) {
return new SelectUserId() {
@Override
protected boolean accept(String userId) {
boolean accept = false;
for (SelectUserId strategy : strategies) {
accept |= strategy.accept(userId);
for (SelectUserId filter : filters) {
accept |= filter.accept(userId);
}
return accept;
}
};
}
public static SelectUserId not(SelectUserId strategy) {
/**
* Filter that inverts the result of the given <pre>filter</pre>.
*
* @param filter filter
* @return inverting filter
*/
public static SelectUserId not(SelectUserId filter) {
return new SelectUserId() {
@Override
protected boolean accept(String userId) {
return !strategy.accept(userId);
return !filter.accept(userId);
}
};
}
/**
* Filter that selects user-ids by the given <pre>email</pre> address.
* It returns user-ids which either contain the given <pre>email</pre> address as angle-bracketed string,
* or which equal the given <pre>email</pre> string exactly.
*
* @param email email
* @return filter
*/
public static SelectUserId byEmail(CharSequence email) {
return SelectUserId.or(
SelectUserId.exactMatch(email),