overview of codebase - dobkeratops/rustfind GitHub Wiki

home

Data Structures

  • RFindCtx - context object holding the compiler datastructures eg cratemap, session etc
  • FNodeInfoMap - copy of the AST using universal nodes, can get node from nodeid
  • AstNode - universal ast node wrapper, an enum holding any rust ast node.
  • ZTextFilePos - source locations with zero-relative line/column indices prefix 'Z' to indicate ZeroRelative
  • ZIndexFilePos - same but indexed rather than using filenames
  • ZTextFilePosLen -
  • ZIndexPosLen - describes a span, being a code location+ length
    • there are many helper functions for converting between these representations of a code location
    • see codemaput.rs and BytePos
    • TODO -refactor to 1-based to match rust internals?- i regret the zero-based index choice.
    • TODO - use doc comments instead of this wiki ..

Source Files/Modules

rustfind.rs

crate root, contains fn main(); imports all the modules and handles commandline input;

find_ast_node.rs

TODO Should be split into several modules

  • Code to build the main datastructure FNodeInfoMap, - tree of "AstNode" and map from nodeid->AstNode -fn build_node_info_map() -- traverses the rust AST with a visitor (fcns_** functions in Visitor{}) to build FNodeInfoMap which everything else is based on.
  • defines universal ast nodes "AstNode", an enum holding all the possible AST nodes in the rust AST, necessery as a return for asking "what node is at this source location"
  • accessors for these AstNodeAccessors
  • some utilities for finding nodes from id's in the internal representation

rust2html.rs

takes a the ast copy and CrossCrateMaps and emits highlighted, linked HTML

CrossCrateMap.rs

deals with the 'crosscratemap' .rfx files - this is extra metadata for the crate, basically a dump of the AST nodes with span information, this is necasery to allow jump-to-definition between different crates. Its possible future additions to Rust internals could obselete this reader/writer. see type "CrossCrateMap"

the idea is: when you generate linked docs for a single crate, it emits a .rfx. This is read in when generating for other crates to resolve inter-crate definitions

TODO: its possible enhancements to rusts' crate metadata could obselete this, would they be open to that or is it un-necasery bloat. This is more like debug-info ?

rfserver.rs

this is intended to be a server mode for IDE integration, similar to how clang-autocomplete works fn run_server () could grow into that..

at the moment it just responds to entering a filename:line:column and responds with the definition filename:line:column

jumptodefmap.rs

processes the ast copy to build various extra maps getting from id's to nodes. i forget the details here. debug dump in json. Uses "def_ids" in rust which are a combination of crate-index and node-index within the crate, a sort of global ID for the nodes... but the crate indices are local. in the '.rfx' file it lists node ID's with a sort of global adress being the crate name & node index within the crate.

rfindctx.rs

just defines RFindCtx holding ast::Crate, middle:;ty::ctxt, driver::session::Session, driver::drviver::CrateAnalysis... the main structures from the rust compiler..

test_input.rs test_input0.rs test_input2.rs

not actually compiled, used to test this

codemaput.rs

helper functions for finding source locations, relating lines / crates / filenames / BytePos, ZIndex etc

textformatting.rs

for debug .. attempt to do nice brace nesting from old print fmt( %? stuff.

ioutil.rs

file writer helpers TODO - refactor to use idiomatic rust fileio

htmlwriter.rs

utilities for writing html eg document with nested tags TODO check if libextra gets something like this

makefile

  • make rustfind - builds the executable
  • make html - compiles and builds the html for this project.
  • make test0 make test1
    • runs itself on the test sources test_input0.rs etc.
    • these are useful for testing individual features in isolation..