vendor/github.com/hashicorp/hcl2/hcl/structure_at_pos.go

   1 package hcl
   2
   3 // -----------------------------------------------------------------------------
   4 // The methods in this file all have the general pattern of making a best-effort
   5 // to find one or more constructs that contain a given source position.
   6 //
   7 // These all operate by delegating to an optional method of the same name and
   8 // signature on the file's root body, allowing each syntax to potentially
   9 // provide its own implementations of these. For syntaxes that don't implement
  10 // them, the result is always nil.
  11 // -----------------------------------------------------------------------------
  12
  13 // BlocksAtPos attempts to find all of the blocks that contain the given
  14 // position, ordered so that the outermost block is first and the innermost
  15 // block is last. This is a best-effort method that may not be able to produce
  16 // a complete result for all positions or for all HCL syntaxes.
  17 //
  18 // If the returned slice is non-empty, the first element is guaranteed to
  19 // represent the same block as would be the result of OutermostBlockAtPos and
  20 // the last element the result of InnermostBlockAtPos. However, the
  21 // implementation may return two different objects describing the same block,
  22 // so comparison by pointer identity is not possible.
  23 //
  24 // The result is nil if no blocks at all contain the given position.
  25 func (f *File) BlocksAtPos(pos Pos) []*Block {
  26         // The root body of the file must implement this interface in order
  27         // to support BlocksAtPos.
  28         type Interface interface {
  29                 BlocksAtPos(pos Pos) []*Block
  30         }
  31
  32         impl, ok := f.Body.(Interface)
  33         if !ok {
  34                 return nil
  35         }
  36         return impl.BlocksAtPos(pos)
  37 }
  38
  39 // OutermostBlockAtPos attempts to find a top-level block in the receiving file
  40 // that contains the given position. This is a best-effort method that may not
  41 // be able to produce a result for all positions or for all HCL syntaxes.
  42 //
  43 // The result is nil if no single block could be selected for any reason.
  44 func (f *File) OutermostBlockAtPos(pos Pos) *Block {
  45         // The root body of the file must implement this interface in order
  46         // to support OutermostBlockAtPos.
  47         type Interface interface {
  48                 OutermostBlockAtPos(pos Pos) *Block
  49         }
  50
  51         impl, ok := f.Body.(Interface)
  52         if !ok {
  53                 return nil
  54         }
  55         return impl.OutermostBlockAtPos(pos)
  56 }
  57
  58 // InnermostBlockAtPos attempts to find the most deeply-nested block in the
  59 // receiving file that contains the given position. This is a best-effort
  60 // method that may not be able to produce a result for all positions or for
  61 // all HCL syntaxes.
  62 //
  63 // The result is nil if no single block could be selected for any reason.
  64 func (f *File) InnermostBlockAtPos(pos Pos) *Block {
  65         // The root body of the file must implement this interface in order
  66         // to support InnermostBlockAtPos.
  67         type Interface interface {
  68                 InnermostBlockAtPos(pos Pos) *Block
  69         }
  70
  71         impl, ok := f.Body.(Interface)
  72         if !ok {
  73                 return nil
  74         }
  75         return impl.InnermostBlockAtPos(pos)
  76 }
  77
  78 // OutermostExprAtPos attempts to find an expression in the receiving file
  79 // that contains the given position. This is a best-effort method that may not
  80 // be able to produce a result for all positions or for all HCL syntaxes.
  81 //
  82 // Since expressions are often nested inside one another, this method returns
  83 // the outermost "root" expression that is not contained by any other.
  84 //
  85 // The result is nil if no single expression could be selected for any reason.
  86 func (f *File) OutermostExprAtPos(pos Pos) Expression {
  87         // The root body of the file must implement this interface in order
  88         // to support OutermostExprAtPos.
  89         type Interface interface {
  90                 OutermostExprAtPos(pos Pos) Expression
  91         }
  92
  93         impl, ok := f.Body.(Interface)
  94         if !ok {
  95                 return nil
  96         }
  97         return impl.OutermostExprAtPos(pos)
  98 }
  99
 100 // AttributeAtPos attempts to find an attribute definition in the receiving
 101 // file that contains the given position. This is a best-effort method that may
 102 // not be able to produce a result for all positions or for all HCL syntaxes.
 103 //
 104 // The result is nil if no single attribute could be selected for any reason.
 105 func (f *File) AttributeAtPos(pos Pos) *Attribute {
 106         // The root body of the file must implement this interface in order
 107         // to support OutermostExprAtPos.
 108         type Interface interface {
 109                 AttributeAtPos(pos Pos) *Attribute
 110         }
 111
 112         impl, ok := f.Body.(Interface)
 113         if !ok {
 114                 return nil
 115         }
 116         return impl.AttributeAtPos(pos)
 117 }