Description

State associated with printing arrows in the margin.

Arrows are represented by directed edges in an "arrow graph", and the vertices of that graph represent the endpoints of the arrows. Each arrow must have a unique ID (size_t) as should each endpoint. Multiple arrows may have the same endpoint, but any particular arrow should not have the same endpoint as both its source and target (since drawing such an arrow is not always possible, e.g., with ASCII text). Arrow IDs for arrows that correspond to CFG edges are just the CFG edge IDs.

Each basic block is optionally prefixed by one line per incoming edge, and optionally suffixed by one line per outgoing edge, depending on the unparser settings. When edge lines are present, the arrows originate and/or terminate at these lines, otherwise they use the first or last instruction of the basic block.

Arrow endpoint IDs are one of two things, depending on whether the endpoint would be a line describing a CFG edge, or a line corresponding to a CFG vertex (a basic block). In both cases there are two possible endpoint locations that need to have unique IDs for a total of four types, but based on the settings we only ever use two of these types.

arrow source endpoint is the last line of a basic block; its ID is twice the CFG vertex ID plus one.
arrow source endpoint is the CFG edge source line; its ID is twice the CFG edge ID.
arrow target endpoint is the first line of a basic block; its ID is twice the CFG vertex ID.
arrow target endpoint is the CFG edge target line; its ID is twice the CFG edge ID plus one.

These endpoint IDs are obtained from the EdgeArrow::toSourceEndpoint and related functions.

Definition at line 69 of file Unparser/Base.h.

#include <Rose/BinaryAnalysis/Unparser/Base.h>

Classes
class	CfgEndpoint

Public Member Functions
	ArrowMargin (const ArrowMargin &)=delete

ArrowMargin &	operator= (const ArrowMargin &)=delete

	ArrowMargin (CfgEndpoint::Type srcEndpointType, CfgEndpoint::Type dstEndpointType)

void	arrowStyle (EdgeArrows::ArrowStylePreset, EdgeArrows::ArrowSide)
	Set arrow style.

void	reset ()
	Reset the margin arrow state.

void	maybeInsertArrow (EdgeArrows::EndpointId src, EdgeArrows::EndpointId tgt, size_t arrowId)
	Insert an arrow into the graph if it isn't already there.

void	maybeInsertEndpoint (EdgeArrows::EndpointId)
	Insert an arrow endpoint into the ordered list of endpoints.

bool	haveEndpointId (EdgeArrows::EndpointId) const
	Test whether we have an endpoint ID.

CfgEndpoint::End	whichEnd (EdgeArrows::EndpointId) const
	Test whether an endpoint is the source or target of an arrow.

void	computeLayout ()
	Compute where arrows go in the margins.

std::string	render ()
	Destructively render the arrows for a line of output.

void	debug (std::ostream &, const Partitioner2::PartitionerConstPtr &) const
	Show some debugging information.


CfgEndpoint	makeCfgEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Edge &)
	Get an arrow endpoint.

EdgeArrows::EndpointId	getEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Edge &)
	Get an arrow endpoint.


Sawyer::Optional< EdgeArrows::EndpointId >	findEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Edge &) const
	Test whether we have an endpoint ID for a particular line of output given some info about what's on that line.

Sawyer::Optional< EdgeArrows::EndpointId >	findEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Vertex &) const
	Test whether we have an endpoint ID for a particular line of output given some info about what's on that line.


void	atPossibleEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Edge &)
	While generating output, indicate what line we're at.

void	atPossibleEndpoint (CfgEndpoint::End, const Partitioner2::ControlFlowGraph::Vertex &)
	While generating output, indicate what line we're at.

Member Function Documentation

◆ reset()

void Rose::BinaryAnalysis::Unparser::ArrowMargin::reset ( )

Reset the margin arrow state.

This should be called near the end of emitting a function, probably just before emitting the function epilogue.

◆ makeCfgEndpoint()

CfgEndpoint Rose::BinaryAnalysis::Unparser::ArrowMargin::makeCfgEndpoint	(	CfgEndpoint::End	,
		const Partitioner2::ControlFlowGraph::Edge &
	)

Get an arrow endpoint.

Given a CFG edge, return an arrow endpoint ID. Arrow endpoint IDs are unique.

◆ getEndpoint()

EdgeArrows::EndpointId Rose::BinaryAnalysis::Unparser::ArrowMargin::getEndpoint	(	CfgEndpoint::End	,
		const Partitioner2::ControlFlowGraph::Edge &
	)

Get an arrow endpoint.

Given a CFG edge, return an arrow endpoint ID. Arrow endpoint IDs are unique.

◆ maybeInsertArrow()

void Rose::BinaryAnalysis::Unparser::ArrowMargin::maybeInsertArrow	(	EdgeArrows::EndpointId	src,
		EdgeArrows::EndpointId	tgt,
		size_t	arrowId
	)

Insert an arrow into the graph if it isn't already there.

The arrow ID should be the same as the CFG edge ID that it represents.

◆ maybeInsertEndpoint()

void Rose::BinaryAnalysis::Unparser::ArrowMargin::maybeInsertEndpoint ( EdgeArrows::EndpointId )

Insert an arrow endpoint into the ordered list of endpoints.

Endpoints should be inserted in the same order they're emitted to the output. It is not necessary to insert endpoints before inserting the arrows to which they're attached.

◆ computeLayout()

void Rose::BinaryAnalysis::Unparser::ArrowMargin::computeLayout ( )

Compute where arrows go in the margins.

Before calling this, you must have inserted some arrows and endpoints.

◆ atPossibleEndpoint() [1/2]

void Rose::BinaryAnalysis::Unparser::ArrowMargin::atPossibleEndpoint	(	CfgEndpoint::End	,
		const Partitioner2::ControlFlowGraph::Edge &
	)

While generating output, indicate what line we're at.

The line could be one that describes an endpoint of a CFG edge, or it could be an instruction at the beginning or end of a CFG vertex (basic block).

◆ atPossibleEndpoint() [2/2]

void Rose::BinaryAnalysis::Unparser::ArrowMargin::atPossibleEndpoint	(	CfgEndpoint::End	,
		const Partitioner2::ControlFlowGraph::Vertex &
	)

While generating output, indicate what line we're at.

The line could be one that describes an endpoint of a CFG edge, or it could be an instruction at the beginning or end of a CFG vertex (basic block).

◆ render()

std::string Rose::BinaryAnalysis::Unparser::ArrowMargin::render ( )

Destructively render the arrows for a line of output.

If we're at an arrow endpoint in the output (see atPossibleEndpoint) then calling this function advances beyond that line of output.

The documentation for this class was generated from the following file:

Unparser/Base.h