Merge pull request #1 from indrora/complete-api

KaitaiStream: full API + documentation.

KaitaiStream.cs

@@ -3,17 +3,28 @@ using System.IO;
 
 namespace Kaitai
 {
+    ///<summary>
+    /// KaitaiStream is a special stream wrapping a specific set of functionality
+    /// Specifically, it allows (unlike normal Streams) picking the endianness of reads,
+    /// as well as signed/unsigned-ness of read values.
+    ///</summary>
     public class KaitaiStream 
     {
 
         private Stream mStream;
 
 #region Constructors
+        ///<summary>
+        /// Creates a KaitaiStream backed by a file (RO)
+        ///</summary>
         public KaitaiStream(String filename)
         {
             mStream = (Stream)(new FileStream(filename, FileMode.Open));
         }
 
+        ///<summary>
+        ///Creates a KaitaiStream backed by a byte buffer
+        ///</summary>
         public KaitaiStream(byte[] buffer)
         {
             mStream = new MemoryStream(buffer);
@@ -23,21 +34,25 @@ namespace Kaitai
 
 
 #region Raw stream passthru
+        ///<summary>Get the position within the stream</summary>
         public long pos()
         {
             return mStream.Position;
         }
 
+        ///<summary>Seek to a specific position from the beginning of the stream</summary>
         public void seek(long position)
         {
             mStream.Seek(position, SeekOrigin.Begin);
         }
 
+        ///<summary>Return if the current stream is at the end of the stream.</summary>
         public bool isEof()
         {
             return mStream.Position == mStream.Length;
         }
 
+        ///<summary>Read N bytes from the stream.</summary>
         public byte[] readBytes(int n)
         {
             try
@@ -58,6 +73,7 @@ namespace Kaitai
 
 #region Read Byte/SByte
 
+        ///<summary> Read 1 signed byte from the stream</summary>
         public SByte readS1()
         {
             int val = mStream.ReadByte();
@@ -67,6 +83,7 @@ namespace Kaitai
                 return (SByte)val;
         }
 
+        ///<summary>Read 1 unsigned byte fro mthe stream.</summary>
         public byte readU1() 
         { 
             int val = mStream.ReadByte();
@@ -82,11 +99,13 @@ namespace Kaitai
 
 #region 16-bit integers (unsigned)
 
+        ///<summary>Read an unsigned 16-bit integer, little endian from the stream.</summary>
         public UInt16 readU2le() {
             byte[] tmp = new byte[2];
             mStream.Read(tmp, 0, 2);
             return (UInt16)( (tmp[0] << 8)+(tmp[1] << 0) );
         }
+        ///<summary>Read an unsigned 16-bit integer, big endian, from the stream.</summary>
         public UInt16 readU2be() {
             byte[] tmp = new byte[2];
             mStream.Read(tmp, 0, 2);
@@ -96,12 +115,14 @@ namespace Kaitai
 #endregion
 
 #region 16-bit integers (signed)
+        ///<summary> Read a signed 16-bit integer, little endian, from the stream.</summary>
         public Int16 readS2le() {
             byte[] tmp = new byte[2];
             mStream.Read(tmp, 0, 2);
             return (Int16)( (tmp[0] << 8)+(tmp[1] << 0) );
         }
 
+        ///<summary> Read a signed 16-bit integer, big endian, from the stream.</summary>
         public Int16 readS2be() {
             byte[] tmp = new byte[2];
             mStream.Read(tmp, 0, 2);
@@ -114,11 +135,15 @@ namespace Kaitai
 
 #region 4-byte integer reads
 #region 32-bit integers (Unsigned)
+        ///<summary>Read a 32-bit little-endian unsigned integer</summary>
         public UInt32 readU4le() { throw new NotImplementedException(); }
+        ///<summary>Read a 32-bit big-endian unsigned integer</summary>
         public UInt32 readU4be() { throw new NotImplementedException(); }
 #endregion
 #region 32-bit integers (signed)
+        ///<summary>Read a 32-bit little-endian signed integer</summary>
         public UInt32 readS4le() { throw new NotImplementedException(); }
+        ///<summary>Read a 32-bit big-endian signed integer</summary>
         public UInt32 readS4be() { throw new NotImplementedException(); }
 #endregion
 #endregion // 4-byte integer reads
@@ -126,16 +151,20 @@ namespace Kaitai
 
 #region 8-byte integer reads
 #region 64-bit integers (unsigned)
-    public UInt64 readU8le() { throw new NotImplementedException(); }
-    public UInt64 readU8be() { throw new NotImplementedException(); }
+        ///<summary>Read a 64-bit little-endian unsigned integer</summary>
+        public UInt64 readU8le() { throw new NotImplementedException(); }
+        ///<summary>Read a 64-bit big-endian unsigned integer</summary>
+         public UInt64 readU8be() { throw new NotImplementedException(); }
 #endregion
 #region 64-bit integers (signed)
-    public UInt64 readS8le() { throw new NotImplementedException(); }
-    public UInt64 readS8be() { throw new NotImplementedException(); }
+        ///<summary>Read a 64-bit little-endian signed integer</summary>
+        public UInt64 readS8le() { throw new NotImplementedException(); }
+        ///<summary>Read a 64-bit big-endian signed integer</summary>
+        public UInt64 readS8be() { throw new NotImplementedException(); }
 #endregion
 #endregion // 8-byte integer reads 
 
-
+        ///<summary>Read all remaining bytes from the stream.</summary>
         public byte[] readBytesFull()
         {
             long countLong = mStream.Length - mStream.Position;
@@ -146,6 +175,7 @@ namespace Kaitai
             return buffer;
         }
 
+        ///<summary>Read a specific set of bytes, expecting a specific result.</summary>
         public byte[] ensureFixedContents(int len, byte[] expected)
         {
             byte[] buff = readBytes(len);
@@ -161,14 +191,35 @@ namespace Kaitai
 
         }
 
+        ///<summary>Read a string until the end of the stream.</summary>
         public String readStrEos(String encoding)
         {
             System.Text.Encoding _encoding = System.Text.Encoding.GetEncoding(encoding);
             return _encoding.GetString(readBytesFull());
         }
+
+        ///<summary>Read a string from len characters in the specified encoding.</summary>
         public String readStrByteLimit(int len, String encoding)
         {
             throw new NotImplementedException();
         }
+        
+        ///<summary>Read a string in a specific encoding, with a specific terminator, etc.</summary>
+        public String readStrz(String encoding, byte term, bool includeTerm, bool consumeTerm, bool eosError)
+        {
+            throw new NotImplementedException();
+        }
+        
+        ///<summary>Inflate a Zlib block</summary>
+        public byte[] processZlib(byte[] data)
+        {
+            throw new NotImplementedException();
+        }
+        
+        ///<summary>Barrel-rotate</summary>
+        public byte[] processRotateLeft(byte[] data, int amount, int groupSize)
+        {
+            throw new NotImplementedException();
+        }
     }
 }