You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/HACKING.md
+22-22Lines changed: 22 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -7,86 +7,86 @@ This file contains the details of the program's execution in stages.
7
7
8
8
The user invokes the program as the following: `lua-format [options] <scripts>`
9
9
10
-
At first the program does is to parse the command line options and raise any errors if needed.
10
+
At first, the program does is to parse the command line options and raise any errors if needed.
11
11
12
12
*`options` are parsed by the 3rd party library [args](https://github.com/Taywee/args)
13
13
14
-
Now the program reads the configuration files. There are a couple of _known_ locations the program will check for configuration files, if **no** file is specified in the command line.
14
+
Now the program reads the configuration files. There are a couple of _known_ locations the program will check for configuration files if **no** file is specified in the command line.
In case it doesn't find any suitable file it will fallback to the default values.
21
21
22
-
The default values are hard coded in the program (`Config.cpp`) and are used as fallback whenever possible. For instance when fields are not specified in the user's configuration file.
22
+
The default values are hardcoded in the program (`Config.cpp`) and are used as a fallback whenever possible. For instance when fields are not specified in the user's configuration file.
23
23
24
-
If the program finds the suitable file and has all the required permissions then the file and scripts are passed for formatting. Otherwise raise the error if it doesn't have the required permissions.
24
+
If the program finds the suitable file and has all the required permissions then the file and scripts are passed for formatting. Otherwise, raise the error if it doesn't have the required permissions.
25
25
26
26
If all is well with arguments passing then it shows format success message else it will raise the logic error for the arguments passing.
27
27
28
28
## Configuration loading
29
29
30
-
The program is hard coded with a default value for every field of the configuration in `config.cpp`.
30
+
The program is hardcoded with a default value for every field of the configuration in `config.cpp`.
31
31
32
32
The program uses the 3rd party library [yaml-cpp](https://github.com/jbeder/yaml-cpp) to load the user's configuration file and update the default value of the configuration.
33
33
34
-
The value of each field is updated by picking the configuration field as key and value as their status.
34
+
The value of each field is updated by picking the configuration field as key and value as their status.
35
35
36
-
The function to update the configuration value and read the user configuration file is declared in `config.h`.
36
+
The function to update the configuration value and read the user configuration file is declared in `config.h`.
37
37
38
38
## Implementing formatting features
39
39
40
-
At first the program declares the variables, vectors, and functions to read and write the lines, columns along with operating with newline break in `SourceWriter.h`.
40
+
At first, the program declares the variables, vectors, and functions to read and write the lines, columns along with operating with newline break in `SourceWriter.h`.
41
41
42
42
The program uses the 3rd party library [antrl4](https://github.com/antlr/antlr4) for the token system and making the struct of various functions.
43
43
44
-
The functions for implementing formatting features are declared along with variables and vectors to record the values while formatting in `FormatVisitor.h`..
44
+
The functions for implementing formatting features are declared along with variables and vectors to record the values while formatting in `FormatVisitor.h`.
45
45
46
46
All the formatting features get executed in `FormatVisitor.cpp` according to the configuration values.
47
47
48
-
In function `commentAfter`, the program check the types of the tokens for different types of formatting and returns the string with comments between the attribute passed as ParseTreeNode and nextNode according to conditions.
48
+
In function `commentAfter`, the program checks the types of the tokens for different types of formatting and returns the string with comments between the attribute passed as ParseTreeNode and nextNode according to conditions.
49
49
50
50
While in the `commentAfterNewLine`, the program returns the string with comments between two attributes of the node but with a line break. The line break condition is the newlineIndent value which is passed as the next node.
51
51
52
-
Now for storing the lines, functions like `pushWriter`is defined by sourcewriter constructor with the value for initialColumn as 0 and set the volatile to true if the writers_ is not empty. While in `pushWriterWithColumn` all execution is the same except the initialColumn value for Soucewriter constructor is cur_columns value.
52
+
Now for storing the lines, functions like `pushWriter`are defined by sourcewriter constructor with the value for initialColumn as 0 and set the volatile to true if the writers_ is not empty. While in `pushWriterWithColumn` all execution is the same except the initialColumn value for Soucewriter constructor is cur_columns value.
53
53
54
-
When it comes to pop out the values stored in writers_, function `popWriter` is used. Also, after pop up the writers_, the writer is deleted to free up space.
54
+
When it comes to pop out the values stored in writers_, function `popWriter` is used. Also, after pop up the writers_, the writer is deleted to free up space.
55
55
56
56
In the function `fastTestColumnlimit`, it returns a boolean value by comparing the columnLimit value with the configuration value. It checks the type of tokens starting from the firstnode till the last node and then checks the column’s value with column_limit and returns a boolean value.
57
57
58
-
The program uses the `cur_column` for measuring the column length and returns the integer value and uses `cur_writer` to return the last element of the vector `writers_`.
58
+
The program uses the `cur_column` for measuring the column length and returns the integer value and uses `cur_writer` to return the last element of the vector `writers_`.
59
59
60
60
The program uses various types of indentation with tabs and spaces according to the configuration provided.
61
61
* In `string FormatVisitor::indentWithAlign()` if the config value for **use_tab** is true then indent with a tab for indent_ times and with spaces for indenforAlign times and if false then indent with space for indent_+indentforAlign times and return the string.
62
62
63
-
* While in ` string FormatVisitor::indent()`, indent for indent_ times with tab if use_tab is true else indent with space and return the string.
63
+
* While in ` string FormatVisitor::indent()`, indent for indent_ times with tab if use_tab is true else indent with space and return the string.
64
64
65
-
Now whenever indentation requires after newline, the program uses certain functions to increase and decrease the indent.
65
+
Now whenever indentation requires after the newline, the program uses certain functions to increase and decrease the indent.
66
66
* In `incIndent()` indent_ value is increased by **indent_width** of the config value and in `decIndent()` it will decrease by the same value.
67
67
* While in `incContinuationIndent()` and `decContinuationIndent()` indent_ value is increased and decreased by the value of the **continuation_indent_width** in the config respectively.
68
68
69
-
* But for the `incIndentForAlign(int indent)` the value is passed which will be increased in the indentForAlign value and for decrement it will be passed in `decIndentForAlign(int indent)`.
69
+
* But for the `incIndentForAlign(int indent)` the value is passed which will be increased in the indentForAlign value and for decrement, it will be passed in `decIndentForAlign(int indent)`.
70
70
71
-
In `visitChunk(LuaParser::ChunkContext* ctx) `, it visits the block with chop_down_block as true then after checking the newline it returns a string with a newline if a newline is not there.
71
+
In `visitChunk(LuaParser::ChunkContext* ctx) `, it visits the block with chop_down_block as true then after checking the newline it returns a string with a newline if a newline is not there.
72
72
73
73
In `visitBlock(LuaParser::BlockContext* ctx)` the function checks the semi and needComment for the StatContext in LuaParser for each stats. Then corresponding to their bool value if semi is false the function `visitStat` is executed and for needComment it checks the `previousWhiteSpace` with semi value and `lastcharWhiteSpace`. After that if the retstat for tht context is not null then execute function `visitretstat` else set the blockComment to commentAfter with context.
74
74
75
75
In `visitStat(LuaParser::StatContext* ctx)` it checks the chop_down_block value and then applies an operator for indent in the cur_writer and execute `visitChildren` with the StatContext.
76
76
77
77
In `buildFirstArgumentWS` function checks the args LP and front of the context then according to the value of **space_before_call** in config add the spaces.
78
78
79
-
In `visitRetstat(LuaParser::RetstatContext* ctx)` it checks the chop_down_block, explist of the context and then execute the function `visitExplist` with the explist of the retstatContext. Also it checks the semi for the context and apply the operator with text of the semiContext in the cur_writer.
79
+
In `visitRetstat(LuaParser::RetstatContext* ctx)` it checks the chop_down_block, explist of the context and then execute the function `visitExplist` with the explist of the retstatContext. Also, it checks the semi for the context and applies the operator with the text of the semiContext in the cur_writer.
80
80
81
-
In `visitExplist(LuaParser::ExplistContext* ctx)` first it execute the `pushWriterwithcolumn`. Then the visitExp with the front exp of the context and pop the writer is executed. After that it set the beyondlimit value by checking the explength with column_limit and cur_columns but if the lines in the cur_writer are greater than 1 and cur_column is greater than half of column_limit set the beyondlimit to true. Now for the beyond limit execute the corresponding functions and format the part else format by the different specified function call and indentation. Similarly for every index of the context check the beyondlimit and then execute the feature of **alignargs** and corresponding to it set the indentation for newlines.
81
+
In `visitExplist(LuaParser::ExplistContext* ctx)` first it execute the `pushWriterwithcolumn`. Then the visitExp with the front exp of the context and pop the writer is executed. After that, it set the beyondlimit value by checking the explength with column_limit and cur_columns but if the lines in the cur_writer are greater than 1 and cur_column is greater than half of column_limit set the beyondlimit to true. Now for the beyond limit execute the corresponding functions and format the part else format by the different specified function call and indentation. Similarly, for every index of the context check the beyondlimit and then execute the feature of **alignargs** and corresponding to it set the indentation for newlines.
82
82
83
83
In `visitExp(LuaParser::ExpContext* ctx)` there are various checkpoints such as
84
84
* linkoperator, unaryoperator, prefixexp, functiondef, table constructor , string etc.
85
85
* So if the **linkoperator** is not null then execute the visitexp itself for the exp[0] of the context and then check the config for the **break_after_operator** and implement the features according to the standard style by checking beyondlimit and with the column_limit and do the required indentation.
86
86
* For the **unaryoperator** check the text is ‘not" then do the corresponding function otherwise check text for ‘-’ and do the commentAfter according to it.
87
-
* For the **prefixexp** we call `visitprefixexp` for the context of prefixexp, for **functiondef** we call `visitfunctiondef` for the context of functiondef, for **tableconstructor** we call `visitTableconstructor` for the context of tableconstructor, for **string** we call `visitString` for the context of string and for rest apply the operator to the context of the text in cur_writer.
87
+
* For the **prefixexp** we call `visitprefixexp` for the context of prefixexp, for **functiondef** we call `visitfunctiondef` for the context of functiondef, for **tableconstructor** we call `visitTableconstructor` for the context of tableconstructor, for **string** we call `visitString` for the context of string and for rest apply the operator to the context of the text in cur_writer.
88
88
89
-
In `visitString(LuaParser::StringContext* ctx)` the program implement **single_qoute_to_double_qoute** and **double_quote_to_single_quote** features. It starts with checking the normalstring of the context and sets the quote to ‘\’’ or ‘\"’ and later deals with switching to it. After that according to the config it replace the single to double and viceversa.
89
+
In `visitString(LuaParser::StringContext* ctx)` the program implement **single_qoute_to_double_qoute** and **double_quote_to_single_quote** features. It starts with checking the normalstring of the context and sets the quote to ‘\’’ or ‘\"’ and later deals with switching to it. After that according to the config it replaces the single to double and vice-versa.
90
90
91
91
In `visitPrefixexp(LuaParser::PrefixexpContext* ctx)` it start with pushing the false value to chainedMethodCallHasIncIndent_ and chainedMethodCallIsFirst_ and call the function `visitVarOrExp` with varOrExp context and set the string ws to return the value of the function buildFirstArguments with nameAndArgs of the context. The feature of **align_parameter** is implemented by checking the config value for it and executing the buildArguments function for the context of nameAndArgs. At last indent by checking the chainedMethodCallHasIncIndent_.
92
92
@@ -120,4 +120,4 @@ This file contains the details of the program's execution in stages.
120
120
121
121
## Configuration and formatting testing
122
122
123
-
Now at last the program does is to test the all types of feature implementations.In `test_config.cpp` the program test the correct configuration implementation by setting the config value for each field while in `test_format_file.cpp` the program test the expected formatting by passing a lua scripts and configuration file. Later check the formatted scripts with the desired script.
123
+
Now at last the program does is to test all types of feature implementations.In `test_config.cpp` the program test the correct configuration implementation by setting the config value for each field while in `test_format_file.cpp` the program tests the expected formatting by passing a lua script and configuration file. Later check the formatted scripts with the desired script.
0 commit comments