-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmanual_codetwig.txt
170 lines (109 loc) · 8.27 KB
/
manual_codetwig.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
When reading from Github, press button "Raw" to get line-wrapping.
------------------------------------------------------------------
Welcome to help for CodeTwig
CodeTwig is terminal-program to view source-code and to show procedures as usage-trees or used-by-trees.
Currently only meant for Nim.
All commands follow a certain structure and style:
- Long-style: ctwig projects/someproject.pro --command:somecommand --extrakey1:somevalue --extrakey2:othervalue
- Short-style: ctwig projects/someproject.pro -c:s -k:v -o:x
Currently all commands require a project-definition-path, except for help:
ctwig -h or ctwig --help
As option-separator one can use ':' and '='. Also a brief option-sep exists of none for short options and space for long options. Example short style: ctwig projects/someproject.pro -ct -rb -d4
Below I will list the commands with possible (extra) options in the logical order of use.
All commands are invoked as:
-c or --command
The command-key needs as values the actual commands.
PROJECTS
CodeTwig has its own project-directory "projects" in which you must place your codetwig-projects. It may sound complicated but it is very easy. The starting-point of a project is the project-definition-file. You can copy the template to get started. You rename the copied template to yourproject.pro.
You just have to paste the path to the source-files of your project, and the rest goes (mostly) automatically. You can perform below-standing command to add the source-files programmatically. Just check the results and remove potential backups or earlier versions of your source-files. Off course you can also manually add the source-files.
All codetwig-genererated files are placed in a newly created folder: projects/yourproject
So the folder-name is based on the basename of your project-def-file.
MULTI-PROJECTS
After you have defined some projects in project-files (.pro), since CT 1.5x you can create a multi-project-definition (.mul) that enables you to show more projects at once; for now that is the trees of usage and used-by. (no views, for that you can look at the respective projects). Lateron the source-code-view will be added.
ALL COMMANDS
The commands are to be input in a terminal / powershell. Of course you can use multiple tabs for different tasks. Go to the directory where your ctwig-executable lives and enter one of the following commands.
Where I write ctwig, in some terminals you must input: ./ctwig
-----------------------------------------------------------------------------
-c:a or --command:add_files
no options
Full example:
ctwig projects/yourproject.pro -c:a
After you have copied the project-template, renamed it and adjusted the path to the source-files, you can run above command. The operation adds the names of the source-files (.nim) from the source-path and (since 1.5x) underlying directories to project-def-file (yourproject.pro). You must manually prune backup- or test-files or other .nim-files that you want to exclude from the codetwig-analysis.
------------------------------------------------------------------------------
-c:d or --command:declarations
no options
Full example:
ctwig projects/yourproject.pro -c:d
Running this command will create a list of declarations. Declarations are the various procs, template, macros and functions. The file is not very readable, but will be used to create addtional views. Also it is parsed to generate the proc-trees on the fly. (see later). The list contains:
- declarations (like procs) for all source-files
- declarations that are used in above declarations (these are appended to above line)
The arise of the dec-list happens in three phases, whereby phase 3 is the version that is used by other functions. Since CT 1.5x a field with the project-name is added to enable multi-project trees. (command:combine will tell more on that).
---------------------------------------------------------------------------
-c:v or --command:views
no options
Full example:
ctwig projects/yourproject.pro -c:v
Running this command will create some views of the source-code. Currently four views are available, basic and extended view with one level or two levels. The one-level-files show the source-files and the declarations only (usually mostly procs), and the two-level-files shows the (first-level) usages of each declaration (that is mostly the used procs). The extended ones provide also the parameters of function and the added comment.
So you get:
yourproject_basic_one-level_view.txt
yourproject_basic_two-level_view.txt
yourproject_extended_one-level_view.txt
yourproject_extended_two-level_view.txt
---------------------------------------------------------------------------
-c:g or --command:generate_all
no options
Full example:
ctwig projects/yourproject.pro -c:g
This command generates both the declaration-list and all of the views for a project. Use it if you want to update your project and are not interested in the output screen-notifications of the dec-list.
---------------------------------------------------------------------------
-c:c or --command:combine
Full example:
ctwig projects/some_set_of_projects.mul -c:c
After you have defined some projects in project-files (.pro), since CT 1.5x you can create a multi-project-definition (.mul) that enables you to show more projects at once; for now that is the trees of usage and used-by.
To create a multi-project declaration-list do the following:
-create and update the individual projects you want to include in below list.
-run the command: ./ctwig projects/your_multiproject.mul -c:c
-the command creates a directory and concatenates the dec-lists of the individual projects into one with a similar naming-convention. (mymultiproject.mul generates a subdir mymultiproject)
---------------------------------------------------------------------------
-c:t or --command:tree
options:
* direction
-r:u or --direction:usage (default)
-r:b or --direction:used-by
* depth
-d:3 --depth:3 (default)
Full examples:
ctwig projects/yourproject.pro -c:t -r:b -d:4
ctwig projects/yourproject.pro -c:t -r:u -d:2
ctwig projects/yourproject.pro -c:t (using the defaults)
And since 1.5x:
ctwig projects/yourmultiproject.mul -c:t
Seps can be ommitted:
ctwig projects/yourproject.pro -ct -ru -d2
Lastly above command starts with a box in which a substring can be entered to search for a declaration. Then a list of declarations is displayed which have the substring in them. If the entered substring matches only one declaration, a tree is shown based on the parameters direction and depth. The direction usage refers to the calls to other procs that are made in the proc, where used-by stands for all the procs that are using the declaration (so the reverse process). The depths stands for the number of levels that are shown.
Also now declarational arguments and comments are added to the chosen declaration.
Since CT 0.35 you can add a semi-column to indicate not only declaration but module as well, like so:
declaration;module
This is needed to show same-named decs.
Since CT 1.5x you can also enter a projectname, which is usefull for the multiproject-case, like so:
declaration;module;project
Omitting things means a wildcard. A tilde ~ prepended or postpended means exact-match (but case-insensitive).
Since 1.65, When the same declaration-name exists multiple times, a specific one can be chosen by adding the line-number after the tilde, like: someproc~401
Examples:
- entering nothing returns all decs
- ;; also means all decs
- ;;someproject means all decs of someproject
- ;somemodule; means all decs in somemodule of all projects
Defaultly the search is substring but sometimes you need an EXACT-MATCH, for example when you have myfunc and myfunction, for which the first one is a substring of the second one.
- myfunc~ returns only that function (if unique in all projects); also allowed
- ~myfunc
- ~myfunc~ for who likes to type ;-)
- myfunc~581 for the dec-occurence on that line
-----------------------------------------------------------------------------
-c:s or --command:sourcecode
Full example:
ctwig projects/yourproject.pro -c:s
This command enables you to show/view the full source-code of a certain declaration (like proc or template) and is added in CT 1.6x.
The search-function is the same as in the tree-command; you can search for a:
declaration;module;project
See above for further explanation.