# Package Control:

  1. Open Sublime Text 3
  2. cmd+shift+p
  3. Package Control: Install Package
  4. Search for LiveStamps

# Manual Install:  

  1. Open Sublime Text 3
  2. Sublime Text Menu -> Preferences -> Browse Packages
  3. Create folder called LiveStamps
  4. Copy the contents of this repo to the folder.

1. Right-Click -> LiveStamps -> Definitions -> Open
  2. Fill in "user_info" key accordingly
  3. You may add custom keys here if you like

  # Note, By default LiveStamps updates all stamps on save, to disable:

  Right-Click -> LiveStamps -> Preferences -> Update On Save

# Generic Usage:

[super] + [alt] + [letter]   # Injects a formatted value
[ctrl]  + [alt] + [letter]   # Injects a raw value

# Example: All Stamps

[super] + [alt] + a          # Injects all formatted values   
[ctrl]  + [alt] + a          # Injects all raw values

Right-click -> LiveStamps -> Insert Stamp -> [type]
Right-click -> LiveStamps -> Insert Value -> [type]

1. Right-click -> LiveStamps -> Menu -> Build -> Command      # Only needed first time
2. [cmd/ctrl] + [shift] + [p]
3. Type LiveStamps to see list of commands, enter to execute.

# Refresh Existing Menus:
Right-click -> LiveStamps -> Menus -> Refresh

# Generate a Menu:
Right-click -> LiveStamps -> Menus -> Build -> [menutype]

# Open Existing Menu To Manually Edit:
Right-click -> LiveStamps -> Menus -> Open -> [menutype]

# Backup Existing Stamps & User Info:
 Right-Click -> LiveStamps -> Definitions -> Backup

 # Restore Previous Stamp Definitions:
 Right-Click -> LiveStamps -> Definitions -> Restore -> [definition file]

 # To Rename Definitions:
 1. Right-Click -> LiveStamps -> Definitions -> Browse
 2. Rename any files as you wish (keep .sublime-settings extension)

 # To Import or Share Definitions:
 1. Right-Click -> LiveStamps -> Definitions -> Browse
 2. Copy any stamp definition files to or from this directory to import/export

1. Right-Click -> LiveStamps -> Definitions -> Open
  2. Custom stamp definitions are defined within the "stamps" key
  3. There are a few examples and instructions to get you started here as well

"mystamp": {
  "value": "LiveStamps rule!",
},

# Output: LiveStamps rule!

# Stamp Keymap:

"[name]": {
  "[menu]"  : string,
  "[value]" : int|string|list *dict can be used for time offsets*
  "[regex]" : string,
  "[stamp]" : string,
  "[tflag]" : string,
},

# Required Keys:

[name]   : The parent key containing the stamp name using snake_case
[value]  : A string/int literal, or list of values to be used for injection.

# Optional Keys:

[menu]   : Groups a stamp under a submenu in the right-click context menu
[regex]  : Regex pattern. Set to auto for docblock. Exclude for static data.
[stamp]  : Formatting string. Python format() flags. See injection flags below. 
[tflag]  : Time Formatting string. Python strftime() flags i.e. "%d-%m-%Y"

"mystamp1": {
  "value": "zero",        # A String Literal
},

# Output: zero

"mystamp2": {
  "value": ["zero"],      # Single List Item
},

# Output: zero

"mystamp3": {
  "value": [1, "two", 3]  # Multiple Item Lis:
},

# Output: 1 two 3

# The following stamps are auto generated:

"user"         : Gets current user
"checksum"     : Gets checksum of the current file (algorithm can be modified)
"extension"    : Gets current file extension
"base_name"    : Gets current basename
"file_size"    : Gets current filesize
"file_name"    : Gets current filename
"file_path"    : Gets current filepath
"parent_name"  : Gets name of parent folder
"parent_path"  : Gets path of parent folder
"file_extname" : Gets current filename.extension
"modified"     : Current timestamp using "%c" flag, (preferred local time)

# From "user_info" key in LiveStampsDefinitions.sublime-settings:

"author"      : "Your name here"                                  
"vendor"      : "Your company here"                                     
"email"       : "Your email here"                              
"website"     : "Your website here"                     
"quote"       : "A quote you like"

# Custom info may be added to the "user_info" key if you wish:

"location"    : "Whitehorse, Yukon",
"fav_color"   : "Green",
"gender"      : "male"

SOURCE:
-------

"tic_tac": {
  "value": "Tic",
  "stamp": "{0} Tac",  # Don't worry about the {0}, it's covered next!
},

# Output -> Tic Tac


USING THE SOURCE VALUE:
-----------------------

"tic": {
  "value": "_tic_tac",  # Leading underscore gets the "value" key of tic_tac
}

# Output -> Tic


USING THE SOURCE STAMP:
-----------------------

"tic_tac_toe": {
  "value": "tic_tac",   # No underscore gets the formattad "stamp" key of tic_tac
  "stamp": "{0} Toe",
}

# Output -> Tic Tac Toe

'stamp': "{0} {1} {2}" # Explicit location (stamp values injected by index)
'stamp': "{} {} {}"    # Implicit location (stamp values injected sequentially

# All these will output: Have you heard? LiveStamps rule! Thanks TundraTech!

# No injection:

  "mystamp": {
    "value": "Have you heard? LiveStamps rule! Thanks TundraTech!",
  },

# Complete injection:

  "mystamp": {
    "value": "Have you heard? LiveStamps rule! Thanks TundraTech!",
    "stamp": "{0}",
  },

# Partial injection (explicit):

  "mystamp": {
    "value": "LiveStamps rule!",
    "stamp": "Have you heard? {0} Thanks TundraTech!",
  },

# Partial injection (implicit):

  "mystamp": {
    "value": "LiveStamps rule!",
    "stamp": "Have you heard? {} Thanks TundraTech!",
  },

SOURCE STAMP
--------------

"mystamp": {
  "value": ["zero", "one", "two", "three"],
  "stamp": "@mystamp   {0} {1} {2} {3}",
},

# Normal Output: Each value is mapped to a Python format() flag:

  "stamp" : "@mystamp   {0} {1} {2} {3}",
  Output  :  @mystamp   zero one two three


# Mixed ordering is allowed and flags can be injected anywhere:

  "stamp" : "@mystamp   {3} hello {1} {2} world {0}",
  Output  :  @mystamp   three hello one two world zero


# Not all values have to be mapped to a flag

  "stamp" : "@mystamp   {0} {1}",
  Output  :  @mystamp   zero one


# It's OK to define more flags used than values to allow for future expansion

  "stamp" : "@mystamp   {0} {1} {2} {3} {4} {5} {6} {7}",
  Output  :  @mystamp   zero one two three


# Using a flag more than once is OK.

  "stamp" : "@mystamp   {0} {0} {0} {0} {1} {2} {3} {0}",
  Output  :  @mystamp   zero zero zero zero one two three zero


# Using no flags is also OK.

  "stamp" : "@mystamp   ",
  Output  :  @mystamp

Right Click -> LiveStamps -> Help -> format() Reference

"bases": {
  "value": 87,
  "stamp": "Base conversion: {0:d} - {0:x} - {0:o} - {0:b}",
},

# Output: Base conversion:  87 - 57 - 127 - 1010111

"formatted_bases": {
  "value": [87, "\nDecimal","\nHex", "\nOctal", "\nBinary"],
  "stamp": "{1:<10}: {0:d} {2:<10}: {0:x} {3:<10}: {0:o} {4:<10}: {0:b}",
},

Output:

Decimal  : 87 
Hex      : 57 
Octal    : 127 
Binary   : 1010111

Right Click -> LiveStamps -> Help -> strftime() Reference

"date": {
  "value": "auto",
  "tflag": "%d-%m-%Y",
  "regex": "@date.+",
  "stamp": "@date        {0}",
},

# Output: @date        08-03-2015

"time": {
  "value": "auto",
  "tflag": "%c",
  "regex": "@modified.+",
  "stamp": "@modified    {0}",
},

# Output: @modified    Fri Mar  6 18:21:57 2015

# String literal
"value": "microseconds: -21709870.5",

# Timezone support
"value": "America/Whitehorse",

# Multiple offsets in a list
"value": ["years: 10", "weeks: 3"],

# Multiple offsets in a dictionary
"value": {"months": -1.5, "seconds" :30},

"ahead_ten_hours": {
  "value": "hours: 10",
  "tflag": "%c",
},

# Output: Wed Apr  1 22:29:05 2015

"Maui time": {
  "value": "America/Honolulu",
  "tflag": "%c",
  "stamp": "Maui time is: {0}",
},

# Output: Maui time is: Wed Apr  1 22:29:05 2015

"ten_minutes_thirty_seconds_ago": {
  "value": "[minutes=-10, seconds=-30]",
  "tflag": ""
},

# Auto defined stamp/value:

"mystamp": {
  "value": "Is really cool",
  "regex": "auto",
  "stamp": "auto", 
 }

# Which would work great in a docblock header:

/**
 * # Anything here is safe
 * @mystamp Is really cool   # Anything over here is always erased on update
 * # Anything here is safe
 */

"mystamp": {
    "value": "Is really cool",
    "regex": "* @mystamp.+",
    "stamp": "* @mystamp {0}",
  },

Right-Click -> LiveStamps -> Preferences -> Settings - User

# CAUTION!!! Changes here will have a big, potentially dangerous effect:

"autoregex" : " \\* @{0}.+",  # Stamp name injected at flag {0}
"autostamp" : " * @{0} {1}",  # Stamp name injected at flag {0}, values at {1}
"separator" : " ",            # Separator used for "auto" multi value stamps

# Note the escaped backslashes because input is in JSON.

  "date": {
    "value": "Date is: ",
    "tflag": "%d-%m-%Y",
    "regex": "Date is (\\d\\d-\\d\\d-\\d\\d\\d\\d)",
    "stamp": "{0}",
  },

# Output: Date is 28-03-2015

# Matches "%c" format flag

"regex": "(Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)(\s|\s\s)(\d|\d\d)\s(\d\d:\d\d:\d\d)\s\d\d\d\d"