Merge pull request #3 from Garen-Wang/collab

add comments, update readme

README.md

@@ -6,13 +6,15 @@ Pie (abbr. Pie Is an Editor) is a cross-platform text editor, intended to be fas
 
 ## Features
 
-- graphical user interface
+- SOTA inner text representation
 
-- modal editing
+- Graphical user interface
 
-- syntax highlighting
+- Easy-to-use modal editing
 
-- configurable
+- Semantic syntax highlighting
+
+- Configurable
 
 ## Usage
 
@@ -79,14 +81,15 @@ If you would like to change the system default font to your favorite one like Sa
 
 ### Windows
 
-1. Download the pre-built version of Pie.
+1. Download the pre-built Windows version of Pie.
 2. Extract the archive.
 3. Run `pie.exe`.
 
 ### Linux
 
-1. Download the Appimage of Pie.
-2. Run `pie-x86_64.Appimage`.
+1. Download the pre-built Linux version of Pie.
+2. Extract the archive.
+3. Run `pie`.
 
 ### Build from Source
 
@@ -95,6 +98,11 @@ If you would like to change the system default font to your favorite one like Sa
 3. Copy `shl` and `test` to the source root of the build directory.
 4. Run the executable.
 
+## Collaborators
+
+- Qing Liu, a.k.a [guest0x0](https://github.com/guest0x0)
+- Xiankai Miao
+
 ## License
 
 The repository is under WTFPL.

include/pierc/pierc.h

@@ -5,16 +5,22 @@
 #include <QFont>
 
 namespace pierc {
+    /* a special type of parser, only used to parse .pierc */
     typedef peg_parser::ParserGenerator<std::string> ConfigParser;
 
+    /* store the name of the font */
     extern std::string fontName;
+
+    /* store the size of the font */
     extern int fontSize;
 
+    /* configure the parser after initialization */
     void config(ConfigParser &parser);
 
-    // can use only once at the beginning when pie starts execution
+    /* used only once at the beginning when pie starts its execution */
     void gatherInfo();
 
+    /* retrieve the font family in format of *QFont* */
     QFont getFont();
 }// namespace pierc
 

include/shl/builtin.h

@@ -19,12 +19,14 @@
 using Attr = Style;
 
 namespace shl {
+    /* types of languages under syntax highlighting support */
     enum class LanguageType {
         CPP,
         JAVA,
         PYTHON,
     };
 
+    /* a pair of syntax highlighting message, including indexes and corresponding style attributes */
     class SyntaxHighlightInfo {
       public:
         mutable int idx = 0;
@@ -33,51 +35,65 @@ namespace shl {
         explicit SyntaxHighlightInfo(int idx, Attr attr);
     };
 
+    /* act as the return type of each semantic action */
     typedef std::vector<SyntaxHighlightInfo> SyntaxHighlightInfos;
     using Parser = peg_parser::ParserGenerator<std::string>;
     using ParserBuilder = peg_parser::ParserGenerator<std::shared_ptr<SyntaxHighlightInfos>, Parser &>;
 
     class Colors {
       private:
-        // not wise to use *unordered_set* here, try *unordered_map*
+        /* map color names to corresponding QFont objects */
         std::unordered_map<std::string, QColor> colors;
 
       public:
-        // get expression for PEG parser grammar
+        // get expression in parsing expression grammar
         std::string getExpr();
-        // hope all string in `colors` are lowercase
+        // all strings in `colors` are expected to be lowercase
         void append(const std::string &color, const QColor &_color);
         bool exist(const std::string &str);
         QColor get(const std::string &str);
     };
 
+    /* return a ParserBuilder that have finished configuration */
     ParserBuilder *generateParserBuilder(Colors &colors, Rope *);
 
+    /* check all colors under support */
     Colors getPredefinedColors();
 
+    /* receive path of shl file, return a parser generated according to the grammar of shl file */
     std::pair<bool, Parser> generateParserFromSHL(const std::string &filename, Rope *rope);
 
+    /* the initial configuration to a new ParserBuilder */
     void initParserBuilder(ParserBuilder &g, Colors &colors, Rope *, bool render = false);
 
-    extern std::vector<int> indentDepth;
-
-    extern std::vector<std::pair<int, int>> blockRecords;
+    /* debug messages when indent-aware feature is enable */
+    extern std::vector<int> indentDepth; // elements are the number of spaces as indent
+    extern std::vector<std::pair<int, int>> blockRecords; // record the beginning and the end line of an indent block
 
+    /* teach a ParserBuilder about the grammar of Syntax Highlighting Language */
     void initSHLGrammar(ParserBuilder &g);
 
+    /* find out the positional interval in text, from which line to which line */
     std::pair<long, long> getLineNumber(std::string_view input, std::pair<int, int> blockRecord);
 
+    /* return the real index described in shl language, given the size */
     int getIdx(const std::string &str, int size);
 
+    /* check if all the letters in the string are lowercase */
     bool isLowercase(const std::string &str);
 
+    /* generate the corresponding language parser */
+    /* user can directly invoke this API to get the final parser */
     std::pair<bool, shl::Parser> generateLanguageParser(LanguageType languageType, Rope *);
 }// namespace shl
 
+/* FilePath is designed to make file path experience consistent across Windows and Linux,
+ * without hardcoding the whole path */
 class FilePath {
   private:
     std::string pathString; // stores the actual path on different system
 
+    /* get separator, determined in runtime */
     const static char _separator = 
 #if defined _WIN32 || defined __CYGWIN__
       '\\';
@@ -86,10 +102,12 @@ class FilePath {
 #endif
 
   public:
+    /* allow multiple strings as arguments */
     explicit FilePath(int n_args, ...);
 
     ~FilePath() = default;
 
+    /* reconstruct the path if the path needs to modifying */
     static std::string constructFileString(int n_args, ...);
 
     std::string getPathString() const;