|
ROSE 0.11.145.192
|
Renders textual margin arrows.
This class is responsible for calculating the layout of textual arrows in a left or right margin of assembly output, and then later rendering those arrows.
The implementation is general in that it doesn't know what purpose the arrows serve–it only knows that an arrow has two endpoints called herein the "source" and "target". However, it assumes that an arrow spans lines of output and its main body is therefore rendered as a vertical lines, although its two endpoints might have horizontal components.
This API has a few high-level layout functions for situations that are common in the ROSE library, and these are written in terms of a more general layout function. At the more general level, the desired arrows are represented by a graph whose vertices represent the end points and whose edges represent the desired arrows connecting the endpoints. Arrows may share endpoints in this descriptive graph. Each endpoint has a unique ID number.
Definition at line 36 of file EdgeArrows.h.
#include <Rose/BinaryAnalysis/Unparser/EdgeArrows.h>
Classes | |
| struct | ArrowStyle |
| Arrow text. More... | |
Public Types | |
| enum | OutputPart { FIRST_LINE , LAST_LINE , MIDDLE_LINE , INTER_LINE } |
| Parts of the output. More... | |
| enum | ArrowStylePreset { UNICODE_1 , UNICODE_2 , ASCII_1 , ASCII_2 , ASCII_3 } |
| Arrow style presets. More... | |
| enum | ArrowSide { LEFT , RIGHT } |
| Specifies on which side of the output the arrows appear. More... | |
| using | EndpointId = size_t |
| Endpoint identification number. | |
| using | ArrowId = size_t |
| Arrow identification number. | |
| using | Graph = Sawyer::Container::Graph< EndpointId, ArrowId, EndpointId, ArrowId > |
| Graph relating endpoints. | |
Public Member Functions | |
| bool | columnIsRendered (size_t columnIdx) const |
| Predicate: Whether the specified arrow column is rendered. | |
| void | computeLayout (const Graph &, const std::vector< EndpointId > &order) |
| Analyze connectivity in order to assign arrow locations. | |
| void | computeCfgBlockLayout (const Partitioner2::PartitionerConstPtr &, const Partitioner2::FunctionPtr &) |
| Compute arrow layout for a control flow graph for a function. | |
| void | computeCfgEdgeLayout (const Partitioner2::PartitionerConstPtr &, const Partitioner2::FunctionPtr &) |
| Compute arrow layout for a control flow graph for a function. | |
| bool | exists (EndpointId) const |
| Tests whether endpoint ID is known. | |
| Sawyer::Optional< Arrow > | findArrow (ArrowId) const |
| Finds the arrow information for the specified edge. | |
| void | reset () |
| Reset the analysis. | |
| size_t | nArrowColumns () const |
| Number of arrow columns. | |
| size_t | nRenderColumns () const |
| Number of columns to render. | |
| void | arrowStyle (ArrowStylePreset, ArrowSide) |
| Set the arrow style to a preset value. | |
| std::string | renderBlank () const |
| Render a field of blank characters for all the columns. | |
| std::string | render (EndpointId, OutputPart) const |
| Render arrow columns for an endpoint. | |
| size_t | nSources (EndpointId) const |
| Number of arrows that emanate from the given endpoint. | |
| size_t | nTargets (EndpointId) const |
| Number of arrows that point to the given endpoint. | |
| void | debug (std::ostream &) const |
| Print implementation-defined debugging information. | |
| std::pair< size_t, size_t > | minMaxRenderColumns () const |
| Property: Minimum and maximum number of columns to render. | |
| void | minMaxRenderColumns (size_t minColumns, size_t maxColumns) |
| Property: Minimum and maximum number of columns to render. | |
| const ArrowStyle & | arrowStyle () const |
| Property: Information about how to render an arrow. | |
| void | arrowStyle (const ArrowStyle &t) |
| Property: Information about how to render an arrow. | |
Static Public Member Functions | |
| static EndpointId | edgeToSourceEndpoint (size_t edgeId) |
| Endpoint IDs related to edge IDs. | |
| static EndpointId | edgeToTargetEndpoint (size_t edgeId) |
| Endpoint IDs related to edge IDs. | |
| static size_t | edgeFromEndpoint (EndpointId) |
| Endpoint IDs related to edge IDs. | |
| static bool | isSourceEndpoint (EndpointId) |
| Endpoint IDs related to edge IDs. | |
| static bool | isTargetEndpoint (EndpointId) |
| Endpoint IDs related to edge IDs. | |
| static EndpointId | otherEndpoint (EndpointId) |
| Endpoint IDs related to edge IDs. | |
| static ArrowStyle | unicodeL1 () |
| Arrow rendering styles. | |
| static ArrowStyle | unicodeR1 () |
| Arrow rendering styles. | |
| static ArrowStyle | unicodeL2 () |
| Arrow rendering styles. | |
| static ArrowStyle | unicodeR2 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiL1 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiR1 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiL2 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiR2 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiL3 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiR3 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiL4 () |
| Arrow rendering styles. | |
| static ArrowStyle | asciiR4 () |
| Arrow rendering styles. | |
| using Rose::BinaryAnalysis::Unparser::EdgeArrows::EndpointId = size_t |
Endpoint identification number.
These serve a user-specified purpose to identify the things to/from which arrows point. For instance, they might be the identification numbers for basic blocks in a control flow graph, or they might be identification numbers for lines describing CFG edge sources and targets.
Definition at line 57 of file EdgeArrows.h.
| using Rose::BinaryAnalysis::Unparser::EdgeArrows::ArrowId = size_t |
Arrow identification number.
This is a user-specified arrow identification number. Most users will probably arrange for arrow IDs to be the same as the ID numbers for edges in a control flow graph.
Definition at line 63 of file EdgeArrows.h.
| using Rose::BinaryAnalysis::Unparser::EdgeArrows::Graph = Sawyer::Container::Graph<EndpointId, ArrowId, EndpointId, ArrowId> |
Graph relating endpoints.
The vertices of this graph represent the endpoints of the arrows. The arrows themselves are represented by the directed edges in this graph. An edge from endpoint A to endpoint B means that there should be an arrow that originates from endpoint A and points to endpoint B in the output.
Definition at line 70 of file EdgeArrows.h.
Parts of the output.
Arrows are rendered one line at a time, although it is simpler to think of the output in terms of the things to which the arrows point (e.g., the basic blocks in a control flow graph). Each pointee is assumed to have zero or more lines describing arrow targets (e.g., describing from whence CFG execution flow comes), followed by zero or more non-endpoint lines (e.g., the instructions themselves), followed by zero or more lines describing arrow sources (e.g., describing to where execution flow goes next). Pointees might be separated from one another in the output by zero or more other lines.
Definition at line 45 of file EdgeArrows.h.
Arrow style presets.
Definition at line 89 of file EdgeArrows.h.
Specifies on which side of the output the arrows appear.
| Enumerator | |
|---|---|
| LEFT | Arrows appear left of the main output and point to the right. |
| RIGHT | Arrows appear right of the main output and point to the left. |
Definition at line 98 of file EdgeArrows.h.
|
inline |
Definition at line 152 of file EdgeArrows.h.
| std::pair< size_t, size_t > Rose::BinaryAnalysis::Unparser::EdgeArrows::minMaxRenderColumns | ( | ) | const |
Property: Minimum and maximum number of columns to render.
The render columns will emit at least the specified minumum number of arrow columns, but not more than the maximum. If there are fewer columns than the minimum, then extra empty columns are rendered; if there are more than the maximum number of columns then some columns are not rendered.
The minimum must be less than or equal to the maximum.
| void Rose::BinaryAnalysis::Unparser::EdgeArrows::minMaxRenderColumns | ( | size_t | minColumns, |
| size_t | maxColumns | ||
| ) |
Property: Minimum and maximum number of columns to render.
The render columns will emit at least the specified minumum number of arrow columns, but not more than the maximum. If there are fewer columns than the minimum, then extra empty columns are rendered; if there are more than the maximum number of columns then some columns are not rendered.
The minimum must be less than or equal to the maximum.
| bool Rose::BinaryAnalysis::Unparser::EdgeArrows::columnIsRendered | ( | size_t | columnIdx | ) | const |
Predicate: Whether the specified arrow column is rendered.
Arrows belong to logical columns, and the renderer can be set to show a minimum and maximum number of columns. This predicate returns true if the specified logical column would be shown. Columns are printed in different orders depending on whether they appear left or right of the things to which they point, and this predicate takes that into account.
| void Rose::BinaryAnalysis::Unparser::EdgeArrows::computeLayout | ( | const Graph & | , |
| const std::vector< EndpointId > & | order | ||
| ) |
Analyze connectivity in order to assign arrow locations.
Analyzes the connectivity of the endpoints specified in the graph, and the optional endpoint order to calculate the locations of the margin arrows. The endpoints in the graph are assumed to be output in the order listed in the order argument. Any endpoints that are present in the graph but not in the order specification are sorted by EndpointId and then appended to the order.
This does not clear previous layout information, and so it can be used to append to previous output. To discard previous layout information first, call reset.
| void Rose::BinaryAnalysis::Unparser::EdgeArrows::computeCfgBlockLayout | ( | const Partitioner2::PartitionerConstPtr & | , |
| const Partitioner2::FunctionPtr & | |||
| ) |
Compute arrow layout for a control flow graph for a function.
This produces arrows for intra-function CFG edges such that the arrows' sources and targets are basic blocks. That is, in the output, arrows will point to the first instruction of a basic block and emanate from the last instruction. This method assumes that the unparser emits a function's basic blocks in order of their starting address.
See also, computeCfgEdgeLayout
| void Rose::BinaryAnalysis::Unparser::EdgeArrows::computeCfgEdgeLayout | ( | const Partitioner2::PartitionerConstPtr & | , |
| const Partitioner2::FunctionPtr & | |||
| ) |
Compute arrow layout for a control flow graph for a function.
This produces arrows for intra-function CFG edges such that the arrows' sources and targets are the "predecessor" and "successor" lines emitted by the unparser before and after each basic block. That is, each arrow points to its corresponding "predecessor" line, and emanates from its corresponding "successor" line. This method assumes that the unparser emits a function's basic blocks in order of their starting address, and emits the "predecessor" and "successor" lines in the order they appear in the partitioner control flow graph (from vertex.inEdges and vertex.outEdges, respectively). It also assumes that "predecessors" are listed before "successors".
See also, computeCfgBlockLayout
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
|
static |
Endpoint IDs related to edge IDs.
These functions generate endpoint IDs from edge IDs and vice versa. They're purely here for convenience–you can number your endpoints however you like.
The computeCfgEdgeLayout uses the numbering scheme implemented by these functions.
| bool Rose::BinaryAnalysis::Unparser::EdgeArrows::exists | ( | EndpointId | ) | const |
Tests whether endpoint ID is known.
Returns true if the specified endpoint is part of the edge arrow information, false if the ID is unknown.
| void Rose::BinaryAnalysis::Unparser::EdgeArrows::reset | ( | ) |
Reset the analysis.
This clears previous layout information but not rendering information. I.e., the arrows are all erased, but the arrow style and other properties are not affected.
Referenced by Rose::BinaryAnalysis::Unparser::ArrowMargin::reset().
| size_t Rose::BinaryAnalysis::Unparser::EdgeArrows::nArrowColumns | ( | ) | const |
Number of arrow columns.
This is the number of logical columns needed for the arrows. An arrow occupies a single logical column, but depending on the arrow style, the rendered arrow might occupy multiple physical columns of output. The return value is not limited by the minMaxRenderColumns property.
If you want the number of columns of characters (rather than arrows) you should multiply the return value of this function by arrowStyle.charactersPerColumn.
| size_t Rose::BinaryAnalysis::Unparser::EdgeArrows::nRenderColumns | ( | ) | const |
Number of columns to render.
This is the number of logical arrow columns actually rendered. The return value is a function of nArrowColumns and minMaxRenderColumns. Each logical column may refer to multiple physical columns depending on the arrow style.
|
inline |
Property: Information about how to render an arrow.
Definition at line 257 of file EdgeArrows.h.
|
inline |
Property: Information about how to render an arrow.
Definition at line 258 of file EdgeArrows.h.
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
|
static |
Arrow rendering styles.
These functions have names that follow a regular pattern. The first part of the name describes the character set used for the arrows. The letters "R" and "L" indicate whether the arrows are to the left or right of the vertices to which they refer (opposite the direction the arrows point). The number indicates the number of characters per column of arrows. The wider formats are easier to read but take up more output space.
To set the arrow style, use code like this:
| std::string Rose::BinaryAnalysis::Unparser::EdgeArrows::renderBlank | ( | ) | const |
Render a field of blank characters for all the columns.
Use this to keep tabular output aligned when you're only reserving space for the arrow columns and not actually printing any arrows.
| size_t Rose::BinaryAnalysis::Unparser::EdgeArrows::nSources | ( | EndpointId | ) | const |
Number of arrows that emanate from the given endpoint.
Normally you'd use the original graph to answer this question, but sometimes that graph is long gone. In those cases, you can use this slower function to find the number of arrows that originate from the specified endpoint.
| size_t Rose::BinaryAnalysis::Unparser::EdgeArrows::nTargets | ( | EndpointId | ) | const |
Number of arrows that point to the given endpoint.
Normally you'd use the original graph to answer this question, but sometimes that graph is long gone. In those cases, you can use this slower function to find the number of arrows that point to the specified endpoint.
1.9.8