importsort-d

commit a5280797420210554540cfa26a89b2098cede2ab
parent 42d01e4e2dc77238d348567a43c5bc4930aac9ab
Author: Friedel Schoen <[email protected]>
Date:   Sun, 23 Oct 2022 15:51:43 +0200

added documentation

Diffstat:
M
src/main.d
 | 
9
++++++++-
M
src/sort.d
 | 
46
+++++++++++++++++++++++++++++++++++++++++-----

2 files changed, 49 insertions(+), 6 deletions(-)
diff --git a/src/main.d b/src/main.d
@@ -11,12 +11,18 @@ import std.functional : unaryFun;
 import std.stdio : File, stderr, stdin, stdout;
 import std.string : endsWith;
 
+/// name of binary (for help)
 enum BINARY = "importsort-d";
-enum VERSION = "0.1.0";
+
+/// current version (and something I always forget to update oops)
+enum VERSION = "0.3.0";
+
+/// the help-message from `help.txt`
 enum HELP = import("help.txt")
 		.replace("{binary}", BINARY)
 		.replace("{version}", VERSION);
 
+/// list entries (`ls`) from all arguments
 DirEntry[] listEntries(alias F = "true")(string[] input, bool recursive) {
 	alias filterFunc = unaryFun!F;
 
@@ -46,6 +52,7 @@ DirEntry[] listEntries(alias F = "true")(string[] input, bool recursive) {
 	return entries;
 }
 
+/// the main-function (nothing to explain)
 void main(string[] args) {
 	SortConfig config;
 	bool inline;
diff --git a/src/sort.d b/src/sort.d
@@ -11,44 +11,77 @@ import std.string : strip, stripLeft;
 import std.traits : isIterable;
 import std.typecons : Yes;
 
+/// the pattern to determinate a line is an import or not
 enum PATTERN = ctRegex!`^(\s*)(?:(public|static)\s+)?import\s+(?:(\w+)\s*=\s*)?([a-zA-Z._]+)\s*(:\s*\w+(?:\s*=\s*\w+)?(?:\s*,\s*\w+(?:\s*=\s*\w+)?)*)?\s*;[ \t]*([\n\r]*)$`;
 
+/// configuration for sorting imports
 struct SortConfig {
+	/// won't format the line, keep it as-is
 	bool keepLine = false;
+
+	/// sort by attributes (public/static first)
 	bool byAttribute = false;
+
+	/// sort by binding instead of the original
 	bool byBinding = false;
+
+	/// print interesting messages (TODO)
 	bool verbose = false;
+
+	/// merges imports of the same source
 	bool merge = false;
 }
 
+/// helper-struct for identifiers and its bindings
 struct Identifier {
+	/// SortConfig::byBinding
 	bool byBinding;
+
+	/// the original e. g. 'std.stdio'
 	string original;
+
+	/// the binding (alias) e. g. 'io = std.stdio'
 	string binding;
 
+	/// wether this import has a binding or not
+	@property
+	bool hasBinding() {
+		return binding != null;
+	}
+
+	/// the string to sort
 	string sortBy() {
 		if (byBinding)
 			return hasBinding ? binding : original;
 		else
 			return original;
 	}
-
-	bool hasBinding() {
-		return binding != null;
-	}
 }
 
+/// the import statement description
 struct Import {
+	/// SortConfig::byAttribute
 	bool byAttribute;
+
+	/// the original line (is `null` if merges)
 	string line;
 
+	/// is a public-import
 	bool public_;
+
+	/// is a static-import
 	bool static_;
+
+	/// origin of the import e. g. `import std.stdio : ...;`
 	Identifier name;
+
+	/// symbols of the import e. g. `import ... : File, stderr, in = stdin;`
 	Identifier[] idents;
+
+	/// spaces before the import (indentation)
 	string begin;
-	string end;
 
+	/// the string to sort
 	string sortBy() {
 		if (byAttribute && (public_ || static_))
 			return '\0' ~ name.sortBy;
@@ -56,6 +89,7 @@ struct Import {
 	}
 }
 
+/// write import-statements to `outfile` with `config`
 void writeImports(File outfile, SortConfig config, Import[] matches) {
 	if (!matches)
 		return;
@@ -107,6 +141,7 @@ void writeImports(File outfile, SortConfig config, Import[] matches) {
 	}
 }
 
+/// sort imports of an entry (file) (entries: DirEntry[])
 void sortImports(alias P = "true", R)(R entries, SortConfig config)
 		if (isIterable!R && is(ElementType!R == DirEntry)) {
 	alias postFunc = unaryFun!P;
@@ -129,6 +164,7 @@ void sortImports(alias P = "true", R)(R entries, SortConfig config)
 	}
 }
 
+/// raw-implementation of sort file (infile -> outfile)
 void sortImports(File infile, File outfile, SortConfig config) {
 	string softEnd = null;
 	Import[] matches;