Package com.headius.invokebinder
Class Signature
- java.lang.Object
-
- com.headius.invokebinder.Signature
-
public class Signature extends java.lang.Object
Signature represents a series of method arguments plus their symbolic names. In order to make it easier to permute arguments, track their flow, and debug cases where reordering or permuting fails to work properly, the Signature class also tracks symbolic names for all arguments. This allows permuting by name or by name pattern, avoiding the error-prone juggling of int[] for the standard MethodHandles.permuteArguments call. A Signature is created starting using #thatReturns method, and expanded using #withArgument for each named argument in sequence. Order is preserved. A Signature can be mutated into another by manipuating the argument list as with java.lang.invoke.MethodType, but using argument names and name patterns instead of integer offsets. Two signatures can be used to produce a permute array suitable for use in java.lang.invoke.MethodHandles#permuteArguments using the #to methods. The #to method can also accept a list of argument names, as a shortcut.- Author:
- headius
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Signature
appendArg(java.lang.String name, java.lang.Class<?> type)
Append an argument (name + type) to the signature.Signature
appendArgs(java.lang.String[] names, java.lang.Class<?>... types)
Append an argument (name + type) to the signature.int
argCount()
The current argument count.java.lang.String
argName(int index)
Retrieve the name of the argument at the given index.Signature
argName(int index, java.lang.String name)
Set the argument name at the given index.java.lang.String[]
argNames()
The current argument names for this signature.int
argOffset(java.lang.String name)
Retrieve the offset of the given argument name in this signature's arguments.int
argOffsets(java.lang.String pattern)
Retrieve the offset of the given argument name in this signature's arguments.java.lang.Class<?>
argType(int index)
Get the argument type at the given index.Signature
argType(int index, java.lang.Class<?> type)
Set the argument type at the given index.Signature
asFold(java.lang.Class<?> retval)
Produce a new signature based on this one with a different return type.Signature
changeReturn(java.lang.Class<?> retval)
Create a new signature based on this one with a different return type.Signature
collect(java.lang.String newName, java.lang.String oldPattern)
Collect sequential arguments matching pattern into an array.Signature
dropArg(int index)
Drops the argument at the given index.Signature
dropArg(java.lang.String name)
Drops the first argument with the given name.Signature
dropFirst()
Drop the first argument from this signature.Signature
dropFirst(int n)
Drop the specified number of first arguments from this signature.Signature
dropLast()
Drop the last argument from this signature.Signature
dropLast(int n)
Drop the specified number of last arguments from this signature.boolean
equals(java.lang.Object o)
Signature
exclude(java.lang.String... excludeArgs)
Create a new signature containing the same return value as this one, but omitting the specified arguments.java.lang.String
firstArgName()
Get the first argument name.java.lang.Class<?>
firstArgType()
Get the first argument type.static Signature
from(java.lang.Class<?> retval, java.lang.Class<?>[] argTypes, java.lang.String... argNames)
Create a new signature based on the given return value, argument types, and argument namesint
hashCode()
Signature
insertArg(int index, java.lang.String name, java.lang.Class<?> type)
Insert an argument (name + type) into the signature.Signature
insertArg(java.lang.String beforeName, java.lang.String name, java.lang.Class<?> type)
Insert an argument (name + type) into the signature before the argument with the given name.Signature
insertArgs(int index, java.lang.String[] names, java.lang.Class<?>... types)
Insert arguments (names + types) into the signature.Signature
insertArgs(java.lang.String beforeName, java.lang.String[] names, java.lang.Class<?>... types)
Insert arguments (names + types) into the signature before the argument with the given name.java.lang.String
lastArgName()
Get the last argument name.java.lang.Class<?>
lastArgType()
Get the last argument type.Signature
permute(java.lang.String... permuteArgs)
Create a new signature containing the same return value as this one, but only the specified arguments.SmartHandle
permuteWith(SmartHandle target)
Produce a new SmartHandle by permuting this Signature's arguments to the Signature of a target SmartHandle.java.lang.invoke.MethodHandle
permuteWith(java.lang.invoke.MethodHandle target, java.lang.String... permuteArgs)
Produce a method handle permuting the arguments in this signature using the given permute arguments and targeting the given java.lang.invoke.MethodHandle.Signature
prependArg(java.lang.String name, java.lang.Class<?> type)
Prepend an argument (name + type) to the signature.Signature
prependArgs(java.lang.String[] names, java.lang.Class<?>... types)
Prepend arguments (names + types) to the signature.Signature
replaceArg(java.lang.String oldName, java.lang.String newName, java.lang.Class<?> newType)
Replace the named argument with a new name and type.static Signature
returning(java.lang.Class<?> retval)
Create a new signature returning the given type.Signature
spread(java.lang.String... names)
Spread the trailing [] argument into its component type assigning given names.Signature
spread(java.lang.String[] names, java.lang.Class<?>... types)
Spread the trailing [] argument into its component type assigning given names.Signature
spread(java.lang.String baseName, int count)
Spread the trailing [] argument into its component type assigning given names.int[]
to(Signature other)
Generate an array of argument offsets based on permuting this signature to the given signature.int[]
to(java.lang.String... otherArgPatterns)
Generate an array of argument offsets based on permuting this signature to the given signature.java.lang.String
toString()
Produce a human-readable representation of this signature.java.lang.invoke.MethodType
type()
The current java.lang.invoke.MethodType for this Signature.
-
-
-
Method Detail
-
toString
public java.lang.String toString()
Produce a human-readable representation of this signature. This representation uses Class#getSimpleName to improve readability.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a human-readable representation of the signature
-
returning
public static Signature returning(java.lang.Class<?> retval)
Create a new signature returning the given type.- Parameters:
retval
- the return type for the new signature- Returns:
- the new signature
-
from
public static Signature from(java.lang.Class<?> retval, java.lang.Class<?>[] argTypes, java.lang.String... argNames)
Create a new signature based on the given return value, argument types, and argument names- Parameters:
retval
- the type of the return valueargTypes
- the types of the argumentsargNames
- the names of the arguments- Returns:
- a new Signature
-
changeReturn
public Signature changeReturn(java.lang.Class<?> retval)
Create a new signature based on this one with a different return type.- Parameters:
retval
- the class for the new signature's return type- Returns:
- the new signature with modified return value
-
asFold
public Signature asFold(java.lang.Class<?> retval)
Produce a new signature based on this one with a different return type.- Parameters:
retval
- the new return type for the new signature- Returns:
- a new signature with the added argument
-
appendArg
public Signature appendArg(java.lang.String name, java.lang.Class<?> type)
Append an argument (name + type) to the signature.- Parameters:
name
- the name of the argumenttype
- the type of the argument- Returns:
- a new signature with the added arguments
-
appendArgs
public Signature appendArgs(java.lang.String[] names, java.lang.Class<?>... types)
Append an argument (name + type) to the signature.- Parameters:
names
- the names of the argumentstypes
- the types of the argument- Returns:
- a new signature with the added arguments
-
prependArg
public Signature prependArg(java.lang.String name, java.lang.Class<?> type)
Prepend an argument (name + type) to the signature.- Parameters:
name
- the name of the argumenttype
- the type of the argument- Returns:
- a new signature with the added arguments
-
prependArgs
public Signature prependArgs(java.lang.String[] names, java.lang.Class<?>... types)
Prepend arguments (names + types) to the signature.- Parameters:
names
- the names of the argumentstypes
- the types of the arguments- Returns:
- a new signature with the added arguments
-
insertArg
public Signature insertArg(int index, java.lang.String name, java.lang.Class<?> type)
Insert an argument (name + type) into the signature.- Parameters:
index
- the index at which to insertname
- the name of the new argumenttype
- the type of the new argument- Returns:
- a new signature with the added arguments
-
insertArg
public Signature insertArg(java.lang.String beforeName, java.lang.String name, java.lang.Class<?> type)
Insert an argument (name + type) into the signature before the argument with the given name.- Parameters:
beforeName
- the name of the argument before which to insertname
- the name of the new argumenttype
- the type of the new argument- Returns:
- a new signature with the added arguments
-
insertArgs
public Signature insertArgs(int index, java.lang.String[] names, java.lang.Class<?>... types)
Insert arguments (names + types) into the signature.- Parameters:
index
- the index at which to insertnames
- the names of the new argumentstypes
- the types of the new arguments- Returns:
- a new signature with the added arguments
-
insertArgs
public Signature insertArgs(java.lang.String beforeName, java.lang.String[] names, java.lang.Class<?>... types)
Insert arguments (names + types) into the signature before the argument with the given name.- Parameters:
beforeName
- the name of the argument before which to insertnames
- the names of the new argumentstypes
- the types of the new arguments- Returns:
- a new Signature with the added arguments
-
dropArg
public Signature dropArg(java.lang.String name)
Drops the first argument with the given name.- Parameters:
name
- the name of the argument to drop- Returns:
- a new signature
-
dropArg
public Signature dropArg(int index)
Drops the argument at the given index.- Parameters:
index
- the index of the argument to drop- Returns:
- a new signature
-
dropLast
public Signature dropLast()
Drop the last argument from this signature.- Returns:
- a new signature
-
dropLast
public Signature dropLast(int n)
Drop the specified number of last arguments from this signature.- Parameters:
n
- number of arguments to drop- Returns:
- a new signature
-
dropFirst
public Signature dropFirst()
Drop the first argument from this signature.- Returns:
- a new signature
-
dropFirst
public Signature dropFirst(int n)
Drop the specified number of first arguments from this signature.- Parameters:
n
- number of arguments to drop- Returns:
- a new signature
-
replaceArg
public Signature replaceArg(java.lang.String oldName, java.lang.String newName, java.lang.Class<?> newType)
Replace the named argument with a new name and type.- Parameters:
oldName
- the old name of the argumentnewName
- the new name of the argument; can be the same as oldnewType
- the new type of the argument; can be the same as old- Returns:
- a new signature with the modified argument
-
spread
public Signature spread(java.lang.String[] names, java.lang.Class<?>... types)
Spread the trailing [] argument into its component type assigning given names.- Parameters:
names
- names to use for the decomposed argumentstypes
- types to use for the decomposed arguments- Returns:
- a new signature with decomposed arguments in place of the trailing array
-
spread
public Signature spread(java.lang.String... names)
Spread the trailing [] argument into its component type assigning given names.- Parameters:
names
- names to use for the decomposed arguments- Returns:
- a new signature with decomposed arguments in place of the trailing array
-
spread
public Signature spread(java.lang.String baseName, int count)
Spread the trailing [] argument into its component type assigning given names.- Parameters:
baseName
- base name of the spread argumentscount
- number of arguments into which the last argument will decompose- Returns:
- a new signature with decomposed arguments in place of the trailing array
-
collect
public Signature collect(java.lang.String newName, java.lang.String oldPattern)
Collect sequential arguments matching pattern into an array. They must have the same type.- Parameters:
newName
- the name of the new array argumentoldPattern
- the pattern of arguments to collect- Returns:
- a new signature with an array argument where the collected arguments were
-
type
public java.lang.invoke.MethodType type()
The current java.lang.invoke.MethodType for this Signature.- Returns:
- the current method type
-
argCount
public int argCount()
The current argument count.- Returns:
- argument count of this signature
-
argNames
public java.lang.String[] argNames()
The current argument names for this signature.- Returns:
- the current argument names
-
argName
public java.lang.String argName(int index)
Retrieve the name of the argument at the given index.- Parameters:
index
- the index from which to get the argument name- Returns:
- the argument name
-
argOffset
public int argOffset(java.lang.String name)
Retrieve the offset of the given argument name in this signature's arguments. If the argument name is not in the argument list, returns -1.- Parameters:
name
- the argument name to search for- Returns:
- the offset at which the argument name was found or -1
-
argOffsets
public int argOffsets(java.lang.String pattern)
Retrieve the offset of the given argument name in this signature's arguments. If the argument name is not in the argument list, returns -1.- Parameters:
pattern
- the argument name to search for- Returns:
- the offset at which the argument name was found or -1
-
firstArgName
public java.lang.String firstArgName()
Get the first argument name.- Returns:
- the first argument name
-
lastArgName
public java.lang.String lastArgName()
Get the last argument name.- Returns:
- the last argument name
-
argName
public Signature argName(int index, java.lang.String name)
Set the argument name at the given index.- Parameters:
index
- the index at which to set the argument namename
- the name to set- Returns:
- a new signature with the given name at the given index
-
argType
public java.lang.Class<?> argType(int index)
Get the argument type at the given index.- Parameters:
index
- the index from which to get the argument type- Returns:
- the argument type
-
firstArgType
public java.lang.Class<?> firstArgType()
Get the first argument type.- Returns:
- the first argument type
-
lastArgType
public java.lang.Class<?> lastArgType()
Get the last argument type.- Returns:
- the last argument type
-
argType
public Signature argType(int index, java.lang.Class<?> type)
Set the argument type at the given index.- Parameters:
index
- the index at which to set the argument typetype
- the type to set- Returns:
- a new signature with the given type at the given index
-
permute
public Signature permute(java.lang.String... permuteArgs)
Create a new signature containing the same return value as this one, but only the specified arguments.- Parameters:
permuteArgs
- the names of the arguments to preserve- Returns:
- the new signature
-
exclude
public Signature exclude(java.lang.String... excludeArgs)
Create a new signature containing the same return value as this one, but omitting the specified arguments. Blacklisting to #permute's whitelisting.- Parameters:
excludeArgs
- the names of the arguments to exclude- Returns:
- the new signature
-
permuteWith
public java.lang.invoke.MethodHandle permuteWith(java.lang.invoke.MethodHandle target, java.lang.String... permuteArgs)
Produce a method handle permuting the arguments in this signature using the given permute arguments and targeting the given java.lang.invoke.MethodHandle. Example:Signature sig = Signature.returning(String.class).appendArg("a", int.class).appendArg("b", int.class); MethodHandle handle = handleThatTakesOneInt(); MethodHandle newHandle = sig.permuteTo(handle, "b");
- Parameters:
target
- the method handle to targetpermuteArgs
- the arguments to permute- Returns:
- a new handle that permutes appropriate positions based on the given permute args
-
permuteWith
public SmartHandle permuteWith(SmartHandle target)
Produce a new SmartHandle by permuting this Signature's arguments to the Signature of a target SmartHandle. The new SmartHandle's signature will match this one, permuting those arguments and invoking the target handle.- Parameters:
target
- the SmartHandle to use as a permutation target- Returns:
- a new SmartHandle that permutes this Signature's args into a call to the target SmartHandle.
- See Also:
permuteWith(java.lang.invoke.MethodHandle, java.lang.String[])
-
to
public int[] to(Signature other)
Generate an array of argument offsets based on permuting this signature to the given signature.- Parameters:
other
- the signature to target- Returns:
- an array of argument offsets that will permute to the given signature
-
to
public int[] to(java.lang.String... otherArgPatterns)
Generate an array of argument offsets based on permuting this signature to the given signature. Repeats are permitted, and the patterns will be matched against actual argument names using regex matching.- Parameters:
otherArgPatterns
- the argument name patterns to permute- Returns:
- an array of argument offsets that will permute to the matching argument names
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
-