Skip to content

Commit fbc52f5

Browse files
sidmishrawsidmishraw
committed
Updated Readme and Changelog files, documented the changes.
1 parent fa8f6d3 commit fbc52f5

File tree

3 files changed

+132
-156
lines changed

3 files changed

+132
-156
lines changed

‎CHANGELOG.md

+6-2
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,13 @@ All notable changes to the "topper" extension will be documented in this file.
88

99
### [v1.0.0]
1010

11+
**[!!!] This release has breaking changes and might need some configuration from your part for the first time you start using it –– especially on older files that were annotated with older versions of Topper. No worries for new users and new files.**
12+
1113
- Re-wrote the code from scratch in Typescript for better maintenance. Also got rid of the popup, it seems that the use of a keyboard shortcut is the best approach. The other way is to invoke command directly using the commands menu of vscode.
12-
- Externalized the date formatting for created date and last modified date.
13-
- Externalized the last modified date capture regex in case the user defines their custom last modified date format.
14+
- The command palette now shows a command that is bound to the first profile in the list, no need for the popup –– this was made for streamlined usage. For a more streamlined approach, please use the keyboard shortcuts to the desired profiles.
15+
- [CAUTION] Externalized the date formatting for created date and last modified date.
16+
- [CAUTION] Externalized the last modified date capture regex in case the user defines their custom last modified date format.
17+
- [CAUTION] Externalized the row and column indices to be used for insertion of the header string: use with care. Defaults to 0 for both row and col for sanity.
1418

1519
### [v0.4.0]
1620

‎README.md

+125-153
Original file line numberDiff line numberDiff line change
@@ -1,132 +1,166 @@
1-
# Topper README
1+
# Topper
2+
3+
```
4+
Version: 1.0.0
5+
```
26

37
`Topper` is a file header utility. It will add a header to the file depending on the configurations made by you.
48

59
## Features
610

7-
The gif below shows how to use the `Topper` extension.
11+
> Note: the GIF below is deprecated, will be replacing it with a new one soon.
12+
13+
> [DEPRECATED] The gif below shows how to use the `Topper` extension. Valid for extension version <= 0.4.0
814
915
![](https://zippy.gfycat.com/LeanNeatEasternnewt.gif)
1016

1117
## Extension Settings
1218

1319
This extension contributes the following settings:
1420

15-
- `topper.customTemplateParameters`: This configures template parameters. These parameters can be used in the header templates as placeholders.
21+
### `topper.customTemplateParameters`: This configures template parameters. These parameters can be used in the header templates as placeholders.
1622

17-
The default setting is:
23+
The default setting is:
1824

19-
```javascript
20-
[
25+
```json
26+
[
2127
{
22-
personalProfile: {
23-
author: "bulbasaur",
24-
website: "bulbasaur.github.bitbucket.yababbdadado.com",
25-
copyright: "None",
26-
license: "None",
27-
email: "ivysaur.bulbasaur@venosaur.com"
28-
}
28+
"personalProfile": {
29+
"author": "bulbasaur",
30+
"website": "bulbasaur.github.bitbucket.yababbdadado.com",
31+
"copyright": "None",
32+
"license": "None",
33+
"email": "ivysaur.bulbasaur@venosaur.com",
34+
},
2935
},
3036
{
31-
officeProfile: {
32-
author: "John Doe",
33-
department: "Product Development",
34-
email: "john.doe@doejohn.com"
35-
}
36-
}
37-
];
38-
```
37+
"officeProfile": {
38+
"author": "John Doe",
39+
"department": "Product Development",
40+
"email": "john.doe@doejohn.com",
41+
},
42+
},
43+
];
44+
```
3945

40-
You can add any number of profiles to the list. You also have the ability to add in any number of parameters here in your profiles. This way you can use those parameters in the header templates.
46+
You can add any number of profiles to the list. You also have the ability to add in any number of parameters here in your profiles. This way you can use those parameters in the header templates.
4147

42-
- `topper.headerTemplates`: This is the list of all the header templates you configure depending upon the languages being used.
48+
### `topper.headerTemplates`: This is the list of all the header templates you configure depending upon the languages being used.
4349

44-
The list of language Ids can be found here: [https://code.visualstudio.com/docs/languages/identifiers](https://code.visualstudio.com/docs/languages/identifiers).
50+
The list of language Ids can be found here: [https://code.visualstudio.com/docs/languages/identifiers](https://code.visualstudio.com/docs/languages/identifiers).
4551

46-
If the file's `languageId` is not configured here, it defaults to the `defaultCStyled` header template.
52+
In case the language name or ID is not found: the following header template is used:
4753

48-
> Note: Please do not delete the `defaultCStyled` template. Copy it over when configuring this section.
49-
> Note: Please keep the `defaultCStyled` as the first element in the list of all the header templates.
54+
```json
55+
{
56+
"headerBegin": "/**",
57+
"headerPrefix": "*",
58+
"headerEnd": "*/",
59+
"template": [
60+
"${headerBegin}",
61+
"${headerPrefix} ${fileName}",
62+
"${headerPrefix} @author ${author}",
63+
"${headerPrefix} @description ${description}",
64+
"${headerPrefix} @created ${createdDate}",
65+
"${headerPrefix} @last-modified ${lastModifiedDate}",
66+
"${headerEnd}"
67+
]
68+
}
69+
```
5070

51-
The default configuration for the header templates is:
71+
Additionally, the default configuration for the header templates is:
5272

53-
```javascript
54-
[
55-
{
56-
defaultCStyled: {
57-
headerBegin: "/**",
58-
headerPrefix: "*",
59-
headerEnd: "*/",
60-
template: [
61-
"${headerBegin}",
62-
"${headerPrefix} ${fileName}",
63-
"${headerPrefix} @author ${author}",
64-
"${headerPrefix} @description ${description}",
65-
"${headerPrefix} @created ${createdDate}",
66-
"${headerPrefix} @last-modified ${lastModifiedDate}",
67-
"${headerEnd}"
68-
]
69-
}
70-
},
73+
```json
74+
[
7175
{
72-
python: {
73-
headerBegin: "#",
74-
headerPrefix: "#",
75-
headerEnd: "#",
76-
template: [
77-
"${headerBegin}",
78-
"${headerPrefix} ${fileName}",
79-
"${headerPrefix} @author ${author}",
80-
"${headerPrefix} @description ${description}",
81-
"${headerPrefix} @created ${createdDate}",
82-
"${headerPrefix} @last-modified ${lastModifiedDate}",
83-
"${headerEnd}"
84-
]
85-
}
76+
"python": {
77+
"headerBegin": "#",
78+
"headerPrefix": "#",
79+
"headerEnd": "#",
80+
"template": [
81+
"${headerBegin}",
82+
"${headerPrefix} ${fileName}",
83+
"${headerPrefix} @author ${author}",
84+
"${headerPrefix} @description ${description}",
85+
"${headerPrefix} @created ${createdDate}",
86+
"${headerPrefix} @last-modified ${lastModifiedDate}",
87+
"${headerEnd}"
88+
]
89+
}
8690
}
87-
];
88-
```
91+
]
92+
```
8993

90-
As you can already see, each header template object is of form:
94+
As you can already see, each header template object is of form:
9195

92-
```javascript
93-
{
94-
"[languageId]": {
95-
"headerBegin": string,
96-
"headerPrefix": string,
97-
"headerEnd": string,
98-
"template": string[] // <string values with parameters>
99-
}
100-
}
101-
```
96+
```javascript
97+
{
98+
"[languageId]": {
99+
"headerBegin": string,
100+
"headerPrefix": string,
101+
"headerEnd": string,
102+
"template": string[] // <string values with parameters>
103+
}
104+
}
105+
```
106+
107+
To use the parameters inside the `template`, use the `${<parameter name>}` notation.
108+
109+
### [CAUTION] `topper.lastModified`: The key of the last-modified field in the header template --- `@last-modified`. Topper looks for this to determine if it needs to update the last-modified date-time value in your header. It defaults to `@last-modified`. For example, if you assign the value to `Modified`, then your header field for `Modified` should have be defined as `${headerPrefix} Modified ${lastModifiedDate}` for it to be considered by topper for automatic updation.
110+
111+
### [CAUTION] `topper.lastModifiedRegex`: The regular expression used for capturing the last modified date in the header and auto-update it when the file is saved.
112+
113+
Defaults to:
114+
115+
```javascript
116+
'[ ]*\\@last\\-modified\\s*.?\\s+((\\d{4}-\\d{2}-\\d{2})T(\\d{2}:\\d{2}:\\d{2}\\.\\d{3})Z([\\+\\-]?\\d{2}:\\d{2}))\\n*';
117+
```
118+
119+
> Note: This configuration is dependent on the `topper.lastModified` and `topper.dateFormat` values, please make sure that both are in sync, otherwise Topper will not be able to capture the last modified field in the header and update the timestamp.
120+
121+
### [CAUTION] `topper.dateFormat`: The format to be used for created date and last modified date values in the header. Topper uses Moment.js so please refer to the date formatting rules mentioned in moment.js. https://momentjs.com/docs/ . The default is ISO date format.
122+
123+
Defaults to:
124+
125+
```javascript
126+
'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]Z';
127+
```
102128

103-
To use the parameters inside the `template`, use the `${<parameter name>}` notation.
129+
> Note: Please make sure that the last date modified regex is also in sync to the changes made to date format, otherwise Topper will not be able to automatically update the last modified timestamp in the header.
104130
105-
- `topper.lastModified`: The key of the last-modified field in the header template --- `@last-modified`. Topper looks for this to determine if it needs to update the last-modified date-time value in your header. It defaults to `@last-modified`. For example, if you assign the value to `Modified`, then your header field for `Modified` should have be defined as `${headerPrefix} Modified ${lastModifiedDate}` for it to be considered by topper for automatic updation.
131+
### [CAUTION] `topper.insertAtRow`: The row from where to insert the header string at! Defaults to `0`.
106132

107-
Topper has a few intrinsic template parameters:
133+
> Note: Please override this only if required, the default value is a SANE value. thanks :)
108134
109-
- `createdDate` - The date when the file was created, this is obtained from the underlying OS. If the file is `Untitled-x` or unsaved, the created time defaults to the time `Topper: Add Header` command was invoked.
135+
### [CAUTION] `topper.insertAtCol`: The column from where to insert the header string at! Defaults to 0.
110136

111-
- `lastModifiedDate` - The date when the file was modified, this too is obtained from the underlying OS. If the file is `Untitled-x` or unsaved, the created time defaults to the time `Topper: Add Header` command was invoked.
137+
> Note: Please override this only if required, the default value is a SANE value. thanks :)
112138
113-
- `fileName` - The name of the file
139+
## Topper's intrinsic parameters
114140

115-
- `fileVersion` - The VSCode maintained fileVersion
141+
Topper has the following intrinsic template parameters. The values of these parameters are extracted from the underlying OS and the file metadata:
142+
143+
- `createdDate` - The date when the file was created, this is obtained from the underlying OS. If the file is `Untitled-x` or unsaved, the created time defaults to the time `Topper: Add Header` command was invoked.
144+
145+
- `lastModifiedDate` - The date when the file was modified, this too is obtained from the underlying OS. If the file is `Untitled-x` or unsaved, the created time defaults to the time `Topper: Add Header` command was invoked.
146+
147+
- `fileName` - The name of the file.
148+
149+
- `fileVersion` - The VSCode maintained file version.
116150

117151
## Defining a custom keyboard shortcut
118152

119153
To define a custom keyboard shortcut do the following:
120154

121-
- Preferences -> Keyboard Shortcuts -> Open `keybindings.json`
155+
- Preferences -> Keyboard Shortcuts -> Open `keybindings.json`
122156

123-
- Add the following entry:
157+
- Add the following entry:
124158

125159
```json
126160
// This opens up the interactive Topper with all the popups.
127161
{
128-
"key": "cmd+shift+t",
129-
"command": "topper.addTopHeader"
162+
"key": "cmd+shift+t",
163+
"command": "topper.addTopHeader"
130164
}
131165
```
132166

@@ -135,8 +169,8 @@ or
135169
```json
136170
// Defines the shortcut for the specific profile. Now only that specific profile is invoked. No annoying popups!
137171
{
138-
"key": "<your-key-combination>",
139-
"command": "topper.addTopHeader.<your-profile-name>"
172+
"key": "<your-key-combination>",
173+
"command": "topper.addTopHeader.<your-profile-name>"
140174
}
141175
```
142176

@@ -145,81 +179,19 @@ For eg:
145179
```json
146180
// Invokes Topper using the `personalProfile` directly, skipping all the interactive popups/dialog boxes.
147181
{
148-
"key": "cmd+shift+t 1",
149-
"command": "topper.addTopHeader.personalProfile"
182+
"key": "cmd+shift+t 1",
183+
"command": "topper.addTopHeader.personalProfile"
150184
}
151185
```
152186

153187
The `"key"` field can be any key combination. The command has to be `"topper.addTopHeader"`.
154188

155189
## Changelog
156190

157-
### [v0.4.0]
158-
159-
- Merged pull request from @Drakesinger into master to allow more flexible formats for the `last modified` field in the headers. Thanks @Drakesinger for the PR!
160-
161-
- Updated the readme document with more information about the `topper.lastModified` contribution point. Since, I had forgotten to add the description of this contribution point in the document I believe some of the users might have found it difficult to configure the `lastModified` field name in their headers. Sorry!
162-
163-
### [v0.3.2]
164-
165-
- Fixed the issue [problem about last-modified when press cmd+s #3](https://github.com/sidmishraw/topper/issues/3). Now, topper's watcher listens to the `TextDocumentWillSaveEvent` and updates the last-modified field before the document saves.
166-
167-
### [v0.3.1]
168-
169-
- Fixed the issue of Topper capturing templates of "last-modified". Now, there are strict patterns in place.
170-
171-
### [v0.3.0]
172-
173-
- Fixed issue where the `@last-modified` field in the header was not getting updated automatically. Now, there is a configuration field `topper.lastModified` where the users can specify their custom field names for `last-modified` incase they do not use `@last-modified`. The default value is `@last-modified`.
174-
175-
> Caveats: The implementation is choppy in some aspects because of limited support from VS Code APIs. Expect a better implementation in the next version.
176-
177-
- Code cleanup.
178-
179-
### [v0.2.0]
180-
181-
- Code cleanup.
182-
183-
- Addition of profile specific shortcuts added to `keybinding.json` of VSCode:
184-
185-
```json
186-
{
187-
"key": "cmd+shift+t 1",
188-
"command": "topper.addTopHeader.personalProfile"
189-
},
190-
{
191-
"key": "shift+cmd+t 2",
192-
"command": "topper.addTopHeader.officeProfile"
193-
}
194-
```
195-
196-
The first key combination is `Command + Shift + T` followed by a `1` or `2` depending on the profile. The user is free to bind any profile to any key combination.
197-
The commandId is of the form `topper.addTopHeader.<your-profile-name>`.
198-
199-
### [v0.1.0]
200-
201-
- Stable release.
202-
203-
### [v0.0.3]
204-
205-
- Changed the extension's command from `extension.addTopHeader` to `topper.addTopHeader`. To make it easier for customized keybinding.
206-
207-
- Code cleanup.
208-
209-
### [v0.0.2]
210-
211-
- Added support for multi line strings as values for the custom template parameters.
212-
213-
- Updated `lastModifiedDate` to be fetched from the underlying OS. This is the true last modified date.
214-
215-
### [v0.0.1]
216-
217-
- Initial release of `Topper` extension. [Alpha]
218-
219-
## P.S
191+
The change log is available at: [change-log](./CHANGELOG.md)
220192

221-
In case of any suggestions or issues please email me at [**sidharth.mishra@sjsu.edu**](mailto:sidharth.mishra@sjsu.edu)
193+
In case of any suggestions or issues please feel free to create an issue on the Github repo.
222194

223195
## References
224196

225-
- Template style configuration idea inspired by [https://github.com/doi/fileheadercomment](https://github.com/doi/fileheadercomment)
197+
- Template style configuration idea inspired by [https://github.com/doi/fileheadercomment](https://github.com/doi/fileheadercomment)

‎src/extension.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
* extension.ts
3333
* @author Sidharth Mishra
3434
* @created Sun Apr 07 2019 19:33:36 GMT-0700 (PDT)
35-
* @last-modified Sun Apr 28 2019 23:16:19 GMT-0700 (PDT)
35+
* @last-modified Sun Apr 28 2019 23:50:19 GMT-0700 (PDT)
3636
*/
3737

3838
import { ExtensionContext, workspace, commands } from 'vscode';

0 commit comments

Comments
 (0)