Mozilla FireFox Gecko内核源代码解析(3.nsScanner)

Mozilla FireFox Gecko内核源代码解析

(3.nsScanner)

中科院计算技术研究所网络数据科学与工程研究中心

信息抽取小组

耿耘

gengyun@sohu.com

 

前面我们介绍了nsParser，nsTokenizer，它们之上都需要调用nsScanner获取基本的字符串信息，这里我们来介绍一下这个nsScanner。

nsScanner是一个为了给nsParser以及一些上层服务提供支持的底层类，它是一个功能完善，十分经典的字符串扫描器。它能够接受一个字符流（内部字符流），并且提供一些经典的扫描器方法，如readUntil()，以及SkipWhitespace()之类。说白了，它主要就是提供了一个可控制的字符串获取器，对HTML流进行逐字符的解析。

首先我们来看一下nsScanner.h的源代码

[cpp]  view plain copy

1. #include "nsCOMPtr.h"  
2. #include "nsString.h"  
3. #include "nsIParser.h"  
4. #include "prtypes.h"  
5. #include "nsIUnicodeDecoder.h"  
6. #include "nsScannerString.h"  
7. classnsParser;  
8. classnsReadEndCondition {  
9. public:  
10.   const PRUnichar *mChars;  
11.  PRUnichar mFilter;  
12.  //构造参数的显式转换，nsReadEndCondition = (PRUnichar)  
13.   explicit nsReadEndCondition(constPRUnichar* aTerminateChars);  
14. private:  
15.      //这种通过把相应的构造方法和运算符设置为私有变量的方法，可以防止从外部调用该方法，也就禁止了使用同类型变量对其进行拷贝，或使用=运算符对其进行赋值的操作  
16.  nsReadEndCondition(constnsReadEndCondition& aOther); // No copying  
17.   void operator=(const nsReadEndCondition& aOther); // No assigning  
18. };  
19. classnsScanner {  
20.   public:  
21.      /** 
22.        * Use this constructor if you want i/o to be based on 
23.        * a single string you hand in during construction. 
24.        * This short cut was added for Javascript. 
25.        * 
26.        * @update  ftang 3/02/99 
27.        * @param   aCharset charset 
28.        * @param   aCharsetSource - wherethe charset info came from 
29.        * @param   aMode represents theparser mode (nav, other) 
30.        * @return  
31.        */  
32.      nsScanner(const nsAString&anHTMLString, const nsACString& aCharset,PRInt32 aSource);      //构造方法nsScanner，这个构造方法可以让你的I/O基于一个固定的字符串  
33.    
34.      /** 
35.        * Use this constructor if you want i/o to be based on 
36.        * a file (therefore a stream) or just data you provide via Append(). 
37.        * 
38.        * @update  ftang 3/02/99 
39.        * @param   aCharset charset 
40.        * @param   aCharsetSource - wherethe charset info came from 
41.        * @param   aMode represents theparser mode (nav, other) 
42.        * @return  
43.        */  
44.       //构造方法，如果你希望你的I/O基于一个文件(实际上就是流)，或者是基于使用Append()，即不断加入新字符的情况下，可以使用这个构造方法  
45.      nsScanner(nsString& aFilename,PRBool aCreateStream, const nsACString& aCharset, PRInt32 aSource);  
46.    
47.      ~nsScanner(); //析构方法  
48.    
49.      /** 
50.        * retrieve next char from internal input stream 
51.        *  
52.        * @update  gess 3/25/98 
53.        * @param   ch is the char to acceptnew value 
54.        * @return  error code reflectingread status 
55.        */  
56.       //从输入的字符流中，获取下一个字节  
57.      nsresult GetChar(PRUnichar& ch);  
58.    
59.      /** 
60.        * peek ahead to consume next char from scanner's internal 
61.        * input buffer 
62.        *  
63.        * @update  gess 3/25/98 
64.        * @param   ch is the char to acceptnew value 
65.        * @return  error code reflectingread status 
66.        */  
67.       //从输入流中通过只读方式获取下一个字节  
68.      nsresult Peek(PRUnichar& ch, PRUint32 aOffset=0);  
69.    
70.       //从输入流中通过只读方式获取下一个字节  
71.      nsresult Peek(nsAString& aStr, PRInt32 aNumChars, PRInt32 aOffset =0);  
72.      /** 
73.        * Skip over chars as long as they equal given char 
74.        *  
75.        * @update  gess 3/25/98 
76.        * @param   char to be skipped 
77.        * @return  error code 
78.        */  
79.       //跳过接下来的字符，只要找到第一个字符和参数给定的字符不同为止  
80.      nsresult SkipOver(PRUnichar aSkipChar);  
81.    
82.      /** 
83.        * Consume characters until you run into space, a '<', a '>', or a'/'. 
84.        *  
85.        * @param   aString - receives newdata from stream 
86.        * @return  error code 
87.        */  
88.       //处理字符，直到遇到了一个’<’或者’>’，或者’/’为止  
89.      nsresult ReadTagIdentifier(nsScannerSharedSubstring& aString);  
90.    
91.      /** 
92.        * Consume characters until you run into a char that's not valid in an 
93.        * entity name 
94.        *  
95.        * @param   aString - receives newdata from stream 
96.        * @return  error code 
97.        */  
98.       //持续处理字符，直到你遇到一个不为Entity的字符为止  
99.      nsresult ReadEntityIdentifier(nsString& aString);  
100.      //下面这几个也是相应的特殊的读取字符方法，我们在后面的cpp文件中会具体分析  
101.      nsresult ReadNumber(nsString& aString,PRInt32 aBase);  
102.      nsresult ReadWhitespace(nsScannerSharedSubstring& aString,  
103.                               PRInt32&aNewlinesSkipped,  
104.                               PRBool&aHaveCR);  
105.      nsresult ReadWhitespace(nsScannerIterator& aStart,  
106.                              nsScannerIterator&aEnd,  
107.                               PRInt32&aNewlinesSkipped);  
108.    
109.      /** 
110.        * Consume characters until you find the terminal char 
111.        *  
112.        * @update  gess 3/25/98 
113.        * @param   aString receives new datafrom stream 
114.        * @param   aTerminal containsterminating char 
115.        * @param   addTerminal tells uswhether to append terminal to aString 
116.        * @return  error code 
117.        */  
118.      //读取字符，直到碰到terminal字符为止  
119.      nsresult ReadUntil(nsAString& aString,  
120.                          PRUnichar aTerminal,  
121.                          PRBool addTerminal);  
122.    
123.      /** 
124.        * Consume characters until you find one contained in given 
125.        * terminal set. 
126.        *  
127.        * @update  gess 3/25/98 
128.        * @param   aString receives new datafrom stream 
129.        * @param   aTermSet contains set ofterminating chars 
130.        * @param   addTerminal tells uswhether to append terminal to aString 
131.        * @return  error code 
132.        */  
133.      //读取字符，直到遇到了aEndCondition其中之一为止  
134.      nsresult ReadUntil(nsAString& aString,  
135.                          const nsReadEndCondition& aEndCondition,  
136.                          PRBool addTerminal);  
137.    
138.      nsresult ReadUntil(nsScannerSharedSubstring& aString,  
139.                          const nsReadEndCondition& aEndCondition,  
140.                          PRBool addTerminal);  
141.    
142.      nsresult ReadUntil(nsScannerIterator& aStart,  
143.                          nsScannerIterator&aEnd,  
144.                          const nsReadEndCondition& aEndCondition,  
145.                          PRBool addTerminal);  
146.      /** 
147.        * Records current offset position in input stream. This allows us 
148.        * to back up to this point if the need should arise, such as when 
149.        * tokenization gets interrupted. 
150.        *  
151.        * @update  gess 5/12/98 
152.        * @param   
153.        * @return  
154.        */  
155.      //记录下当前读取的位置，这允许我们将来需要的时候可以回溯到这个位置，比如分词操作被打断的时候  
156.      PRInt32 Mark(void);  
157.    
158.      /** 
159.        * Resets current offset position of input stream to marked position. 
160.        * This allows us to back up to this point if the need should arise, 
161.        * such as when tokenization gets interrupted. 
162.        * NOTE: IT IS REALLY BAD FORM TO CALL RELEASE WITHOUT CALLING MARK FIRST! 
163.        *  
164.        * @update  gess 5/12/98 
165.        * @param   
166.        * @return  
167.        */  
168.      //重设当前读取的位置到之前记录(Mark)的位置。调用这个方法允许我们在需要的时候回溯到该位置，比如分词过程被打断。  
169.      void RewindToMark(void);  
170.      /** 
171.        *  
172.        *  
173.        * @update  harishd 01/12/99 
174.        * @param   
175.        * @return  
176.        */  
177.      //将未解析的字符串返回给aBuffer里  
178.      PRBool UngetReadable(constnsAString& aBuffer);  
179.      /** 
180.        *  
181.        *  
182.        * @update  gess 5/13/98 
183.        * @param   
184.        * @return  
185.        */  
186.      //在解析器所要解析的字符串后面新增新的字符串  
187.      nsresult Append(const nsAString&aBuffer);  
188.      /** 
189.        *  
190.        *  
191.        * @update  gess 5/21/98 
192.        * @param   
193.        * @return  
194.        */  
195.      //和上一个方法作用相同，只不过形参不一样  
196.      nsresult Append(const char* aBuffer, PRUint32 aLen,  
197.                       nsIRequest *aRequest);  
198.    
199.      /** 
200.        * Call this to copy bytes out of the scanner that have not yet beenconsumed 
201.        * by the tokenization process. 
202.        *  
203.        * @update  gess 5/12/98 
204.        * @param   aCopyBuffer is where thescanner buffer will be copied to 
205.        * @return  nada 
206.        */  
207.      //调用这个方法获取当前未被分词器分词的字符串  
208.      void CopyUnusedData(nsString&aCopyBuffer);  
209.    
210.      /** 
211.        * Retrieve the name of the file that the scanner is reading from. 
212.        * In some cases, it's just a given name, because the scanner isn't 
213.        * really reading from a file. 
214.        *  
215.        * @update  gess 5/12/98 
216.        * @return  
217.        */  
218.      //获取扫描器所扫描的文件名字，其实这只是个名字而已，不一定是文件名，因为扫描器实际上并不是从文件中进行读取的  
219.      nsString& GetFilename(void);  
220.    
221.      //一个自我测试方法  
222.      static voidSelfTest();  
223.    
224.      /** 
225.        * Use this setter to change the scanner's unicode decoder 
226.        * 
227.        * @update  ftang 3/02/99 
228.        * @param   aCharset a normalized(alias resolved) charset name 
229.        * @param   aCharsetSource- where thecharset info came from 
230.        * @return  
231.        */  
232.      //设置文档所使用的字符集  
233.      nsresult SetDocumentCharset(constnsACString& aCharset, PRInt32 aSource);  
234.      //获取子字符串  
235.      voidBindSubstring(nsScannerSubstring& aSubstring, constnsScannerIterator& aStart, constnsScannerIterator& aEnd);  
236.      //获取当前位置  
237.      voidCurrentPosition(nsScannerIterator& aPosition);  
238.      //设置读取末尾  
239.      void EndReading(nsScannerIterator&aPosition);  
240.      //设置当前位置  
241.      void SetPosition(nsScannerIterator&aPosition,  
242.                        PRBool aTruncate =PR_FALSE,  
243.                        PRBool aReverse =PR_FALSE);  
244.      //替换该位置的字符  
245.      void ReplaceCharacter(nsScannerIterator&aPosition,  
246.                             PRUnichar aChar);  
247.      /** 
248.        * Internal method used to cause theinternal buffer to 
249.        * be filled with data. 
250.        * 
251.        * @update  gess4/3/98 
252.        */  
253.      //获取是否是mIncremental即单字节模式，如果是则是按字节进行读取  
254.      PRBool    IsIncremental(void) {returnmIncremental;}  
255.      //设置mIncremental模式  
256.      void     SetIncremental(PRBool anIncrValue) {mIncremental=anIncrValue;}  
257.      /** 
258.        * Return the position of the firstnon-whitespace 
259.        * character. This is only reliablebefore consumers start 
260.        * reading from this scanner. 
261.        */  
262.      //获取从当前位置起第一个不为空白字符的位置。这只有在外部模块在开始从扫描器获取字符前有效  
263.      PRInt32 FirstNonWhitespacePosition()  
264.      {  
265.        return mFirstNonWhitespacePosition;  
266.      }  
267.      //设置该扫描器对应的解析器  
268. void SetParser(nsParser*aParser)  
269.      {  
270.        mParser = aParser;  
271.      }  
272.    
273.      /** 
274.        * Override replacement character used bynsIUnicodeDecoder. 
275.        * Default behavior is that it usesnsIUnicodeDecoder's mapping. 
276.        * 
277.        * @param aReplacementCharacter thereplacement character 
278.        *       XML (expat) parser uses 0xffff 
279.        */  
280.       //重设替换用的字符  
281.      voidOverrideReplacementCharacter(PRUnichar aReplacementCharacter);  
282.    
283. //下面我们看一下数据成员：  
284.   protected:  
285.      //将字符串附加到被解析的字符串上的函数  
286.      PRBool AppendToBuffer(nsScannerString::Buffer *, nsIRequest *aRequest,PRInt32 aErrorPos = -1);  
287.      PRBool AppendToBuffer(constnsAString& aStr)  
288.      {  
289.        nsScannerString::Buffer* buf =nsScannerString::AllocBufferFromString(aStr);  
290.        if (!buf)  
291.          return PR_FALSE;  
292.        AppendToBuffer(buf, nsnull);  
293.        return PR_TRUE;  
294.      }  
295.      //带解析的字符串  
296.      nsScannerString*            mSlidingBuffer;  
297.      //解析器的当前解析位置  
298.      nsScannerIterator           mCurrentPosition; // The position we will nextread from in the scanner buffer  
299.      //解析器记录的位置  
300.      nsScannerIterator           mMarkPosition;    // The position last marked (we may rewind to here)  
301.      //当前解析器字符串的结束位置  
302.      nsScannerIterator           mEndPosition;     // The current end of the scanner buffer  
303.      //第一个检测出非法字符的位置  
304.      nsScannerIterator           mFirstInvalidPosition; // The position of thefirst invalid character that was detected  
305.      //文件名，其实并不是从文件读取  
306.      nsString        mFilename;  
307.      //scanner还未读取的字符串中的剩余字节  
308.      PRUint32        mCountRemaining; // The number of bytes still to be read  
309.                                        // from the scanner buffer  
310.      //是否是单字节式解析  
311.      PRPackedBool    mIncremental;  
312.      PRPackedBool   mHasInvalidCharacter;    //是否有非法的字符  
313.      PRUnichar      mReplacementCharacter;   //替换用字符  
314.      PRInt32        mFirstNonWhitespacePosition; //第一个非空白字符的位置  
315.      PRInt32         mCharsetSource;     //字符集编号  
316.      nsCString       mCharset;      //字符集名称  
317.      nsCOMPtr<nsIUnicodeDecoder> mUnicodeDecoder; //Unicode编码器  
318.      nsParser        *mParser;  //当前扫描器所对应的解析器  
319.    
320.   private:  
321.      nsScanner &operator =(const nsScanner &); //Not implemented.  

  

以上就是nsScanner的头文件定义，其中的具体实现都在nsScanner.cpp文件中，下面我们来具体看看nsScanner.cpp中的具体实现：

 

[cpp]  view plain copy

1. //我们忽略开头的一堆include文件，直接看其有效代码  
2. // We replace NUL characterswith this character.  
3. //我们会使用以下字符替换NUL字符  
4. staticPRUnichar sInvalid = UCS2_REPLACEMENT_CHAR;  
5.    
6. nsReadEndCondition::nsReadEndCondition(const PRUnichar* aTerminateChars) :  
7.  mChars(aTerminateChars), mFilter(PRUnichar(~0)) //All bits set  
8. {  
9.   // Build filter that will be used to filter out characterswith  
10.   // bits that none ofthe terminal chars have. This works very well  
11.   // because terminal chars often have only the last 4-6 bitsset and  
12.   // normal ascii letters have bit 7 set. Other letters haveeven higher  
13.   // bits set.  
14.    
15.   // Calculate filter  
16.   //注意到，这个构造方法主要是为了建立一个名为Filter的字符，该字符会用来过滤其他拥有它所没有的bit位的字符，但我们首先要先来构建这个Filter。据作者说，这个Filter的工作效果很好，因为大部分的terminal字符只有低位的第4至第6bit设置了，但是一般的ascii字符的第7位bit设置了。其他的字符可能会有更高位的bit被设置了。  
17.  //注意两个参数，aTerminateChars是存放terminate字符的数组，而mFilter字符各个bit位首先被置为了全1  
18.  //首先获取aTerminateChars数组的首地址  
19.   const PRUnichar *current = aTerminateChars;  
20.  //获取该数组地一个字符，放到terminalChar里  
21.  PRUnichar terminalChar = *current;  
22.  //当terminalChar不为空的时候，即遍历整个terminalChar数组  
23.   while (terminalChar) {  
24.    mFilter &= ~terminalChar;    //用terminalChar的反码和mFilter进行与运算，也就是说如果terminalChar的第N位为1的话，那么mFilter的第N位则会被至为0  
25.    ++current;     //取下一个TerminateChars数组元素的地址  
26.    terminalChar = *current;     //并且其赋值给terminalChar  
27.  }  
28. }  
29.    
30. #ifdef__INCREMENTAL   //如果设置了INCREMENTAL位  
31. const int   kBufsize=1;     //设置缓冲区大小为1  
32. #else  
33. const int  kBufsize=64;    //否则设置为64  
34. #endif  
35. /** 
36.  *  Usethis constructor if you want i/o to be based on 
37.  *  asingle string you hand in during construction. 
38.  *  Thisshort cut was added for Javascript. 
39.  * 
40.  * @update  gess 5/12/98 
41.  * @param   aMode represents theparser mode (nav, other) 
42.  * @return  
43.  */  
44. //如果你希望i/o基于一个在构造方法时传递过来的单独的字符串则可以使用这个方法进行构造。这个捷径主要是为了给Javascript提供支持而添加的  
45. nsScanner::nsScanner(const nsAString& anHTMLString, const nsACString& aCharset,  
46.                      PRInt32 aSource)  
47.  : mParser(nsnull)  
48. {  
49.  MOZ_COUNT_CTOR(nsScanner);  
50. //以下设置几个变量的初始值  
51.  mSlidingBuffer = nsnull;  
52.  mCountRemaining = 0;  
53.  mFirstNonWhitespacePosition = -1;  
54.   if (AppendToBuffer(anHTMLString)) {     //将给定的字符串拷贝到当前要解析的buffer中  
55.    mSlidingBuffer->BeginReading(mCurrentPosition);     //开始解析，需要注意的是，实际上并不是从mCurrentPosition位置开始解析，而是开始解析，并把位置赋值给mCurrentPosition  
56.  } else {    //其他情况下，说明将字符串拷贝给buffer失败了  
57.    /* XXX see hack below, re: bug 182067 */  
58.    memset(&mCurrentPosition, 0, sizeof(mCurrentPosition));  //貌似通过内存设置方式直接将其指针置空  
59.    mEndPosition = mCurrentPosition; //此时这两个值都应当为0  
60.  }  
61.  mMarkPosition = mCurrentPosition;  //记录一下当前的位置  
62.  mIncremental = PR_FALSE;  //设置增量式解析位为FALSE  
63.  mUnicodeDecoder = 0; //某个变量  
64.  mCharsetSource = kCharsetUninitialized; //字符集变量  
65.  mHasInvalidCharacter = PR_FALSE;   //设置是否有非法字符  
66.  mReplacementCharacter = PRUnichar(0x0); //设置如果遇到非法字符的替换字符  
67. }  
68. //设置扫描器所用的字符集  
69. nsresult nsScanner::SetDocumentCharset(const nsACString& aCharset , PRInt32 aSource)  
70. {  
71.  //字符集是有优先级的，首先应对其进行判断，低优先级的字符集一般是高优先级的字符集子集，设置的时候需要进行判断  
72.   if (aSource < mCharsetSource) // priority is lower the the current one , just  
73.    return NS_OK;      //如果新字符集的优先级较低，直接返回  
74.    
75.  nsICharsetAlias* calias = nsParser::GetCharsetAliasService();  //获取字符集服务  
76.  NS_ASSERTION(calias, "Must have thecharset alias service!");  //确保获取成功  
77.    
78.  nsresult res = NS_OK;  
79.   if (!mCharset.IsEmpty())       //如果当前字符集不为空  
80.  {  
81.    PRBool same;  
82.    res = calias->Equals(aCharset, mCharset, &same);    //判断一下新字符集和当前字符集是否是同一个字符集  
83.    if(NS_SUCCEEDED(res) && same)    //如果两个字符集一样  
84.    {    //则直接返回  
85.      return NS_OK; //no difference, don't change it  
86.    }  
87.  }  
88.  //运行到此处，说明两个字符集不一样，且新字符集的优先级较高，需要进行替换  
89.   // different, need to change it  
90.  nsCString charsetName;  
91.  res = calias->GetPreferred(aCharset, charsetName);    //获取字符集名称  
92.    
93.   if(NS_FAILED(res) && (mCharsetSource ==kCharsetUninitialized))  
94.  {  //如果获取失败，且当前的字符集为空  
95.     // failed - unknown alias , fallback toISO-8859-1  
96.    mCharset.AssignLiteral("ISO-8859-1"); //那么默认使用ISO-8859-1字符集  
97.  }  
98.   else  
99.  {  
100.    mCharset.Assign(charsetName);    //获取成功，则直接使用该字符集  
101.  }  
102.  mCharsetSource = aSource;      //设置字符集源值  
103.  NS_ASSERTION(nsParser::GetCharsetConverterManager(),  
104.                "Musthave the charset converter manager!");  
105.  //获取UnicodeDecoder  
106.  res = nsParser::GetCharsetConverterManager()->  
107.    GetUnicodeDecoderRaw(mCharset.get(), getter_AddRefs(mUnicodeDecoder));  
108.   if (NS_FAILED(res))  //如果获取UnicodeDecoder失败  
109.  {  
110.    // GetUnicodeDecoderRaw can fail if thecharset has the .isXSSVulnerable  
111.    // flag. Try to fallback to ISO-8859-1  
112.    mCharset.AssignLiteral("ISO-8859-1"); //则还是默认使用ISO-8859-1字符集  
113.    mCharsetSource = kCharsetFromWeakDocTypeDefault;    //设置为最低优先级  
114.    res = nsParser::GetCharsetConverterManager()-> //获取相应的UnicodeDecoder  
115.      GetUnicodeDecoderRaw(mCharset.get(), getter_AddRefs(mUnicodeDecoder));  
116.  }  
117.  //如果获取成功  
118.   if (NS_SUCCEEDED(res) && mUnicodeDecoder)  
119.  {  
120.     // We need to detect conversion error ofcharacter to support XML  
121.     // encoding error.  
122.      //我们需要对字符转换的错误进行监测，从而支持XML编码中的错误  
123.     mUnicodeDecoder->SetInputErrorBehavior(nsIUnicodeDecoder::kOnError_Signal);  
124.      //为UnicodeDecoder进行错误行为处理设置  
125.  }  
126.    
127.   return res;          //返回处理结果  
128. }  
129. //下面是析构方法  
130. /** 
131.  * default destructor 
132.  *  
133.  * @update  gess 3/25/98 
134.  * @param   
135.  * @return  
136.  */  
137. nsScanner::~nsScanner() {  
138.    
139.   if (mSlidingBuffer) {      
140.    delete mSlidingBuffer;  //删除当前未扫描的字符串  
141.  }  
142.    
143.  MOZ_COUNT_DTOR(nsScanner);     //用来进行日志记录的一个构件方法，如果没有特殊#Define NS_BUILD_REFCNT_LOGGING的话，这个方法一般为空，什么都不做  
144. }  
145. /** 
146.  * default destructor 
147.  *  
148.  * @update  gess 3/25/98 
149.  * @param   
150.  * @return  
151.  */  
152. nsScanner::~nsScanner() {  
153.    
154.   if (mSlidingBuffer) {      
155.    delete mSlidingBuffer;  //删除当前未扫描的字符串  
156.  }  
157.    
158.  MOZ_COUNT_DTOR(nsScanner);     //用来进行日志记录的一个构件方法，如果没有特殊#Define NS_BUILD_REFCNT_LOGGING的话，这个方法一般为空，什么都不做  
159. }  
160.    
161. //上面提到过了一个Mark的方法，用来提供回溯时的记录位，下面我们来看看回溯的Rewind方法，很简单的实现。  
162.    
163. /** 
164.  * Resets current offset position of input stream to marked position. 
165.  *  Thisallows us to back up to this point if the need should arise, 
166.  *  suchas when tokenization gets interrupted. 
167.  *  NOTE:IT IS REALLY BAD FORM TO CALL RELEASE WITHOUT CALLING MARK FIRST! 
168.  * 
169.  * @update  gess 5/12/98 
170.  * @param   
171.  * @return  
172.  */  
173. voidnsScanner::RewindToMark(void){  
174.   if (mSlidingBuffer) {     //如果当前存在一个mSlidingBuffer  
175.    mCountRemaining += (Distance(mMarkPosition, mCurrentPosition));   //修改剩余的字节数，需要加上Mark位置到当前位置的距离  
176.    mCurrentPosition = mMarkPosition;     //设置当前位置为Mark的位置  
177.  }  
178. }  
179.    
180.    
181. //下面是在上面方法执行之前必须进行的Mark方法。  
182.    
183. /** 
184.  * Records current offset position in input stream. This allows us 
185.  *  toback up to this point if the need should arise, such as when 
186.  * tokenization gets interrupted. 
187.  * 
188.  * @update  gess 7/29/98 
189.  * @param   
190.  * @return  
191.  */  
192. PRInt32 nsScanner::Mark() {  
193.  PRInt32 distance = 0;     //设置距离为0  
194.   if (mSlidingBuffer) {     //如果当前字符串存在  
195. nsScannerIteratoroldStart;       //设置一个游标  
196. mSlidingBuffer->BeginReading(oldStart);    //用该游标记录下原始的起始位置  
197.    distance = Distance(oldStart, mCurrentPosition);  
198.    mSlidingBuffer->DiscardPrefix(mCurrentPosition);    //去掉当前位置mCurrentPosition之前的字符串  
199.    mSlidingBuffer->BeginReading(mCurrentPosition);  //设置起始位置为mCurrentPosition  
200.    mMarkPosition = mCurrentPosition;     //设置mMarkPosition为mCurrentPosition  
201.  }  
202.   return distance;  
203. }  
204.    
205. //下面这个方法，主要是配合Parse中，将上一次解析时没有处理完的字符串，重新插入到当前扫描器中去的方法。  
206.    
207. /** 
208.  * Insert data to our underlying input bufferas 
209.  * if it were read from an input stream. 
210.  * 
211.  * @update harishd 01/12/99 
212.  * @return error code 
213.  */  
214. PRBool nsScanner::UngetReadable(const nsAString& aBuffer) {  
215.   if (!mSlidingBuffer) {    //如果当前的解析字符串不存在  
216.    return PR_FALSE;   //则返回  
217.  }  
218.    
219.  mSlidingBuffer->UngetReadable(aBuffer,mCurrentPosition);   //调用mSlidingBuffer的UngetReadable，将aBuffer插入到mCurrentPosition中去  
220.  //重新设置读取的起始位置和结束位置，因为插入操作会破坏我们原始的游标  
221.  mSlidingBuffer->BeginReading(mCurrentPosition); // Insertion invalidated our iterators  
222.  mSlidingBuffer->EndReading(mEndPosition);  
223.  //获取新插入字符串的长度  
224.  PRUint32 length = aBuffer.Length();  
225.  //在原始未解析的字符串长度上加上新插入字符串的长度  
226.  mCountRemaining += length; // Ref. bug 117441  
227.   return PR_TRUE;  
228. }  
229.    
230. //下面这几个Append方法主要是为了给普通的I/O提供服务，即将新到来的字符串附到原始待解析的字符串末尾端。  
231.    
232. /** 
233.  * Append data to our underlying input bufferas 
234.  * if it were read from an input stream. 
235.  * 
236.  * @update gess4/3/98 
237.  * @return error code 
238.  */  
239. nsresult nsScanner::Append(const nsAString& aBuffer) {  
240.   if (!AppendToBuffer(aBuffer))  //直接调用AppendToBuffer方法  
241.    return NS_ERROR_OUT_OF_MEMORY;  
242.   return NS_OK;  
243. }  
244.    
245.    
246. /** 
247.  *  
248.  *  
249.  * @update  gess 5/21/98 
250.  * @param   
251.  * @return  
252.  */  
253. //对于C++中，字符型数组作为参数，除了其指针，一般都需要传递其长度  
254. nsresult nsScanner::Append(const char* aBuffer,PRUint32 aLen,  
255.                            nsIRequest*aRequest)  
256. {  
257.  nsresult res=NS_OK;  
258.  PRUnichar *unichars, *start;  
259.   if (mUnicodeDecoder) {  
260.    PRInt32 unicharBufLen = 0;  
261. mUnicodeDecoder->GetMaxLength(aBuffer,aLen, &unicharBufLen); //就是unicharBufLen = aLen + 1  
262. //申请一个新数组，长度为unicharBufLen + 1，因为C++中字符数组最后一位要放’\0’  
263.    nsScannerString::Buffer* buffer =nsScannerString::AllocBuffer(unicharBufLen + 1);  
264. NS_ENSURE_TRUE(buffer,NS_ERROR_OUT_OF_MEMORY);  
265. //指针指向字符数组的第一个字节  
266.    start = unichars = buffer->DataStart();  
267.    //初始化几个变量  
268.    PRInt32 totalChars = 0;  
269.    PRInt32 unicharLength = unicharBufLen;  
270. PRInt32errorPos = -1;  
271. //下面这个循环主要就是对于那些非法的字符(即无法识别的字符)需要用之前设置好的Replacement字符进行替换。  
272.    do {  
273.      PRInt32 srcLength = aLen;  //设置一个变量，记录附加字符串的原始长度  
274.      //进行字符串转换，转换结果放到unichars中去，并在unicharLength中记录转换后的字符串长度  
275.      res = mUnicodeDecoder->Convert(aBuffer, &srcLength, unichars,&unicharLength);  
276.      //将总字节数，加上unicharLength  
277.      totalChars += unicharLength;  
278.       // Continuationof failure case  
279.      if(NS_FAILED(res)) {  
280.        // if we failed, we consume one byte, replaceit with the replacement  
281.        // character and try the conversion again.  
282.        // This is only needed because some decodersdon't follow the  
283.        // nsIUnicodeDecoder contract: they return afailure when *aDestLength  
284.         // is 0rather than the correct NS_OK_UDEC_MOREOUTPUT. See bug 244177  
285.          //运行到这里，说明我们刚才的转换操作失败了，我们将错误字符替换为代替字符，并且再次尝试对其进行转换。  
286.          //这只有在有些解码器不符合nsIUnicodeDecoder规则的时候才会发生：他们当  
287.            DestLength为0的时候会返回一个失败值  
288.        if ((unichars + unicharLength) >=buffer->DataEnd()) {   //如果超出了最大长度  
289.          NS_ERROR("Unexpected end of destinationbuffer");  //指针越界出错了  
290.          break;  
291.        }  
292.          if (mReplacementCharacter == 0x0 && errorPos== -1) {    //如果替换字符为0，且出错位置为-1  
293.          errorPos = totalChars;     //出错位置直接记录为整体字符串  
294.        }  
295.          //进行字符替换  
296.        unichars[unicharLength++] = mReplacementCharacter == 0x0 ?  
297.                                    mUnicodeDecoder->GetCharacterForUnMapped() :  
298.                                    mReplacementCharacter;  
299.          //重新设置字符串的起始位置和长度  
300.        unichars = unichars + unicharLength;  
301.        unicharLength = unicharBufLen - (++totalChars);  
302.          //重设UnicodeDecoder  
303.        mUnicodeDecoder->Reset();  
304.        if(((PRUint32) (srcLength + 1)) >aLen) {  //此处应当是出现了错误字符才会导致的情况  
305.          srcLength = aLen;  
306.        }  
307.        else {     //一般情况下只需要进行加一操作，即按序解析下一个字符  
308.          ++srcLength;  
309.        }  
310.        aBuffer += srcLength;    //将aBuffer向后移动srcLength个位置  
311.        aLen -= srcLength;  //减少srcLength长度，即已经解析的字节数  
312.      }  
313. }while (NS_FAILED(res) && (aLen >0));  
314.    
315.    buffer->SetDataLength(totalChars);    //设置buffer的数据长度为新的数据长度  
316.    // Don't propagate return code of unicodedecoder  
317.    // since it doesn't reflect on our success orfailure  
318.    // - Ref. bug 87110  
319. res= NS_OK;  
320.    if (!AppendToBuffer(buffer, aRequest,errorPos))    //使用转换好的字符串进行AppendToBuffer操作，这个操作在代码的最后会进行介绍  
321.      res = NS_ERROR_OUT_OF_MEMORY;  
322.   }  
323.    
324.   else {      //其他情况下，说明Append操作失败  
325.    NS_WARNING("No decoder found.");  
326.    res = NS_ERROR_FAILURE;      //设置结果为错误值  
327.  }  
328.    
329.   return res; //返回结果  
330. }  
331.    
332. //看完了上面的一些方法，我们来看接下来的几个经典的Scanner所支持的操作：  
333. /** 
334.  * retrieve next char from scanners internal input stream 
335.  *  
336.  * @update  gess 3/25/98 
337.  * @param   
338.  * @return  error code reflectingread status 
339.  */  
340. //这个方法很简单，就是“取出”字符流中的第一个字符，并将aChar指向的它  
341. nsresultnsScanner::GetChar(PRUnichar& aChar) {  
342.   if (!mSlidingBuffer || mCurrentPosition ==mEndPosition) { //先判断一下当前解析是不是已经到结尾了，或者带解析的字符串本身就不存在  
343.    aChar = 0;  
344.    return kEOF;   //返回文件末尾，即空值  
345.  }  
346.    
347.  aChar = *mCurrentPosition++;   //设置aChar为当前的位置加一  
348.  --mCountRemaining;   //减少剩余未解析的字节数  
349.    
350.   return NS_OK;  
351. }  
352.    
353. //下面这个方法和上面的方法不同，并不是“取出(Get)”，而是只读方式的“浏览(Peek)”，代码很简单  
354.    
355. /** 
356.  *  peekahead to consume next char from scanner's internal 
357.  *  inputbuffer 
358.  *  
359.  * @update  gess 3/25/98 
360.  * @param   
361.  * @return  
362.  */  
363. //浏览从当前位置起，aOffset之后个位置的字符，并将aChar指向该字符  
364. nsresult nsScanner::Peek(PRUnichar&aChar, PRUint32 aOffset) {  
365.  aChar = 0;  
366.   if (!mSlidingBuffer || mCurrentPosition ==mEndPosition) { //如果当前待解析的字符串不存在，或当前位置等于结束位置了  
367.    return kEOF;   //返回文件末尾kEOF，即空  
368.  }  
369.   if (aOffset > 0) {   //如果aOffset大于零  
370.    if (mCountRemaining <= aOffset)  //如果偏移位置超过了剩余字节的数量  
371.      return kEOF; //直接返回空（为啥不返回最后一个字节呢，合情合理）  
372.    
373.    nsScannerIterator pos = mCurrentPosition;  //获取当前位置  
374.    pos.advance(aOffset);   //前进aOffset个位置  
375.    aChar=*pos;    //用aChar指向该位置的字符  
376.  }  
377.   else {  
378.    aChar=*mCurrentPosition;     //其他情况下，即aOffset为0或者为负值的情况下，直接指向当前位置  
379.  }  
380.    
381.   return NS_OK;    //返回正确结果  
382. }  
383.    
384.    
385. //下面这个Peek方法，同样是浏览，但是一次获取的是若干个字符，并不是单个字符  
386.    
387. //较前一个方法，多了一个aNumChars，用来记录取出字符的数量  
388. nsresult nsScanner::Peek(nsAString&aStr, PRInt32 aNumChars, PRInt32 aOffset)  
389. {  
390.   if (!mSlidingBuffer || mCurrentPosition ==mEndPosition) { //如果当前待解析的字符串为空，或当前位置已经是结束的位置了  
391.    return kEOF;   //直接返回文件末尾值，即空值  
392.  }  
393.  nsScannerIterator start, end;  //设置两个游标start，end  
394.  start = mCurrentPosition;      //start游标指向当前位置  
395.    
396.   if ((PRInt32)mCountRemaining <= aOffset) {   //如果偏移值超过了剩余字节的数量  
397.    return kEOF;   //返回文件末尾值  
398.  }  
399.    
400.   if (aOffset > 0) {   //如果偏移值大于0  
401.    start.advance(aOffset);      //游标start向前前进aOffset个位置  
402.  }  
403.    
404.   if (mCountRemaining < PRUint32(aNumChars +aOffset)) {     //这个和前面的Peek方法就不一样了，如果需要获取的字符串的末位置超出了文档结尾，则已文档末尾作为获取字符串的结束位置  
405.    end = mEndPosition;  
406.  }  
407.   else { //其他情况下，即正常情况  
408.    end = start;  
409.    end.advance(aNumChars); //将end在start的基础上前进aNumChars个字节  
410.  }  
411.  CopyUnicodeTo(start, end, aStr);   //这样就直接可以获取start和end之间的字符串作为结果放到aStr中去了  
412.   return NS_OK;    //返回正确值  
413. }  
414.    
415. //下面这个方法，是让扫描器从当前开始，不断前进，直到遇到一个不为空字符类型（\0，\r，\n）的字符，其过程并不复杂且很好理解。  
416.    
417. /** 
418.  *  Skipwhitespace on scanner input stream 
419.  *  
420.  * @update  gess 3/25/98 
421.  * @param   
422.  * @return  error status 
423.  */  
424. nsresult nsScanner::SkipWhitespace(PRInt32&aNewlinesSkipped) {  
425.  //aNewlinesSkipped中记录跳过的行数  
426.   if (!mSlidingBuffer) {    //如果当前解析字符串为空  
427.    return kEOF;   //返回文件末尾值，即空值  
428.  }  
429.  PRUnichar theChar = 0;    //设置一个字符变量  
430.  nsresult  result = Peek(theChar);  //获取当前位置的字符  
431.   if (NS_FAILED(result)) {  //如果获取失败  
432.    return result;     //则返回该结果  
433.  }  
434.    
435.  nsScannerIterator current = mCurrentPosition;    //获取当前位置的游标  
436.  //设置两个变量  
437.  PRBool    done = PR_FALSE;  
438.  PRBool    skipped = PR_FALSE;  
439.   //进行循环，直到文件末尾，或者遇到不为空字符的字符为止  
440.   while (!done && current != mEndPosition) {  
441.    switch(theChar) {  
442.      case '\n':  
443.      case '\r':++aNewlinesSkipped; //遇到\r或者\n，则对参数中的变量+1  
444.      case ' ':  
445.      case '\t':  
446.        {  
447.          skipped = PR_TRUE;     //设置遇到了空字符并进行了跳过  
448.          PRUnichar thePrevChar = theChar;     //用thePrevChar记录当前字节  
449.          theChar = (++current != mEndPosition) ? *current : '\0';    //如果到文件末尾了，那么直接将theChar写成’\0’  
450.          if ((thePrevChar == '\r' && theChar == '\n') ||  
451.               (thePrevChar == '\n' && theChar == '\r')) {  
452.             theChar = (++current !=mEndPosition) ? *current : '\0'; // CRLF == LFCR => LF        //如果遇到了’\r’和’\n’结合使用的情况，再多跳过一个字节  
453.          }  
454.        }  
455.        break;  
456.      default:  
457.        done = PR_TRUE;     //其他情况下即遇到非空字符，则设置DONE为PR_TRUE以跳出循环  
458.        break;  
459.    }  
460.  }  
461.    
462.   if (skipped) {   //如果发生了跳过空字符  
463.    SetPosition(current);   //设置当前位置为新位置  
464.    if (current == mEndPosition) {   //如果当前位置为mEndPosition  
465.      result = kEOF;   //返回文件末尾值  
466.    }  
467.  }  
468.   return result;   //返回结果  
469. }  
470.    
471. //下面这个方法，是让扫描器从当前开始，不断前进，直到遇到一个不为参数所给出的aSkipChar为止。  
472.    
473. /** 
474.  *  Skipover chars as long as they equal given char 
475.  *  
476.  * @update  gess 3/25/98 
477.  * @param 
478.  * @return  error code 
479.  */  
480. nsresult nsScanner::SkipOver(PRUnicharaSkipChar){  
481.    
482.   if (!mSlidingBuffer) {    //如果当前待解析字符串为空  
483.    return kEOF;   //返回空值  
484.  }  
485.  //初始化两个变量  
486.  PRUnichar ch=0;  
487.  nsresult   result=NS_OK;  
488.   while(NS_OK==result) {    //循环进行字符跳过  
489.    result=Peek(ch);   //获取当前位置的字符  
490.    if(NS_OK == result) {   //如果获取成功  
491.      if(ch!=aSkipChar) {   //如果当前位置字符和所给定字符不等  
492.        break;     //跳出循环  
493.      }  
494.      GetChar(ch);     //调用前面的GetChar获取下一个字符  
495.    }  
496.    else break;    //其他情况下，即Peek()返回失败值，则退出循环  
497.  } //while  
498.   return result;   //返回结果  
499. }  
500.    
501. //下面这个方法，是针对Tag进行的，会让扫描器从当前位置开始，一直读取，直到遇到了一个’<’，或’>’，或’/’字符，或者前面提到过的空格型字符为止。  
502. /** 
503.  * Consume characters until you run into space, a '<', a '>', or a'/'. 
504.  *  
505.  * @param   aString - receives newdata from stream 
506.  * @return  error code 
507.  */  
508. nsresultnsScanner::ReadTagIdentifier(nsScannerSharedSubstring& aString) {  
509.    
510.   if (!mSlidingBuffer) {    //如果当前待解析的字符串为空  
511.    return kEOF;   //返回文件末尾值，即空值  
512.  }  
513. //设置并初始化一些需要用的变量  
514.  PRUnichar         theChar=0;  
515.  nsresult         result=Peek(theChar);  
516.  nsScannerIterator current, end;  
517.  PRBool           found=PR_FALSE;   
518.    
519.  current = mCurrentPosition;  
520.  end = mEndPosition;  
521.    
522.   // Loop until we find an illegal character. Everything isthen appended  
523.   // later.  
524.  //下面这个循环，不断地循环，直到找到一个非法的字符为止  
525.   while(current != end && !found) {  
526.    theChar=*current;  
527.    
528.    switch(theChar) {  
529.      case '\n':  
530.      case '\r':  
531.      case ' ':  
532.      case '\t':  
533.      case '\v':  
534.      case '\f':  
535.      case '<':  
536.      case '>':  
537.      case '/':  
538.        found = PR_TRUE;    //找到非法字符，设置相应标示位  
539.        break;  
540.    
541.      case '\0':  
542.        ReplaceCharacter(current, sInvalid);   //如果是空字符则使用特殊字符对其进行替换  
543.        break;  
544.    
545.      default:  
546.        break;  
547. }  
548.    if (!found) {  //如果没找到  
549.      ++current;   //则将当前位置前进一个字符  
550.    }  
551. }  
552.  SetPosition(current);     //设置当前位置为新位置  
553.   if (current == end) {     //如果当前已经到了文件末尾  
554.    result = kEOF;     //返回文件末尾值  
555.  }  
556.    
557.   //DoErrTest(aString);  
558.    
559.   return result;   //返回处理结果  
560. }  
561.    
562. //下面这个方法，是让扫描器不断地读取字符，直到遇到了一个实体名为止。  
563.    
564. /** 
565.  * Consume characters until you run into a char that's not valid in an 
566.  * entity name 
567.  *  
568.  * @param   aString - receives newdata from stream 
569.  * @return  error code 
570.  */  
571. //和前面的方法基本相同，区别就是判断条件改为了：’_’，’-’，’.’或大小写字符及数字  
572. nsresultnsScanner::ReadEntityIdentifier(nsString& aString) {  
573.    
574.   if (!mSlidingBuffer) {    //对待解析字符串进行判断  
575.    return kEOF;  
576.  }  
577.  //设置几个变量  
578.  PRUnichar         theChar=0;  
579.  nsresult         result=Peek(theChar);  
580.  nsScannerIterator origin, current, end;  
581.  PRBool           found=PR_FALSE;   
582.  //下面几个变量用来记录位置信息  
583.  origin = mCurrentPosition;  
584.  current = mCurrentPosition;  
585.  end = mEndPosition;  
586.    
587.   while(current != end) {   //循环遍历字符串，直到末尾或主动退出  
588.    theChar=*current;  //获取当前位置的字符  
589.    if(theChar) {  //如果字符存在  
590.      found=PR_FALSE;  //设置是否找到位found默认值为PR_FALSE  
591.      switch(theChar) {  
592.        case '_':  
593.        case '-':  
594.        case '.':  
595.          // Don't allow ':' in entity names.  See bug 23791  
596.          found = PR_TRUE;  
597.          break;  
598.        default:  
599.          found = ('a'<=theChar &&theChar<='z') ||  
600.                   ('A'<=theChar&& theChar<='Z') ||  
601.                   ('0'<=theChar&& theChar<='9');  
602.          break;  
603.      }  
604.      if(!found) {     //这里不应当对是否前进了进行一下判断么？如果mCurrentPosition和current相等怎么办？他似乎默认当前一定能找到Entity字符  
605.         //如果该字符不是任何Entity字符，那么将CurrentPosition位置和当前位置之间的字符串Append到aString中去  
606.        AppendUnicodeTo(mCurrentPosition, current,aString);  
607.        break;  
608.      }  
609.    }  
610.    ++current;     //将current前进一位  
611.  }  
612.    
613.  SetPosition(current);     //将当前位置设置为新的位置  
614.   if (current == end) {     //如果发现是文件末尾了  
615.    AppendUnicodeTo(origin, current, aString);  //将原始的position和当前位置之间的这段字符串粘贴到aString中去  
616.    return kEOF;  
617.  }  
618.   //DoErrTest(aString);  
619.   return result;   //返回结果  
620. }  
621.    
622. //下面这个ReadNumber方法和刚才那个方法几乎一样，只不过不是读取EntityName，而是读取数字，一旦遇到非数字就退出。  
623.    
624. /** 
625.  * Consume digits 
626.  *  
627.  * @param   aString - should containdigits 
628.  * @return  error code 
629.  */  
630. nsresultnsScanner::ReadNumber(nsString& aString,PRInt32 aBase) {  
631.    
632.   if (!mSlidingBuffer) {    //对待解析字符串的存在进行判定  
633.    return kEOF;  
634.  }  
635. //判断aBase值进行判断，判断是什么进制的，目前只支持10进制或16进制  
636.  NS_ASSERTION(aBase == 10 || aBase == 16,"basevalue not supported");  
637. //设置一些变量  
638.  PRUnichar         theChar=0;  
639.  nsresult         result=Peek(theChar);  
640.  nsScannerIterator origin, current, end;  
641. //下面这些变量用来记录位置信息  
642.  origin = mCurrentPosition;  
643.  current = origin;  
644.  end = mEndPosition;  
645.    
646.  PRBool done = PR_FALSE;  
647.   while(current != end) {   //循环遍历字符串，直到字符串结尾或主动退出循环  
648.    theChar=*current;  
649.    if(theChar) {  //如果字符串存在  
650.      done = (theChar < '0' || theChar> '9') &&  
651.              ((aBase == 16)? (theChar < 'A' || theChar > 'F')&&  
652.                              (theChar < 'a' || theChar > 'f')  
653.                              :PR_TRUE);   //判断是否是0~9，或16进制情况下的A~F  
654.      if(done) {   //如果找到  
655.        AppendUnicodeTo(origin, current, aString); //则将其粘附到aString末尾  
656.        break;     //退出循环  
657.      }  
658.    }  
659.    ++current;  
660.  }  
661.  SetPosition(current);     //同上一个方法一样，主要为进行一些特殊情况的收尾工作  
662.   if (current == end) {  
663.    AppendUnicodeTo(origin, current, aString);  
664.    return kEOF;  
665.  }  
666.   //DoErrTest(aString);  
667.   return result;  
668. }  
669.    
670. //下面的方法ReadWhitespace是让扫描前从当前位置开始，一直读取，直到遇到非空白字符为止。  
671.    
672. /** 
673.  * Consume characters until you find the terminal char 
674.  *  
675.  * @update  gess 3/25/98 
676.  * @param   aString receives new datafrom stream 
677.  * @param   addTerminal tells uswhether to append terminal to aString 
678.  * @return  error code 
679. //注意其中aHaveCR参数和aNewlinesSkipped参数都是需要在本函数体内进行修改的外部变量 
680. nsresultnsScanner::ReadWhitespace(nsScannerSharedSubstring& aString, 
681.                                    PRInt32&aNewlinesSkipped, 
682.                                    PRBool&aHaveCR) { 
683.  //首先将aHaveCR默认设置为FALSE 
684.  aHaveCR = PR_FALSE; 
685.   if (!mSlidingBuffer) {    //对待解析字符串的存在进行判定 
686.    return kEOF; 
687.  } 
688.  //申请一个字符类型变量，默认值为0 
689.  PRUnichar theChar = 0; 
690.  nsresult  result = Peek(theChar);  //查看当前位置的字符 
691.   
692.   if (NS_FAILED(result)) {  //如果查看失败 
693.    return result; //则返回失败结果 
694.  } 
695.   //申请用来存放位置信息的游标 
696.  nsScannerIterator origin, current, end; 
697.  PRBool done = PR_FALSE;   //设置后面循环用到的变量 
698.  //记录几个位置信息 
699.  origin = mCurrentPosition; 
700.  current = origin; 
701.  end = mEndPosition; 
702.   
703.  PRBool haveCR = PR_FALSE;      //申请一个新的内部使用的haveCR变量，默认同样为FALSE 
704.   while(!done && current != end) { 
705.    switch(theChar) { 
706.      case '\n': 
707.      case '\r': 
708.        {     //如果是’\n’或’\r’的情况下 
709.          ++aNewlinesSkipped;    //首先将aNewlinesSkipped加一，因为新的一行开始了 
710.          PRUnichar thePrevChar = theChar;     //记录当前字符 
711.          theChar = (++current != end) ? *current : '\0';    //获取下一个字符，如果是文件末尾了则设置下一个字符为’\0’ 
712.          if ((thePrevChar == '\r' && theChar == '\n') ||    //判断是否是\r\n同时出现 
713.               (thePrevChar == '\n' && theChar == '\r')) { 
714.            //如果是，那么首先判断theChar之后是否是字符串末尾，如果是则设theChar为’\0’ 
715. theChar = (++current != end) ? *current: '\0'; // CRLF ==LFCR => LF 
716. //设置内部的haveCR为TRUE 
717.             haveCR = PR_TRUE; 
718.          } else if(thePrevChar == '\r') {    //如果上一个字符为’\r’ 
719.             // LoneCR becomes CRLF; callers should know to remove extra CRs 
720.             AppendUnicodeTo(origin, current,aString);  //拷贝字符串 
721.            aString.writable().Append(PRUnichar('\n')); //并且需要手动在其之后加上一个’\n’字符 
722.             origin = current; 
723.             haveCR = PR_TRUE; 
724.          } 
725.        } 
726.        break; 
727.      case ' ': 
728.      case '\t': 
729.        theChar = (++current != end) ? *current : '\0'; //遇到其他类型的空白字符，则都需要对其是否为文件末尾做判断 
730.        break; 
731.      default: 
732.        done = PR_TRUE;     //默认情况下即不为空白字符，那么设置done为TRUE 
733.        AppendUnicodeTo(origin, current, aString); //并将目前已解析的这些字符串，注意是从orgin 
734.        break; 
735.    } 
736.  } 
737.   
738.   
739. //下面这个方法和上面的ReadWhiteSpace大同小异 
740.   
741. //XXXbz callers of this haveto manage their lone '\r' themselves if they want 
742. //it to work.  Good thing they're all in view-source and itdeals. 
743. nsresultnsScanner::ReadWhitespace(nsScannerIterator& aStart, 
744.                                   nsScannerIterator& aEnd, 
745.                                    PRInt32&aNewlinesSkipped) { 
746.   if (!mSlidingBuffer) {    //首先对代解析字符串的存在进行判断 
747.    return kEOF; 
748.  } 
749.   PRUnichartheChar = 0;         //申请一个新的变量 
750.  nsresult  result = Peek(theChar);  //获取当前位置的字符 
751.   if (NS_FAILED(result)) {  //如果获取字符失败 
752.    return result;     //返回失败结果 
753.  } 
754.  nsScannerIterator origin, current, end;      //三个用来记录位置的游标 
755.  PRBool done = PR_FALSE;   //设置循环条件 
756.  //初始化这三个游标的位置 
757.  origin = mCurrentPosition; 
758.  current = origin; 
759.  end = mEndPosition; 
760.  //循环查找字符，直到 
761.   while(!done && current != end) { 
762.    switch(theChar) { 
763.      case '\n': 
764.      case '\r':++aNewlinesSkipped; //遇到\n或者\r就将新行数加一 
765.      case ' ': 
766.      case '\t': 
767.        { 
768.          PRUnichar thePrevChar = theChar; 
769.          theChar = (++current != end) ? *current : '\0'; 
770.          if ((thePrevChar == '\r' && theChar == '\n') ||    //同时需要注意处理\n\r紧邻着同时出现的情况 
771.               (thePrevChar == '\n' && theChar == '\r')) { 
772.             theChar = (++current != end) ?*current : '\0'; //CRLF == LFCR => LF 
773.          } 
774.        } 
775.        break; 
776.      default: 
777.        done = PR_TRUE;     //默认情况下就说明找到了非空格字符 
778.        aStart = origin; 
779.        aEnd = current; 
780.        break; 
781.    } 
782.  } 
783.   
784.  SetPosition(current);     //设置当前位置为新位置 
785.   if (current == end) {     //判断是否已到达字符串末尾 
786.    aStart = origin; 
787.    aEnd = current; 
788.    result = kEOF; 
789.  } 
790.   
791.   return result; 
792. } 
793.   
794. //下面这个ReadUntil方法，将会不断地读取字符，直到遇到了一个在给定输入集中出现的字符为止，看过了以上几个方法，相信对于以下这个方法驾轻就熟地就能明白。 
795.   
796. /** 
797.  * Consume characters until you encounter one contained in given 
798.  *  inputset. 
799.  *  
800.  * @update  gess 3/25/98 
801.  * @param   aString will contain theresult of this method 
802.  * @param   aTerminalSet is anordered string that contains 
803.  *          the set of INVALID characters 
804.  * @return  error code 
805.  */  
806. //与以上几个方法不同，这里的参数中多了一个前面解析过的nsReadEndCondition，其中就包含了能够导致读取终止的特殊字符  
807. nsresultnsScanner::ReadUntil(nsAString& aString,  
808.                               const nsReadEndCondition& aEndCondition,  
809.                               PRBooladdTerminal)  
810. {   
811.   if (!mSlidingBuffer) {    //判断待解析的字符串是否为空  
812.    return kEOF;  
813.  }  
814.  //设置两个游标  
815.  nsScannerIterator origin, current;  
816.  //获取特殊字符  
817.   const PRUnichar* setstart = aEndCondition.mChars;  
818.   const PRUnichar* setcurrent;  
819.  //设置两个游标的位置  
820.  origin = mCurrentPosition;  
821.  current = origin;  
822.    
823.  PRUnichar         theChar=0;  
824.  nsresult         result=Peek(theChar);      //获取当前位置的字符  
825.   if (NS_FAILED(result)) {  //如果获取字符失败  
826.    return result;  
827.  }  
828.    
829.   while (current != mEndPosition) {       //循环，直到字符串末尾  
830.    theChar = *current;     //获取当亲字符  
831.    if (theChar == '\0'){  //如果当前位置是空字符’\0’  
832.      ReplaceCharacter(current, sInvalid);     //用替换字符对其进行替换  
833.      theChar = sInvalid;   //并且获取替换后的字符  
834. }  
835.    
836.    // Filter out completely wrong characters  
837.    // Check if all bits are in the required area  
838. if(!(theChar & aEndCondition.mFilter)){  
839. //首先进行一下粗略的检查过滤，过滤掉大部分肯定是错误的字符，使用的就是前面aEndCondition构造方法中提到过的mFilter,通过位与的方法进行判断和处理，这主要应当是为了提高当aEndCondition很大时的处理效率  
840.      // They were. Do a thorough check.  
841.       //如果到了这里，那么就说明它很有可能是aEndCondition中的字符之一  
842.      setcurrent = setstart;  
843.      while (*setcurrent) {  
844.        if (*setcurrent == theChar) {     //判断是否是特殊字符  
845.          if(addTerminal)   //参数传递过来的标示位，是否需要将该特殊字符也添加到读取结果字符串中  
846.             ++current;  
847.          AppendUnicodeTo(origin, current, aString);    //粘贴字符串  
848.          SetPosition(current);  //设置当前位置为新位置  
849.          //DoErrTest(aString);  
850.          return NS_OK;  
851.        }  
852.        ++setcurrent;  //获取下一个aEndCondition中的字符  
853.      }  
854.    }  
855.    ++current;     //比较源字符串中的下一个字符  
856.  }  
857.   // If we are here, we didn't find any terminator in thestring and  
858.   // current = mEndPosition  
859.   //如果到达了这里，说明我们已经到达了字符串的末尾，并且没有遇到特殊字符  
860.  SetPosition(current);  
861.  AppendUnicodeTo(origin, current, aString);  
862.   return kEOF;  
863. }  
864.    
865. //下面这个ReadUntil()方法，和前面的方法唯一的区别就在于，其参数中使用的不是普通的String，而是nsScannerSharedSubString()，其他的和上面的方法一样，我们就不详细解析了，留给读者自己去理解。  
866.    
867. nsresultnsScanner::ReadUntil(nsScannerSharedSubstring& aString,  
868.                               const nsReadEndCondition& aEndCondition,  
869.                               PRBooladdTerminal)  
870. {   
871.   if (!mSlidingBuffer) {  
872.    return kEOF;  
873.  }  
874.  nsScannerIterator origin, current;  
875.   const PRUnichar* setstart = aEndCondition.mChars;  
876.   const PRUnichar* setcurrent;  
877.  origin = mCurrentPosition;  
878.  current = origin;  
879.  PRUnichar         theChar=0;  
880.  nsresult          result=Peek(theChar);  
881.   if (NS_FAILED(result)) {  
882.    return result;  
883.  }  
884.   while (current != mEndPosition) {  
885.    theChar = *current;  
886.    if (theChar == '\0'){  
887.      ReplaceCharacter(current, sInvalid);  
888.      theChar = sInvalid;  
889. }  
890.    // Filter out completely wrong characters  
891.    // Check if all bits are in the required area  
892.    if(!(theChar &aEndCondition.mFilter)) {  
893.      // They were. Do a thorough check.  
894.      setcurrent = setstart;  
895.      while (*setcurrent) {  
896.        if (*setcurrent == theChar) {  
897.          if(addTerminal)  
898.             ++current;  
899.          AppendUnicodeTo(origin, current, aString);  
900.          SetPosition(current);  
901.          //DoErrTest(aString);  
902.          return NS_OK;  
903.        }  
904.        ++setcurrent;  
905.      }  
906.    }  
907.    ++current;  
908.  }  
909.  // If we are here, we didn't find any terminatorin the string and  
910.   // current = mEndPosition  
911.  SetPosition(current);  
912.  AppendUnicodeTo(origin, current, aString);  
913.   return kEOF;  
914. }  
915.    
916. //下面这个仍然是ReadUntil()方法，和前面唯一的区别就在于参数中多了两个参数aStart和aEnd，我们需要在读取的时候对这两个函数外部变量进行赋值，其中aStart实际上就是mCurrentPosition(几乎没有变化？)，aEnd标示了读取结束的位置，这个我们同样交给读者去理解。  
917.    
918. /** 
919.  * Consumes chars until you see the given terminalChar 
920.  *  
921.  * @update  gess 3/25/98 
922.  * @param   
923.  * @return  error code 
924.  */  
925. nsresult nsScanner::ReadUntil(nsAString&aString,  
926.                               PRUnicharaTerminalChar,  
927.                               PRBooladdTerminal)  
928. {  
929.   if (!mSlidingBuffer) {  
930.    return kEOF;  
931.  }  
932.    
933.  nsScannerIterator origin, current;  
934.  origin = mCurrentPosition;  
935.  current = origin;  
936.  PRUnichar theChar;  
937.  nsresult result = Peek(theChar);  
938.    
939.   if (NS_FAILED(result)) {  
940.    return result;  
941.  }  
942.    
943.   while (current != mEndPosition) {  
944.    theChar = *current;  
945.    if (theChar == '\0'){  
946.      ReplaceCharacter(current, sInvalid);  
947.      theChar = sInvalid;  
948.    }  
949.    
950.    if (aTerminalChar == theChar) {  
951.      if(addTerminal)  
952.        ++current;  
953.      AppendUnicodeTo(origin, current, aString);  
954.      SetPosition(current);  
955.      return NS_OK;  
956.    }  
957.    ++current;  
958.  }  
959.    
960.   // If we are here, we didn't find any terminator in thestring and  
961.   // current = mEndPosition  
962.  AppendUnicodeTo(origin, current, aString);  
963.  SetPosition(current);  
964.   return kEOF;  
965.    
966. }  
967.    
968. //下面，是几个提供支持的简单的方法：  
969.    
970. voidnsScanner::BindSubstring(nsScannerSubstring& aSubstring, const nsScannerIterator& aStart, const nsScannerIterator& aEnd)  
971. {  
972.   //获取mSlidingBuffer，赋值到aSubstring中去，同时要为其传递mStart，和mEnd，以及计算一些如length等参数  
973.  aSubstring.Rebind(*mSlidingBuffer, aStart, aEnd);  
974. }  
975.    
976. voidnsScanner::CurrentPosition(nsScannerIterator& aPosition)  
977. {  
978.  //获取mCurrentPosition  
979.  aPosition = mCurrentPosition;  
980. }  
981.    
982. voidnsScanner::EndReading(nsScannerIterator& aPosition)  
983. {  
984.  //获取mEndPosition  
985.  aPosition = mEndPosition;  
986. }  
987.    
988. //接下来的这个SetPosition()方法前面用到过很多次，主要是为了强制重新设置mCurrentPosition的，同时要做好一些相关的处理工作，如重新计算mCountRemaining，所剩未解析的字节数等。  
989.    
990. voidnsScanner::SetPosition(nsScannerIterator& aPosition, PRBool aTerminate,PRBool aReverse)  
991. {  
992.   if (mSlidingBuffer) {     //首先对未解析字符串的存在进行判定  
993. #ifdefDEBUG  
994.     PRUint32 origRemaining = mCountRemaining;  
995. #endif  
996. if (aReverse) {     //需要通过参数来判断新位置是在当前位置之前还是之后  
997.  //如果是在之前，则当前所剩字节需要加上偏移距离  
998.      mCountRemaining += (Distance(aPosition, mCurrentPosition));  
999.    }  
1000.    else {    //反之就是在之后，需要减去偏移距离  
1001.      mCountRemaining -= (Distance(mCurrentPosition, aPosition));  
1002.    }  
1003.      //下面这个是为了小心而对上面操作所做的一个检测  
1004.    NS_ASSERTION((mCountRemaining >= origRemaining && aReverse)||     
1005.                  (mCountRemaining <=origRemaining && !aReverse),  
1006.                  "Improperuse of nsScanner::SetPosition. Make sure to set the"  
1007.                  "aReverse parameter correctly");  
1008.      //设置当前位置为新位置  
1009.    mCurrentPosition = aPosition;  
1010.    if (aTerminate &&(mCurrentPosition == mEndPosition)) {  //如果当前已经到了字符串结尾，并且相应的aTerminate标示位被设置为TRUE  
1011.      mMarkPosition = mCurrentPosition;   //记录一下当前位置  
1012.      mSlidingBuffer->DiscardPrefix(mCurrentPosition);  //删除当前位置之前的所有字符  
1013.    }  
1014.  }  
1015. }  
1016.    
1017. //下面的方法是用来对非法字符等进行替换的方法。  
1018.    
1019. voidnsScanner::ReplaceCharacter(nsScannerIterator& aPosition,  
1020.                                  PRUnicharaChar)  
1021. {  
1022.   if (mSlidingBuffer) {     //如果当前待解析字符串存在  
1023.    mSlidingBuffer->ReplaceCharacter(aPosition, aChar); //直接对aPosition位置的字符进行替换  
1024.  }  
1025. }  
1026.    
1027.    
1028. //下面这个AppendToBuffer是前面的那个Append所调用的，进行实际粘贴操作的方法。  
1029.    
1030. PRBoolnsScanner::AppendToBuffer(nsScannerString::Buffer* aBuf,  
1031.                                  nsIRequest *aRequest,  
1032.                                  PRInt32aErrorPos)  
1033. {  
1034.   //首先调用mParser的DataAdded通知Parser新的数据到达了  
1035.   if (nsParser::sParserDataListeners && mParser&&  
1036.      NS_FAILED(mParser->DataAdded(Substring(aBuf->DataStart(),  
1037.                                             aBuf->DataEnd()), aRequest))) {  
1038. // Don't actually append on failure.  
1039. //如果失败了，那么直接将字符串至为空  
1040.    return mSlidingBuffer != nsnull;  
1041.  }  
1042.    
1043.   if (!mSlidingBuffer) {    //如果字符串为空的情况下  
1044.    mSlidingBuffer = newnsScannerString(aBuf);    //使用aBuf初始化其为一个新的字符串  
1045.    if (!mSlidingBuffer)    //如果初始化失败  
1046.      return PR_FALSE;      //返回错误值，这里怎么不报那个NS_OUTOFMEMORY错误了？  
1047.    mSlidingBuffer->BeginReading(mCurrentPosition);     //获取字符串的读取当前位置，即起始位置  
1048.    mMarkPosition = mCurrentPosition;     //标记一下当前位置  
1049.    mSlidingBuffer->EndReading(mEndPosition);  //获取结束位置  
1050.    mCountRemaining = aBuf->DataLength();      //获取aBuf的长度  
1051.  }  
1052.   else {  
1053.    mSlidingBuffer->AppendBuffer(aBuf);   //其他情况下，说明当前待解析的字符串不为空，我们需要将aBuf放到该字符串之后  
1054.    if (mCurrentPosition == mEndPosition) {    //判断，如果当前位置是原始字符串的末尾  
1055.      mSlidingBuffer->BeginReading(mCurrentPosition);   //设置新的当前位置，因为我们新增了内容  
1056.    }  
1057.    mSlidingBuffer->EndReading(mEndPosition);  //设置新的结束位置，同样因为有新增内容  
1058.    mCountRemaining += aBuf->DataLength();     //增加剩余字节的数量  
1059.  }  
1060.    
1061.    
1062.   if (aErrorPos != -1 && !mHasInvalidCharacter){  //同时，要对非法字符进行处理，做判断，如果原始字符串中没有非法字符，而新增加的字符串中有非法字符  
1063.    mHasInvalidCharacter = PR_TRUE;  //那么我们需要设置新的非法字符标志位  
1064.    mFirstInvalidPosition = mCurrentPosition;      //改变新的非法字符位置  
1065.    mFirstInvalidPosition.advance(aErrorPos);      //设置该位置为当前位置前进aErrorPos偏移距离后的位置  
1066.  }  
1067.    
1068.   if (mFirstNonWhitespacePosition == -1) {         //同时需要对第一个非空白字符标示位进行修改，判断，如果原始的字符串中全部都是空白字符  
1069.    nsScannerIterator iter(mCurrentPosition);  //那么设置两个游标iter和end  
1070.    nsScannerIterator end(mEndPosition);  
1071.    
1072.    while (iter != end) {   //循环遍历新增加的那段字符串  
1073.      if (!nsCRT::IsAsciiSpace(*iter)) {  //判断当前字符如果是非空字符  
1074.        mFirstNonWhitespacePosition = Distance(mCurrentPosition, iter);    //那么设置第一个非空白字符标示位为起始地址+当前偏移地址（此处我怎么觉得这么别扭？不过貌似没错）  
1075.        break;  
1076.      }  
1077.      ++iter; //将游标前进至下一个字符  
1078.    }  
1079.  }  
1080.   return PR_TRUE;  
1081. }  
1082.    
1083. //下面的方法，是在Parser中，以及一些nsScanner的调用体中经常用到的方法，该将未使用的字符串拷贝出去，以便在下一次解析过程中再进行使用，相当于对分步解析过程的支持。  
1084.    
1085. /** 
1086.  *  callthis to copy bytes out of the scanner that have not yet been consumed 
1087.  *  bythe tokenization process. 
1088.  *  
1089.  *  @update  gess 5/12/98 
1090.  * @param   aCopyBuffer is where thescanner buffer will be copied to 
1091.  * @return  nada 
1092.  */  
1093. voidnsScanner::CopyUnusedData(nsString& aCopyBuffer) {  
1094.   if (!mSlidingBuffer) {         //首先得判断解析字符串是否存在  
1095.    aCopyBuffer.Truncate();      //如果不存在或者为0值，直接清空并返回空值  
1096.    return;  
1097.  }  
1098.  //设置两个游标  
1099.  nsScannerIterator start, end;  
1100.  start = mCurrentPosition;  
1101.  end = mEndPosition;  
1102.  //将当前未解析的字节拷贝出去，终于知道为什么设置mCurrentPosition和mEndPosition了  
1103.  CopyUnicodeTo(start, end, aCopyBuffer);  
1104. }  
1105.    
1106.    
1107. //之后还有几个无关紧要的小方法，读者自己看一看就明白了，特别简单。  
1108.    
1109. /** 
1110.  * Retrieve the name of the file that the scanner is reading from. 
1111.  *  Insome cases, it's just a given name, because the scanner isn't 
1112.  * really reading from a file. 
1113.  *  
1114.  * @update  gess 5/12/98 
1115.  * @return  
1116.  */  
1117. nsString& nsScanner::GetFilename(void) {  //这个filename基本没用  
1118.   return mFilename;  
1119. }  
1120.    
1121.    
1122. /** 
1123.  * Conduct self test. Actually, selftesting for this class 
1124.  * occurs in the parser selftest. 
1125.  *  
1126.  * @update  gess 3/25/98 
1127.  * @param   
1128.  * @return  
1129.  */  
1130.    
1131. voidnsScanner::SelfTest(void) {     //空方法，期待后来人编写  
1132. #ifdef_DEBUG  
1133. #endif  
1134. }  
1135.    
1136. voidnsScanner::OverrideReplacementCharacter(PRUnichar aReplacementCharacter)  
1137. {             //重设新的非法字符替换字符  
1138.  mReplacementCharacter = aReplacementCharacter;  
1139.    
1140.   if (mHasInvalidCharacter) {  
1141.    ReplaceCharacter(mFirstInvalidPosition, mReplacementCharacter);  
1142.  }  
1143. }  

  

 后续:Mozilla Firefox Gecko内核源代码解析(4.nsHTMLTokens)