API

Infiltration and exfiltration

Add @infiltrate to any function to start the infil> REPL mode when that line runs.

It's recommended to put Infiltrator.jl into your global environment and not into package environments for two reasons:

  • Infiltrator.jl is intended as a development tool only and as such should not be shipped
  • Any @infiltrate invocations in your package code will fail at compile-time, which prevents you from accidentally committing infiltrated code

This means that you'll need to use Revise.jl, inline evaluation in VS Code, or just plain old @eval to apply @infiltrate statements in your package code.

Infiltrator.@infiltrate — Macro
@infiltrate
@infiltrate condition::Bool

@infiltrate sets an infiltration point (or breakpoint).

When the infiltration point is hit, it will drop you into an interactive REPL session that lets you inspect local variables and the call stack as well as execute arbitrary statements in the context of the current functions module.

This macro also accepts an optional argument cond that must evaluate to a boolean, and then this macro will serve as a "conditional breakpoint", which starts inspections only when its condition is true. For example:

@infiltrate false # does not infiltrate
source
Infiltrator.@infiltry — Macro
@infiltry expr

Wraps expression in a try block, infiltrate if an exception is raised. Equivalent to:

try
    expr
catch
    @infiltrate
    rethrow()
end

If expr is of the form x = f(...), we take x out of the scope

x = try
    f(...)
catch
    @infiltrate
    rethrow()
end
source
Infiltrator.infiltrate — Function
infiltrate(mod, locals, file, line)

Function form of @infiltrate. Use this to conditionally infiltrate package code without using e.g. Revise (because this version is valid during precompilation).

This would typically be used as

if isdefined(Main, :Infiltrator)
  Main.infiltrate(@__MODULE__, Base.@locals, @__FILE__, @__LINE__)
end
source

The safehouse

This is where all exfiltrated variables end up. You can either exfiltrate a variable explicitly with @exfiltrate or implicitly by assignment in the infil> REPL mode.

Infiltrator.@withstore — Macro
@withstore ex

Evaluates the expression ex in the context of the global store.

Mainly intended for interactive use, as changes to the store's state will not propagate into the returned expression.

source

Utility

Infiltrator.end_session! — Function
end_session!(s = safehouse)

End this infiltration session (reverts the effect of @exit in the debug> REPL).

Only needs to be manually called on Julia versions prior to 1.5.

source