-
Notifications
You must be signed in to change notification settings - Fork 1
/
Dawn.txt
196 lines (138 loc) · 8.26 KB
/
Dawn.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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
*dawn* Project template generator
*dawn.vim*
License: MIT
URL: https://github.com/LunarWatcher/Dawn
Changelog: Todo
================================================================================
Table of contents~
1. Introduction ............................. |dawn-introduction|
2. Usage .................................... |dawn-usage|
3. Options .................................. |dawn-options|
4. Functions ................................ |dawn-functions|
5. The template object ...................... |dawn-template-object|
================================================================================
1. Introduction *dawn-introduction*
Dawn is a flexible project generator.
What?~
What this means is, you plug in a few options and preferences, invoke a command
in a directory, and Dawn generates the files and folders you requested.
You know how IDEs have project setup? Dawn is that, but flexible, customizable,
and can by extension handle any type of project in any style you prefer, or that
your organization/group/whatever requires/prefer. To be completely clear though,
Dawn is _only_ a generator - not a project manager, IDE-emulator, session
manager, or a plugin that stores the location of your projects.
But why?~
Why not?
How?~
Hop on down to |dawn-usage|.
Doesn't this already exist?~
Not as far as I know. There's project management plugins of varying quality and
documentation levels, but none for generating. But hey, maybe it's just me who
keeps jumping on new projects constantly :p
================================================================================
2. Usage *dawn-usage*
See |dawn-template-object| for adding additional templates.
Use *:DawnGenerate* <template name> to generate a template. For a list of
templates in use, use *:DawnList* (<C-g><C-l>).
================================================================================
3. Options *dawn-options*
What's a customizable plugin without options? This section lists the options
that exist. Note that a few have
Table of Contents:~
* |g:DawnDefaultTemplates|
* |g:DawnProjectTemplates|
* |g:DawnSearchPaths|
* |g:DawnSkipExisting|
--------------------------------------------------------------------------------
*g:DawnDefaultTemplates*
Default: ['vim', 'cpp']
Dawn does ship with a couple pre-defined templates for projects; this is the
variable you use if you want to disable these completely.
Essentially, you remove names from the array, and they won't load.
Also, note that the defaults respect your choices. If you name a template `vim`
(case-sensitive, however), the standard `vim` template won't load.
--------------------------------------------------------------------------------
*g:DawnProjectTemplates*
Default: depends on |g:DawnDefaultTemplates|
Refer to the source code for the template implementations. Note that certain
default templates depend on template files present in the /templates directory
of the plugin, by default.
By overriding |g:DawnSearchPaths|, you can override files without overriding
templates. By adding a custom path to the variable before the default path, any
custom files you add in your directory will override the plugin files.
To add additional templates, you add a |dawn-template-object|. Names may be
equivalent to built-in templates without removing the default templates - Dawn
will not override already-present templates when initialization takes place.
--------------------------------------------------------------------------------
*g:DawnSearchPaths*
Default: [<path to plugin>/templates] if |g:DawnDefaultTemplates| has elements,
[] otherwise
Defines where to search for files defined by `source` declarations in
|dawn-template-object|, when the path isn't detected to be absolute.
Note that for paths relative to the home directory, it's adviced that you use
|$HOME| instead of "~/path", due to internal detection systems.
--------------------------------------------------------------------------------
*g:DawnSkipExisting*
Default: 1
Whether or not to skip existing folders and files. Primarily useful for projects
with a few files already produced.
================================================================================
4. Functions *dawn-functions*
If you read or skimmed through the options, you've probably noticed several
functions being mentioned.
These exist to utilize autoload functionality, as well as provide a somewhat
more "sensible" interface to some of the variables.
Table of Contents:
TODO at a later time~
================================================================================
5. The template object *dawn-template-object*
Note that this is heavily connected to |g:DawnProjectTemplates|. To be specific
(and as mentioned in that bit of the documentation), the variable contains
several template objects. To keep the help document structured, this is the bit
of the document that covers what these are, and their syntax.
--------------------------------------------------------------------------------
5.1. *dawn-template-object-syntax*
Well, it's an object. (or |dict| as Vim likes to call it). I won't be covering
the syntax of an object here, but you're probably familiar with it already.
The structure of Dawn's template objects, excluding the outer list, is: >
{
"folders": ["a", "b", "b/c", "you get the idea"],
"files": {"a/example.txt": {'content': 'File content, or', 'source':
'absolute path or a relative one (Dawn will search through
|g:DawnSearchPaths|)'}},
"commands": ["Optional, but commands to run after initializing the basic
folder and file structure. Can also be used without folders or files
if you just wanna interact with something like Hugo"]
}
<
Keys:~
* folders: as you might expect, it contains folders to generate. You don't
explicitly have to declare the roots here (Dawn is smart enough
to figure out the maths and mkdir everything) - depends purely on
what you prefer.
* files: A set of files to generate. Note that this is a map, unlike
folders, which is a list. The map accepts one of two keys:
content or source. Content is self-explanatory: you declare, in
vim, what you want in the file. content can also be a function
Source is different, and defines a file to copy over to the
project. If the path isn't absolute, Dawn will search relative to
|g:DawnSearchPaths|
* commands: A vim function, or a list of vim commands to execute after
folders and files are generated. Note that the commands are
handled through |exec| - if you want to use system commands, the
command has to be in the format `!yoursystemcommand` (i.e.
`!ls`).
*dawn-template-object-substitutions*
Additionally, certain bits supports substitutions. This is largely because it's
not always possible to generate a static, final project structure with clear
file names that have no reason to change. Vim projects is one example of this;
doc/help.txt is way to generic. Dawn therefore offers a set of substitutions.
These are run on file names, commands (|g:DawnSubstituteCommands|), folder
names, and file content (|g:DawnSubstituteFileContent|).
The currently supported substitutions are:
- %{dn} The name of the current directory. If the generate
command is invoked in
/home/you/projects/SuperSecret, %dn is substituted
with SuperSecret.
- %{ldn} %dn but forced lower-case
vim:ft=help:tw=80