From e0a64208b27e815ec7156dd750d2d7fdce8a917e Mon Sep 17 00:00:00 2001 From: icedream Date: Thu, 11 Dec 2014 02:48:31 +0100 Subject: [PATCH] More documentation and overriding. --- src/addoncreator/Addon/AddonFileInfo.cs | 10 ++++++ src/addoncreator/Addon/AddonJson.cs | 36 +++++++++++++++++++ src/addoncreator/Addon/AddonWhitelist.cs | 11 ++++++ src/addoncreator/Addon/JsonAddonFileInfo.cs | 11 ++++++ .../Addon/PhysicalAddonFileInfo.cs | 26 ++++++++++++-- .../Addon/SegmentedAddonFileInfo.cs | 22 +++++++++++- src/addoncreator/Extensions.cs | 17 +++++++++ 7 files changed, 130 insertions(+), 3 deletions(-) diff --git a/src/addoncreator/Addon/AddonFileInfo.cs b/src/addoncreator/Addon/AddonFileInfo.cs index 8099322..b354742 100644 --- a/src/addoncreator/Addon/AddonFileInfo.cs +++ b/src/addoncreator/Addon/AddonFileInfo.cs @@ -7,16 +7,26 @@ namespace GarrysMod.AddonCreator.Addon private int? _hash; private long? _size; + /// + /// The file size. + /// public virtual long Size { get { return _size.HasValue ? _size.Value : (_size = GetContents().Length).Value; } } + /// + /// The CRC32 hash of this file. + /// public virtual int Crc32Hash { get { return _hash.HasValue ? _hash.Value : (_hash = ParallelCRC.Compute(GetContents())).Value; } } + /// + /// Reads all contents of this file and returns it as a byte array. + /// + /// Byte array of the file content public abstract byte[] GetContents(); } } \ No newline at end of file diff --git a/src/addoncreator/Addon/AddonJson.cs b/src/addoncreator/Addon/AddonJson.cs index 25f5630..c3df480 100644 --- a/src/addoncreator/Addon/AddonJson.cs +++ b/src/addoncreator/Addon/AddonJson.cs @@ -6,34 +6,64 @@ using Newtonsoft.Json; namespace GarrysMod.AddonCreator.Addon { + /// + /// Represents information about an addon. + /// public class AddonJson { + /// + /// Creates an instance of . + /// public AddonJson() { Version = 1; } + /// + /// The title of the addon. + /// [JsonProperty("title", NullValueHandling = NullValueHandling.Ignore)] public string Title { get; set; } + /// + /// A description of the addon. + /// [JsonProperty("description")] public string Description { get; set; } + /// + /// The type of the addon. + /// [JsonProperty("type")] public string Type { get; set; } + /// + /// The assigned tags of the addon. + /// [JsonProperty("tags")] public List Tags { get; set; } + /// + /// A list of patterns of files to ignore when exporting the addon. + /// [JsonProperty("ignore", NullValueHandling = NullValueHandling.Ignore)] public List Ignores { get; set; } + /// + /// The addon's version. + /// [JsonProperty("version")] public int Version { get; set; } + /// + /// The author of the addon. + /// [JsonProperty("author")] public string Author { get; set; } + /// + /// Validates the addon information for mistakes. This includes missing/empty title, missing/empty/invalid description and if the type is missing/empty. + /// internal void CheckForErrors() { if (string.IsNullOrEmpty(Title)) @@ -50,8 +80,14 @@ namespace GarrysMod.AddonCreator.Addon { throw new MissingFieldException("Type is empty or not specified."); } + + // TODO: Validate tags using a predefined list. } + /// + /// Removes files matching any of the ignore patterns from a prepared file dictionary. + /// + /// The file dictionary to scan for files to remove public void RemoveIgnoredFiles(ref Dictionary files) { foreach (var key in files.Keys.ToArray()) diff --git a/src/addoncreator/Addon/AddonWhitelist.cs b/src/addoncreator/Addon/AddonWhitelist.cs index 3bb3e1c..f359ae6 100644 --- a/src/addoncreator/Addon/AddonWhitelist.cs +++ b/src/addoncreator/Addon/AddonWhitelist.cs @@ -4,8 +4,14 @@ using System.Text.RegularExpressions; namespace GarrysMod.AddonCreator.Addon { + /// + /// Handles file whitelisting. + /// public static class AddonWhitelist { + /// + /// Contains all allowed file patterns. + /// private static readonly string[] Whitelist = { "addon.json", @@ -77,6 +83,11 @@ namespace GarrysMod.AddonCreator.Addon _regularExpressions = Whitelist.Select(w => w.WildcardRegex()).ToArray(); } + /// + /// Scans a list of file paths for files which are not whitelisted and returns the found file paths. + /// + /// The list of file paths to scan + /// Found files which are not whitelisted public static IEnumerable FindBlacklistedFiles(IEnumerable files) { ConvertWhitelist(); diff --git a/src/addoncreator/Addon/JsonAddonFileInfo.cs b/src/addoncreator/Addon/JsonAddonFileInfo.cs index 2ecacd9..15005ea 100644 --- a/src/addoncreator/Addon/JsonAddonFileInfo.cs +++ b/src/addoncreator/Addon/JsonAddonFileInfo.cs @@ -3,15 +3,26 @@ using Newtonsoft.Json; namespace GarrysMod.AddonCreator.Addon { + /// + /// Represents a JSON-serialized object, prepared for inclusion in instances. + /// public class JsonAddonFileInfo : AddonFileInfo { private readonly byte[] _serializedJson; + /// + /// JSON-serializes a given object using UTF-8 encoding. + /// + /// The object to serialize public JsonAddonFileInfo(object obj) { _serializedJson = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(obj)); } + /// + /// Returns the serialized object as a byte array. + /// + /// public override byte[] GetContents() { return _serializedJson; diff --git a/src/addoncreator/Addon/PhysicalAddonFileInfo.cs b/src/addoncreator/Addon/PhysicalAddonFileInfo.cs index 9301d9d..a75f519 100644 --- a/src/addoncreator/Addon/PhysicalAddonFileInfo.cs +++ b/src/addoncreator/Addon/PhysicalAddonFileInfo.cs @@ -2,20 +2,42 @@ namespace GarrysMod.AddonCreator.Addon { + /// + /// Represents an addon file which exists on the harddisk as a separate file. + /// public class PhysicalAddonFileInfo : AddonFileInfo { private readonly FileInfo _fi; - public PhysicalAddonFileInfo(string path) + /// + /// Creates an instance of from a given file path. + /// + /// The file path + public PhysicalAddonFileInfo(string path) : this(new FileInfo(path)) { - _fi = new FileInfo(path); } + /// + /// Creates an instance of from given file information. + /// + /// The file info instance + public PhysicalAddonFileInfo(FileInfo file) + { + _fi = file; + } + + /// + /// The size of the file. + /// public override long Size { get { return _fi.Length; } } + /// + /// Returns the file contents as a byte array. + /// + /// A byte array of the file content public override byte[] GetContents() { return File.ReadAllBytes(_fi.FullName); diff --git a/src/addoncreator/Addon/SegmentedAddonFileInfo.cs b/src/addoncreator/Addon/SegmentedAddonFileInfo.cs index c1e473c..2f87cc9 100644 --- a/src/addoncreator/Addon/SegmentedAddonFileInfo.cs +++ b/src/addoncreator/Addon/SegmentedAddonFileInfo.cs @@ -3,6 +3,9 @@ using System.IO; namespace GarrysMod.AddonCreator.Addon { + /// + /// Represents an imported segment from another file. + /// public class SegmentedAddonFileInfo : AddonFileInfo { private readonly int _hash; @@ -10,7 +13,14 @@ namespace GarrysMod.AddonCreator.Addon private readonly long _pos; private readonly Stream _stream; - public SegmentedAddonFileInfo(Stream stream, long pos, long len, int fileHash) + /// + /// Constructs an instance of using the given parameters. + /// + /// The source stream from which to extract the file segment + /// The offset from which to start reading + /// The length of the segment to read + /// The CRC32 of the segment to read + internal SegmentedAddonFileInfo(Stream stream, long pos, long len, int fileHash) { _stream = stream; _pos = pos; @@ -18,16 +28,26 @@ namespace GarrysMod.AddonCreator.Addon _hash = fileHash; } + /// + /// The file segment size. + /// public override long Size { get { return _len; } } + /// + /// The file segment's CRC32 hash. + /// public override int Crc32Hash { get { return _hash; } } + /// + /// Reads the complete segment and returns the content as a byte array. + /// + /// The content of the file segment public override byte[] GetContents() { lock (_stream) diff --git a/src/addoncreator/Extensions.cs b/src/addoncreator/Extensions.cs index 8bf5c75..90c42b0 100644 --- a/src/addoncreator/Extensions.cs +++ b/src/addoncreator/Extensions.cs @@ -6,6 +6,11 @@ namespace GarrysMod.AddonCreator { internal static class Extensions { + /// + /// Generates a regular expression from a wildcard. + /// + /// The wildcard pattern + /// A regular expression of the given pattern public static Regex WildcardRegex(this string pattern) { return new Regex("^" + Regex.Escape(pattern) @@ -14,6 +19,12 @@ namespace GarrysMod.AddonCreator + "$"); } + /// + /// Reads a string. If nullTerminated is true, this will not use native string reading but reads until a NULL char is found. + /// + /// The binary reader instance + /// Use null-terminated reading instead of native string reading + /// The read string public static string ReadString(this BinaryReader br, bool nullTerminated) { if (!nullTerminated) @@ -30,6 +41,12 @@ namespace GarrysMod.AddonCreator return sb.ToString(); } + /// + /// Writes a string. If nullTerminated is true, the string will not be written using native string writing but without length prefix and with NULL char termination instead. + /// + /// The binary writer instance + /// The string to write + /// Use null-terminated writing instead of native string writing public static void Write(this BinaryWriter bw, string value, bool nullTerminated) { if (!nullTerminated)