:: Table of Contents ::

• Overview
  • Summary of Features
• Commands
• System Variables
• System Functions
  • Date Formats in System Functions
  • yeartoyear
  • padline
• Configuration
  • Global Options
  • Changes Tracking Configuration
  • Static Variable Values
  • Language Configuration
    • Default Language Configurations
  • Templates
    • Default Template Configurations
  • License Text
  • License Reference
• Compact Mode
• Block-Style Comment Headers
• A Note about Project Paths
• License Information
  • "Custom"
  • "CustomUri"
  • SPDX
  • Refreshing the License Text System Variable
• Changes Tracking
  • Option 1 Simple Replacement
  • Option 2 Template Substitution
• Auto Header
• Enforce Header
• Change Log
  • Configuring Change Logging
  • Questions about Change Logs
    • Can this be configured to not have a caption line?
    • Can it be configured to automatically add a log entry?
    • Can I have comments on a separate line?
    • Why do I have to manually add the comment?
    • What if I need longer comments?
• An Example Custom Configuration
• Creating a Custom Template
• Known Issues
  • Cleaning up SPDX License Text
  • Determining File Creation Time on Linux
• Credits

Overview

The psioniq File Header VSCode Extension will insert a header into the current document - either at the start of the document or at the current cursor position. The header can be configured globally and/or per language. However, the configuration separates the comment syntax from the template body so it is likely that a single template will be able to cover most languages.

It can optionally log modifications to the file via the change tracking feature which will update the header whenever the file is saved.

It is also possible to add templated comment blocks to the header to record for example a historic summary of changes to the file.

There are a veritable plethora of configuration options to cover your innermost headular cravings.

To report bugs, issues, suggestions use the github repository.

Here is a sample output:

/*
 * File: \Users\me\Development\psioniq\myProject\src\myPrecious.js
 * Project: \Users\me\Development\psioniq\myProject
 * Created Date: Saturday December 31 2016
 * Author: Arthur Bodkin, esq
 * -----
 * Last Modified: Sunday January 01 2017
 * Modified By: Tammy Bodkin
 * -----
 * Copyright (c) 2016 psioniq Global Enterprises, Inc
 */

To add a new header manually: * thump F1 and type Header Insert; or * type the keyboard shortcut ctrl-alt-H then ctrl-alt-H.

To insert an entry into the change log: * hit F1 and type Header Change Log Insert; or * type the keyboard shortcut ctrl-alt-C ctrl-alt-C.

Once inserted, the cursor will be placed at the end of the new log entry.

Now grab a coffee and read on...

Summary of Features

Refer to Configuration for the various extension settings details.

• Adds a generic or language-specific header at the current cursor location or at the top of the file.
• Optionally track changes in the header each time the file is saved.
• Configurable whitelists and blacklists to determine which files can be change tracked.
• Can automatically add a header to new files.
• Compatible with VSCode Multi Root Workspaces.
• Separates language specific elements (e.g. comment block begin and end) from the template body to minimise the number of templates you might need to manage.
• Configuration option to force the header to the top of the document - overridable per language.
• Configuration option to add additional blank lines after the header - overridable per language.
• Configurable options to add text before or after the header (e.g. pre-processor commands).
• Provides a default template body for all languages out of the box.
• Provides language-specific syntax settings (e.g. comment block syntax) out of the box.
• Configure your own custom language syntax globally and/or per language.
• Create your own custom templates - global and/or per language.
• Map custom template and syntax settings across languages so you can easily reuse them.
• Provides case-insensitive System Variables for placeholder value substitution.
• Provides case-sensitive System Functions for configurable placeholder value substitution.
• Allows the overriding of system variable values with static global values within the configuration.
• Create an unlimited number of custom static variables for use throughout your custom templates.
• Header insertion can be run manually via the key shortcut ctrl+alt+H then ctrl+alt+H.
• Can automatically insert license text based on SPDX license IDs or from a local text file.
• Allows changes logging for recording a history of changes to the file.

Commands

This extension adds the following commands to VSCode:

Command name	Keyboard Shortcut	Description
Header Insert	ctrl-alt-H ctrl-alt-H	Inserts a new file header
Header Change Log Insert	ctrl-alt-C ctrl-alt-C	Inserts a new change log entry into an existing header

System Variables

The following system variables are available for placeholder substitution in your templates. The variable names are case-insensitive.

Variable Name	Description
date	The current date using the current locale (also see the dateformat() system function below for a formattable date string version).
time	The current time using the current locale.
year	The current year.
filepath	The fully-qualified name of the file. Refer to psi-header.config.overridePathSeparator if you need to override the path separator.
fullpath	The fully-qualified path to the file (excludes the filename). Refer to psi-header.config.overridePathSeparator if you need to override the path separator.
filerelativepath	The file name including the relative path within the project. Refer to psi-header.config.overridePathSeparator if you need to override the path separator.
relativepath	The relative path to the file within the project (excludes the filename). Refer to psi-header.config.overridePathSeparator if you need to override the path separator.
filename	Just the file name without the path details.
filenamebase	Just the file name without the path details or extension.
projectpath	The fully-qualified path to the root directory of the project. Refer to psi-header.config.overridePathSeparator if you need to override the path separator.
projectname	Attempts to read package.json (in the current or any parent directory) for either a displayName or name property. If there is no package.json file and the file has been saved to disk, it will return the project path's base name.
projectslug	Provides a version of projectname for use in url's and links. E.g. "@davidquinn/psi-header" would return "davidquinn/psi-header"
projectversion	Attempts to read package.json (in the current or any parent directory) for a version property.
company	The name of your company. In this release it defaults to "Your Company".
author	Will attempt to get the name of the current user. The options are coalesced in the following order: psi-header.config.author then fullname from the OS then username from the OS. If none of these return a value, it defaults to "You".
initials	Your initials (where you don't want the whole author name
authoremail	The email address of the file author. In this release it defaults to "you@you.you".
licensetext	The full text of the license. This is only required if psi-header.config.license option is set to "Custom".
copyrightholder	Used in some licenses. If not provided it defaults to the same value as company.
licensename	The name of the license. If not using a custom license, this is determined automatically.
licenseurl	The url for the license. If not using a license, this is determined automatically.
spdxid	The SPDX License ID for the license. If not using a custom license, this is determined automatically.
hostname	The value of the psi-header.config.hostname setting if set, otherwise the local machine's hostname as provided by the OS.

Within your template, surround the variable names with two sets of chevrons (e.g. `<<filepath>>. Also, you can modify the text case of the output for any of the system variables by appending !U or !L to the end of the variable name (e.g. <<filepath!U>> to render the file path in uppercase or <<filepath!L>> for lower case).

You can also create your own static custom variables (for example if you are using this extension within a team or you need project-specific variables in your template) by adding your own variables to psi-header.variables then referring to them within your template like the following example which adds a custom variable called projectCreationYear:

    "psi-header.variables": [
        ["projectCreationYear", "2017"]
    ],
    "psi-header.templates": [
        {
            "language": "*",
            "template": [
                "File: <<filename>>",
                "Project: <<projectname>>",
                "File Created: <<filecreated('dddd, Do MMMM YYYY h:mm:ss a')>>",
                "Author: <<author>> (<<authoremail>>)",
                "-----",
                "Last Modified: <<dateformat('dddd, Do MMMM YYYY h:mm:ss a')>>",
                "Modified By: <<author>> (<<authoremail>>>)",
                "-----",
                "Copyright <<projectCreationYear>> - <<year>> <<copyrightholder>>, <<company>>"
            ]
        }
    ]

NOTE: You can include system variables in the beforeHeader and afterHeader properties of your language configurations. However, they will only be processed when the header is first added to your file and will not be updated on subsequent file saves. Why? Because the extension has no idea what may have changed or been edited outside of the template since it was added to the file, and possibly the worst thing that the extension could do is delete or mess up your carefully crafted source code by assuming that the structure of the before and after blocks in your language template exactly matches the structure that existed at the time the header was added.

System Functions

The following case-sensitive system functions are available for configurable placeholder value substitution. These are similar to System Variables but they take arguments and they do not support the text case modifiers.

Function Name	Description
dateformat(format)	The current date or date part using format strings. This function takes a single string argument which represents the moment.js compatible format string.
filecreated(format)	The file created date and time using format strings. This function takes a single string argument which represents the moment.js compatible format string (surrounded in single or double quotes). It can also be called without arguments to use the current locale date format. If the file created date cannot be determined it will return the current date and time (usually because the file has not yet been saved to disk, or the operating system failed to return the creation date and time). Refer to this known issue for potential issues with some Linux setups.
yeartoyear(from, to)	Generates a string in the form "YYYY - YYYY" or just "YYYY" of both dates evaluate to the same year. Useful for copyright messages. Refer to year to year for details.
padline(char, maxLength)	Pads the end of the line with the char up to the maxLength characters. Refer to padline for details.

As with system variables the functions can appear in the beforeHeader and afterHeader properties of your language configuration, with the same constraints around updating.

Date Formats in System Functions

filecreated can also return the current locale date string by passing no arguments. Both the following will work:

    <<filecreated()>>
    <<filecreated>>

The following examples would both output a date like 2017-04-14

    <<dateformat('YYYY-MM-DD')>>
    <<filecreated('YYYY-MM-DD')>>

And the following would both generate something like Friday, April 14th 2017, 8:50:19 am

    <<dateformat('dddd, MMMM Do YYYY, h:mm:ss a')>>
    <<filecreated('dddd, MMMM Do YYYY, h:mm:ss a')>>

These functions use Moment.js and can use all [Moment.js format string options](http://momentjs.com/d