clang API Documentation

Rewriter.h
Go to the documentation of this file.
00001 //===--- Rewriter.h - Code rewriting interface ------------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 //  This file defines the Rewriter class, which is used for code
00011 //  transformations.
00012 //
00013 //===----------------------------------------------------------------------===//
00014 
00015 #ifndef LLVM_CLANG_REWRITE_CORE_REWRITER_H
00016 #define LLVM_CLANG_REWRITE_CORE_REWRITER_H
00017 
00018 #include "clang/Basic/SourceLocation.h"
00019 #include "clang/Rewrite/Core/DeltaTree.h"
00020 #include "clang/Rewrite/Core/RewriteRope.h"
00021 #include "llvm/ADT/StringRef.h"
00022 #include <cstring>
00023 #include <map>
00024 #include <string>
00025 
00026 namespace clang {
00027   class LangOptions;
00028   class Rewriter;
00029   class SourceManager;
00030 
00031 /// RewriteBuffer - As code is rewritten, SourceBuffer's from the original
00032 /// input with modifications get a new RewriteBuffer associated with them.  The
00033 /// RewriteBuffer captures the modified text itself as well as information used
00034 /// to map between SourceLocation's in the original input and offsets in the
00035 /// RewriteBuffer.  For example, if text is inserted into the buffer, any
00036 /// locations after the insertion point have to be mapped.
00037 class RewriteBuffer {
00038   friend class Rewriter;
00039   /// Deltas - Keep track of all the deltas in the source code due to insertions
00040   /// and deletions.
00041   DeltaTree Deltas;
00042   RewriteRope Buffer;
00043 public:
00044   typedef RewriteRope::const_iterator iterator;
00045   iterator begin() const { return Buffer.begin(); }
00046   iterator end() const { return Buffer.end(); }
00047   unsigned size() const { return Buffer.size(); }
00048 
00049   /// \brief Write to \p Stream the result of applying all changes to the
00050   /// original buffer.
00051   /// Note that it isn't safe to use this function to overwrite memory mapped
00052   /// files in-place (PR17960). Consider using a higher-level utility such as
00053   /// Rewriter::overwriteChangedFiles() instead.
00054   ///
00055   /// The original buffer is not actually changed.
00056   raw_ostream &write(raw_ostream &Stream) const;
00057 
00058   /// RemoveText - Remove the specified text.
00059   void RemoveText(unsigned OrigOffset, unsigned Size,
00060                   bool removeLineIfEmpty = false);
00061 
00062   /// InsertText - Insert some text at the specified point, where the offset in
00063   /// the buffer is specified relative to the original SourceBuffer.  The
00064   /// text is inserted after the specified location.
00065   ///
00066   void InsertText(unsigned OrigOffset, StringRef Str,
00067                   bool InsertAfter = true);
00068 
00069 
00070   /// InsertTextBefore - Insert some text before the specified point, where the
00071   /// offset in the buffer is specified relative to the original
00072   /// SourceBuffer. The text is inserted before the specified location.  This is
00073   /// method is the same as InsertText with "InsertAfter == false".
00074   void InsertTextBefore(unsigned OrigOffset, StringRef Str) {
00075     InsertText(OrigOffset, Str, false);
00076   }
00077 
00078   /// InsertTextAfter - Insert some text at the specified point, where the
00079   /// offset in the buffer is specified relative to the original SourceBuffer.
00080   /// The text is inserted after the specified location.
00081   void InsertTextAfter(unsigned OrigOffset, StringRef Str) {
00082     InsertText(OrigOffset, Str);
00083   }
00084 
00085   /// ReplaceText - This method replaces a range of characters in the input
00086   /// buffer with a new string.  This is effectively a combined "remove/insert"
00087   /// operation.
00088   void ReplaceText(unsigned OrigOffset, unsigned OrigLength,
00089                    StringRef NewStr);
00090 
00091 private:  // Methods only usable by Rewriter.
00092 
00093   /// Initialize - Start this rewrite buffer out with a copy of the unmodified
00094   /// input buffer.
00095   void Initialize(const char *BufStart, const char *BufEnd) {
00096     Buffer.assign(BufStart, BufEnd);
00097   }
00098 
00099   /// getMappedOffset - Given an offset into the original SourceBuffer that this
00100   /// RewriteBuffer is based on, map it into the offset space of the
00101   /// RewriteBuffer.  If AfterInserts is true and if the OrigOffset indicates a
00102   /// position where text is inserted, the location returned will be after any
00103   /// inserted text at the position.
00104   unsigned getMappedOffset(unsigned OrigOffset,
00105                            bool AfterInserts = false) const{
00106     return Deltas.getDeltaAt(2*OrigOffset+AfterInserts)+OrigOffset;
00107   }
00108 
00109   /// AddInsertDelta - When an insertion is made at a position, this
00110   /// method is used to record that information.
00111   void AddInsertDelta(unsigned OrigOffset, int Change) {
00112     return Deltas.AddDelta(2*OrigOffset, Change);
00113   }
00114 
00115   /// AddReplaceDelta - When a replacement/deletion is made at a position, this
00116   /// method is used to record that information.
00117   void AddReplaceDelta(unsigned OrigOffset, int Change) {
00118     return Deltas.AddDelta(2*OrigOffset+1, Change);
00119   }
00120 };
00121 
00122 
00123 /// Rewriter - This is the main interface to the rewrite buffers.  Its primary
00124 /// job is to dispatch high-level requests to the low-level RewriteBuffers that
00125 /// are involved.
00126 class Rewriter {
00127   SourceManager *SourceMgr;
00128   const LangOptions *LangOpts;
00129   std::map<FileID, RewriteBuffer> RewriteBuffers;
00130 public:
00131   struct RewriteOptions {
00132     /// \brief Given a source range, true to include previous inserts at the
00133     /// beginning of the range as part of the range itself (true by default).
00134     bool IncludeInsertsAtBeginOfRange;
00135     /// \brief Given a source range, true to include previous inserts at the
00136     /// end of the range as part of the range itself (true by default).
00137     bool IncludeInsertsAtEndOfRange;
00138     /// \brief If true and removing some text leaves a blank line
00139     /// also remove the empty line (false by default).
00140     bool RemoveLineIfEmpty;
00141 
00142     RewriteOptions()
00143       : IncludeInsertsAtBeginOfRange(true),
00144         IncludeInsertsAtEndOfRange(true),
00145         RemoveLineIfEmpty(false) { }
00146   };
00147 
00148   typedef std::map<FileID, RewriteBuffer>::iterator buffer_iterator;
00149   typedef std::map<FileID, RewriteBuffer>::const_iterator const_buffer_iterator;
00150 
00151   explicit Rewriter(SourceManager &SM, const LangOptions &LO)
00152     : SourceMgr(&SM), LangOpts(&LO) {}
00153   explicit Rewriter() : SourceMgr(nullptr), LangOpts(nullptr) {}
00154 
00155   void setSourceMgr(SourceManager &SM, const LangOptions &LO) {
00156     SourceMgr = &SM;
00157     LangOpts = &LO;
00158   }
00159   SourceManager &getSourceMgr() const { return *SourceMgr; }
00160   const LangOptions &getLangOpts() const { return *LangOpts; }
00161 
00162   /// isRewritable - Return true if this location is a raw file location, which
00163   /// is rewritable.  Locations from macros, etc are not rewritable.
00164   static bool isRewritable(SourceLocation Loc) {
00165     return Loc.isFileID();
00166   }
00167 
00168   /// getRangeSize - Return the size in bytes of the specified range if they
00169   /// are in the same file.  If not, this returns -1.
00170   int getRangeSize(SourceRange Range,
00171                    RewriteOptions opts = RewriteOptions()) const;
00172   int getRangeSize(const CharSourceRange &Range,
00173                    RewriteOptions opts = RewriteOptions()) const;
00174 
00175   /// getRewrittenText - Return the rewritten form of the text in the specified
00176   /// range.  If the start or end of the range was unrewritable or if they are
00177   /// in different buffers, this returns an empty string.
00178   ///
00179   /// Note that this method is not particularly efficient.
00180   ///
00181   std::string getRewrittenText(SourceRange Range) const;
00182 
00183   /// InsertText - Insert the specified string at the specified location in the
00184   /// original buffer.  This method returns true (and does nothing) if the input
00185   /// location was not rewritable, false otherwise.
00186   ///
00187   /// \param indentNewLines if true new lines in the string are indented
00188   /// using the indentation of the source line in position \p Loc.
00189   bool InsertText(SourceLocation Loc, StringRef Str,
00190                   bool InsertAfter = true, bool indentNewLines = false);
00191 
00192   /// InsertTextAfter - Insert the specified string at the specified location in
00193   ///  the original buffer.  This method returns true (and does nothing) if
00194   ///  the input location was not rewritable, false otherwise.  Text is
00195   ///  inserted after any other text that has been previously inserted
00196   ///  at the some point (the default behavior for InsertText).
00197   bool InsertTextAfter(SourceLocation Loc, StringRef Str) {
00198     return InsertText(Loc, Str);
00199   }
00200 
00201   /// \brief Insert the specified string after the token in the
00202   /// specified location.
00203   bool InsertTextAfterToken(SourceLocation Loc, StringRef Str);
00204 
00205   /// InsertText - Insert the specified string at the specified location in the
00206   /// original buffer.  This method returns true (and does nothing) if the input
00207   /// location was not rewritable, false otherwise.  Text is
00208   /// inserted before any other text that has been previously inserted
00209   /// at the some point.
00210   bool InsertTextBefore(SourceLocation Loc, StringRef Str) {
00211     return InsertText(Loc, Str, false);
00212   }
00213 
00214   /// RemoveText - Remove the specified text region.
00215   bool RemoveText(SourceLocation Start, unsigned Length,
00216                   RewriteOptions opts = RewriteOptions());
00217 
00218   /// \brief Remove the specified text region.
00219   bool RemoveText(CharSourceRange range,
00220                   RewriteOptions opts = RewriteOptions()) {
00221     return RemoveText(range.getBegin(), getRangeSize(range, opts), opts);
00222   }
00223 
00224   /// \brief Remove the specified text region.
00225   bool RemoveText(SourceRange range, RewriteOptions opts = RewriteOptions()) {
00226     return RemoveText(range.getBegin(), getRangeSize(range, opts), opts);
00227   }
00228 
00229   /// ReplaceText - This method replaces a range of characters in the input
00230   /// buffer with a new string.  This is effectively a combined "remove/insert"
00231   /// operation.
00232   bool ReplaceText(SourceLocation Start, unsigned OrigLength,
00233                    StringRef NewStr);
00234 
00235   /// ReplaceText - This method replaces a range of characters in the input
00236   /// buffer with a new string.  This is effectively a combined "remove/insert"
00237   /// operation.
00238   bool ReplaceText(SourceRange range, StringRef NewStr) {
00239     return ReplaceText(range.getBegin(), getRangeSize(range), NewStr);
00240   }
00241 
00242   /// ReplaceText - This method replaces a range of characters in the input
00243   /// buffer with a new string.  This is effectively a combined "remove/insert"
00244   /// operation.
00245   bool ReplaceText(SourceRange range, SourceRange replacementRange);
00246 
00247   /// \brief Increase indentation for the lines between the given source range.
00248   /// To determine what the indentation should be, 'parentIndent' is used
00249   /// that should be at a source location with an indentation one degree
00250   /// lower than the given range.
00251   bool IncreaseIndentation(CharSourceRange range, SourceLocation parentIndent);
00252   bool IncreaseIndentation(SourceRange range, SourceLocation parentIndent) {
00253     return IncreaseIndentation(CharSourceRange::getTokenRange(range),
00254                                parentIndent);
00255   }
00256 
00257   /// getEditBuffer - This is like getRewriteBufferFor, but always returns a
00258   /// buffer, and allows you to write on it directly.  This is useful if you
00259   /// want efficient low-level access to apis for scribbling on one specific
00260   /// FileID's buffer.
00261   RewriteBuffer &getEditBuffer(FileID FID);
00262 
00263   /// getRewriteBufferFor - Return the rewrite buffer for the specified FileID.
00264   /// If no modification has been made to it, return null.
00265   const RewriteBuffer *getRewriteBufferFor(FileID FID) const {
00266     std::map<FileID, RewriteBuffer>::const_iterator I =
00267       RewriteBuffers.find(FID);
00268     return I == RewriteBuffers.end() ? nullptr : &I->second;
00269   }
00270 
00271   // Iterators over rewrite buffers.
00272   buffer_iterator buffer_begin() { return RewriteBuffers.begin(); }
00273   buffer_iterator buffer_end() { return RewriteBuffers.end(); }
00274   const_buffer_iterator buffer_begin() const { return RewriteBuffers.begin(); }
00275   const_buffer_iterator buffer_end() const { return RewriteBuffers.end(); }
00276 
00277   /// overwriteChangedFiles - Save all changed files to disk.
00278   ///
00279   /// Returns true if any files were not saved successfully.
00280   /// Outputs diagnostics via the source manager's diagnostic engine
00281   /// in case of an error.
00282   bool overwriteChangedFiles();
00283 
00284 private:
00285   unsigned getLocationOffsetAndFileID(SourceLocation Loc, FileID &FID) const;
00286 };
00287 
00288 } // end namespace clang
00289 
00290 #endif