# snippet
```snippet``` allows you to create, view and use snippets on the command-line.
## Usage
```
# Add a new snippet to the database
$ snippet -e archive/extract-tgz -f 'tar -xzvf <archive>'
# Edit a snippet (will open vim)
$ snippet -e archive/extract-tgz
# Search and use a snippet which include the term "extract" (will open fzf)
$ snippet -t extract
# Fill snippet with a value
$ snippet -t archive/extract-tgz /path/to/foo.tar.gz
tar -xvf /path/to/foo.tar.gz
# Fill snippet with multiple values
$ snippet -t archive/extract-tgz /path/to/foo.tar.gz /path/to/bar.tar.gz
tar -xvf /path/to/foo.tar.gz
tar -xvf /path/to/bar.tar.gz
# Fill snippet with multiple values while using repeatable placeholders (e.g. <file...>)
$ snippet -f "tar -czvf <archive> <file...>" /path/to/foo.tar file=foo bar
tar -czvf /path/to/foo.tar.gz foo bar
# Using presets (e.g. '<datetime>' to include current datetime)
$ snippet -f "tar -czvf '<datetime>.tar.gz' <file...>" file=foo bar
tar -czvf 20770413000000.tar.gz foo bar
# Import values from file
$ cat <<EOF > files.txt
foo
bar
EOF
$ snippet -f "tar -czvf '<datetime>.tar.gz' <file...>" file:files.txt
tar -czvf 20770413000000.tar.gz foo bar
# Using optionals
$ snippet -f "python3 -m http.server[ --bind<lhost>][ <lport>]"
python3 -m http.server
$ snippet -f "python3 -m http.server[ --bind<lhost>][ <lport>]" lport=4444
python3 -m http.server 4444
# Using defaults
$ snippet -f "python3 -m http.server[ --bind<lhost>] <lport=8000>"
python3 -m http.server 8000
# Using codecs
$ snippet -f "tar -czvf <archive|squote> <file:squote...>" /path/to/foo.tar file=foo bar
tar -czvf '/path/to/foo.tar.gz' 'foo' 'bar'
```
## Setup
```
pip3 install snippet-cli
```
To enable bash-completion you might add following line to your .bashrc:
```bash
eval "$(register-python-argcomplete3 snippet)"
```
## Advanced usage
1. [Assigning data to placeholders](#Assigning-data-to-placeholders)
1. [Using positional arguments](#Using-positional-arguments)
2. [Using environment variables](#Using-environment-variables)
3. [Using presets](#Using-presets)
2. [Using string formats](#Using-string-formats)
1. [Using on-the-fly transformation](#Using-the---format-string-argument)
2. [Using input from a pipe](#Using-input-from-a-pipe)
3. [Using templates](#Using-templates)
4. [Using defaults](#Using-defaults)
5. [Using optionals](#Using-optionals)
6. [Using codecs](#Using-codecs)
3. [Executing commands](#Executing-commands)
4. [See also](#See-also)
### Assigning data to placeholders
To assign data to a placeholder you have several options:
#### Using positional arguments
The most straight forward way of assigning data to a placeholder is to use positional arguments:
```
$ snippet -f "echo 'hello <arg1>';" snippet
echo 'hello snippet';
```
To assign multiple values to a specific placeholder you need to explicitly declare the placeholder to which the
value should be assigned to:
```
$ snippet -f "echo '<arg1> <arg2>';" hello arg2=snippet world
echo 'hello snippet';
echo 'hello world';
```
#### Using input files
Values can be directly imported from a file:
```
$ cat <<EOF > input.txt
world
universe
EOF
$ snippet -f "echo 'hello <arg1>';" arg1:input.txt
echo 'hello world';
echo 'hello universe';
```
#### Using environment variables
```snippet``` evaluates environment variables and assigns data to any unset
placeholder. To avoid running into conflict with other environment variables ```snippet``` only evaluates
lower-case variable names:
```
$ export arg1=snippet
$ snippet -f "echo 'hello <arg1>';"
echo 'hello snippet';
```
To assign multiple values to a placeholder following syntax must be used:
```
$ export arg1="\('snippet' 'world'\)"
$ snippet -f "echo 'hello <arg1>';"
echo 'hello snippet';
echo 'hello world';
```
Note that positional arguments may override the evaluation of environment variables:
```
$ export arg1=snippet
$ snippet -f "echo 'hello <arg1>';" world
echo 'hello world';
```
#### Using presets
```snippet``` ships with a customizable set of preset placeholders which can be
directly used in your format string
(see ```.snippet/snippet_profile.py``` for more information). Preset placeholders may have constant
but also dynamically generated values assigned to them:
```
$ snippet -f "echo '<datetime>';"
echo '20200322034102';
```
### Using string formats
To use string formats you have several options:
#### Using the --format-string argument
If you read the previous section you already know the ```-f | --format-string``` argument:
```
$ snippet -f "echo 'hello snippet';"
echo 'hello snippet';
```
#### Using input from a pipe
Another option to set the string format is by using a pipe:
```
$ echo "echo 'hello snippet'" | snippet
echo 'hello snippet';
```
#### Using templates
```snippet``` allows you to import format strings from a file by using the ```-t | --template``` argument.
There are two ways of creating a template:
1. Create a file with the ```.snippet``` extension:
```
$ echo -n "echo 'hello, <arg>!'" > example.snippet
$ snippet -t example.snippet world!
```
2. Create a template using the ```-e | --edit``` argument:
```
# Create a template called example with the specified string format
$ snippet -e example -f "echo 'hello, <arg>!'"
# Open vim to edit or add a new template
$ snippet -e example world!
# Use the template
$ snippet -t example world!
```
If you have bash-completion enabled you can press ```<TAB>``` twice to autocomplete
template names.
In addition the ```-t | --template``` argument will open an interactive search prompt
when the specified template name was not found.
To list all available templates you can use the ```--list-templates```
parameter.
#### Using codecs
```snippet``` supports simple string transformation. A list of available codecs can be viewed by using the
```--list-codecs``` argument.
To transform a placeholder use the ```<PLACEHOLDER[|CODEC[:ARGUMENT] ...]>``` format:
```
$ snippet -f "<arg|b64>" "hello snippet"
aGVsbG8gcmV2YW1w
$ snippet -f "<arg> <arg|b64|b64>" "hello snippet"
hello snippet YUdWc2JHOGdjbVYyWVcxdw==
$ snippet -f "<arg...|join:', '>!" arg=hello snippet
hello, snippet!
```
#### Using defaults
```snippet``` supports specifying default values for your placeholders:
```
$ snippet -f "<arg1> <arg2='default'>" hello
hello default
```
#### Using optionals
```snippet``` supports specifying optional parts in the string format by surrounding them with
square-brackets:
```
$ snippet -f "<arg1> [<arg2>]" hello snippet
hello snippet
$ snippet -f "<arg1> [<arg2>]" hello
hello
$ snippet -f "<arg> [my <arg2='snippet'>]" hello
hello my snippet
$ snippet -f "<arg> [my <arg2='snippet'>]" hello arg2=
hello
```
If you need square-brackets to be part of the string format you need to
escape them accordingly:
```
$ snippet -f "\[<arg>\]" hello
[hello]
```
#### Using repeatables
If you specify multiple values for placeholders `snippet` will print all possible permutations.
Since this is not always the thing you wanna do `snippet` allows marking placeholders as repeatable.
This is done by placing three dots at the end of a placeholder. By default arguments which are
associated with a repeatable placeholder are separated by space.
To specify a custom character sequence you may use the `join` codec:
```
$ snippet -f "<arg1>" hello world
hello
world
$ snippet -f "<arg1...>" hello world
hello world
$ snippet -f "<arg1...|join:','>" hello world
hello,world
```
### Executing commands
```snippet``` can be used to easily execute alternating commands in sequence:
```
$ snippet -f "echo 'hello <arg1>';" arg1=snippet world | bash
hello world
hello snippet
```
Using ```xargs``` the resulting commands can also be executed in parallel:
```
snippet -f "echo 'hello <arg1>';" arg1=snippet arg1=world | xargs --max-procs=4 -I CMD bash -c CMD
hello world
hello snippet
```
## See also
To make the most out of this tool you might also consider to look into the following projects:
* [bgl](https://github.com/bytebutcher/bgl) - manage global bash environment variables
Raw data
{
"_id": null,
"home_page": "https://github.com/bytebutcher/snippet",
"name": "snippet-cli",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "bytebutcher",
"author_email": "thomas.engel.web@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/44/e7/5b4a901344097382d25255f3bd7dc070b3dd3414920ab573c49f16b0f935/snippet-cli-2.1.0.tar.gz",
"platform": null,
"description": "# snippet\n\n```snippet``` allows you to create, view and use snippets on the command-line.\n\n## Usage\n\n\n\n```\n# Add a new snippet to the database\n$ snippet -e archive/extract-tgz -f 'tar -xzvf <archive>'\n\n# Edit a snippet (will open vim)\n$ snippet -e archive/extract-tgz\n\n# Search and use a snippet which include the term \"extract\" (will open fzf)\n$ snippet -t extract\n\n# Fill snippet with a value\n$ snippet -t archive/extract-tgz /path/to/foo.tar.gz\ntar -xvf /path/to/foo.tar.gz\n\n# Fill snippet with multiple values\n$ snippet -t archive/extract-tgz /path/to/foo.tar.gz /path/to/bar.tar.gz\ntar -xvf /path/to/foo.tar.gz\ntar -xvf /path/to/bar.tar.gz\n\n# Fill snippet with multiple values while using repeatable placeholders (e.g. <file...>)\n$ snippet -f \"tar -czvf <archive> <file...>\" /path/to/foo.tar file=foo bar\ntar -czvf /path/to/foo.tar.gz foo bar\n\n# Using presets (e.g. '<datetime>' to include current datetime)\n$ snippet -f \"tar -czvf '<datetime>.tar.gz' <file...>\" file=foo bar\ntar -czvf 20770413000000.tar.gz foo bar\n\n# Import values from file\n$ cat <<EOF > files.txt\nfoo\nbar\nEOF\n$ snippet -f \"tar -czvf '<datetime>.tar.gz' <file...>\" file:files.txt\ntar -czvf 20770413000000.tar.gz foo bar\n\n# Using optionals\n$ snippet -f \"python3 -m http.server[ --bind<lhost>][ <lport>]\"\npython3 -m http.server\n$ snippet -f \"python3 -m http.server[ --bind<lhost>][ <lport>]\" lport=4444\npython3 -m http.server 4444\n\n# Using defaults\n$ snippet -f \"python3 -m http.server[ --bind<lhost>] <lport=8000>\"\npython3 -m http.server 8000\n\n# Using codecs\n$ snippet -f \"tar -czvf <archive|squote> <file:squote...>\" /path/to/foo.tar file=foo bar\ntar -czvf '/path/to/foo.tar.gz' 'foo' 'bar'\n```\n\n## Setup\n\n```\npip3 install snippet-cli\n```\n\nTo enable bash-completion you might add following line to your .bashrc:\n```bash\neval \"$(register-python-argcomplete3 snippet)\"\n```\n\n## Advanced usage\n\n1. [Assigning data to placeholders](#Assigning-data-to-placeholders)\n 1. [Using positional arguments](#Using-positional-arguments)\n 2. [Using environment variables](#Using-environment-variables)\n 3. [Using presets](#Using-presets)\n2. [Using string formats](#Using-string-formats)\n 1. [Using on-the-fly transformation](#Using-the---format-string-argument)\n 2. [Using input from a pipe](#Using-input-from-a-pipe)\n 3. [Using templates](#Using-templates)\n 4. [Using defaults](#Using-defaults)\n 5. [Using optionals](#Using-optionals)\n 6. [Using codecs](#Using-codecs)\n3. [Executing commands](#Executing-commands)\n4. [See also](#See-also)\n\n\n### Assigning data to placeholders\nTo assign data to a placeholder you have several options:\n\n#### Using positional arguments\nThe most straight forward way of assigning data to a placeholder is to use positional arguments:\n\n```\n$ snippet -f \"echo 'hello <arg1>';\" snippet\necho 'hello snippet';\n```\n\nTo assign multiple values to a specific placeholder you need to explicitly declare the placeholder to which the\nvalue should be assigned to:\n```\n$ snippet -f \"echo '<arg1> <arg2>';\" hello arg2=snippet world\necho 'hello snippet';\necho 'hello world';\n```\n\n#### Using input files\n\nValues can be directly imported from a file:\n```\n$ cat <<EOF > input.txt\nworld\nuniverse\nEOF\n$ snippet -f \"echo 'hello <arg1>';\" arg1:input.txt\necho 'hello world';\necho 'hello universe';\n```\n\n#### Using environment variables\n\n```snippet``` evaluates environment variables and assigns data to any unset \nplaceholder. To avoid running into conflict with other environment variables ```snippet``` only evaluates \nlower-case variable names:\n```\n$ export arg1=snippet\n$ snippet -f \"echo 'hello <arg1>';\"\necho 'hello snippet';\n```\nTo assign multiple values to a placeholder following syntax must be used:\n```\n$ export arg1=\"\\('snippet' 'world'\\)\"\n$ snippet -f \"echo 'hello <arg1>';\"\necho 'hello snippet';\necho 'hello world';\n```\n\nNote that positional arguments may override the evaluation of environment variables:\n```\n$ export arg1=snippet\n$ snippet -f \"echo 'hello <arg1>';\" world\necho 'hello world';\n```\n\n#### Using presets\n\n```snippet``` ships with a customizable set of preset placeholders which can be \ndirectly used in your format string \n(see ```.snippet/snippet_profile.py``` for more information). Preset placeholders may have constant \nbut also dynamically generated values assigned to them:\n```\n$ snippet -f \"echo '<datetime>';\" \necho '20200322034102';\n```\n\n### Using string formats\n\nTo use string formats you have several options:\n\n#### Using the --format-string argument\n\nIf you read the previous section you already know the ```-f | --format-string``` argument:\n\n```\n$ snippet -f \"echo 'hello snippet';\"\necho 'hello snippet';\n```\n\n#### Using input from a pipe\n\nAnother option to set the string format is by using a pipe:\n```\n$ echo \"echo 'hello snippet'\" | snippet\necho 'hello snippet';\n```\n\n#### Using templates\n\n```snippet``` allows you to import format strings from a file by using the ```-t | --template``` argument.\n\nThere are two ways of creating a template:\n\n1. Create a file with the ```.snippet``` extension:\n```\n$ echo -n \"echo 'hello, <arg>!'\" > example.snippet\n$ snippet -t example.snippet world!\n```\n\n2. Create a template using the ```-e | --edit``` argument:\n```\n# Create a template called example with the specified string format\n$ snippet -e example -f \"echo 'hello, <arg>!'\"\n# Open vim to edit or add a new template\n$ snippet -e example world!\n# Use the template\n$ snippet -t example world!\n```\n\nIf you have bash-completion enabled you can press ```<TAB>``` twice to autocomplete \ntemplate names. \n\nIn addition the ```-t | --template``` argument will open an interactive search prompt \nwhen the specified template name was not found.\n\nTo list all available templates you can use the ```--list-templates```\nparameter.\n\n#### Using codecs\n\n```snippet``` supports simple string transformation. A list of available codecs can be viewed by using the\n```--list-codecs``` argument.\n\nTo transform a placeholder use the ```<PLACEHOLDER[|CODEC[:ARGUMENT] ...]>``` format:\n```\n$ snippet -f \"<arg|b64>\" \"hello snippet\"\naGVsbG8gcmV2YW1w\n$ snippet -f \"<arg> <arg|b64|b64>\" \"hello snippet\"\nhello snippet YUdWc2JHOGdjbVYyWVcxdw==\n$ snippet -f \"<arg...|join:', '>!\" arg=hello snippet\nhello, snippet!\n```\n\n#### Using defaults\n\n```snippet``` supports specifying default values for your placeholders:\n\n```\n$ snippet -f \"<arg1> <arg2='default'>\" hello\nhello default\n```\n\n#### Using optionals\n\n```snippet``` supports specifying optional parts in the string format by surrounding them with \nsquare-brackets:\n```\n$ snippet -f \"<arg1> [<arg2>]\" hello snippet\nhello snippet\n$ snippet -f \"<arg1> [<arg2>]\" hello\nhello\n$ snippet -f \"<arg> [my <arg2='snippet'>]\" hello\nhello my snippet\n$ snippet -f \"<arg> [my <arg2='snippet'>]\" hello arg2=\nhello\n```\n\nIf you need square-brackets to be part of the string format you need to\nescape them accordingly:\n\n```\n$ snippet -f \"\\[<arg>\\]\" hello\n[hello]\n```\n\n#### Using repeatables\n\nIf you specify multiple values for placeholders `snippet` will print all possible permutations.\nSince this is not always the thing you wanna do `snippet` allows marking placeholders as repeatable.\nThis is done by placing three dots at the end of a placeholder. By default arguments which are\nassociated with a repeatable placeholder are separated by space. \nTo specify a custom character sequence you may use the `join` codec:\n\n```\n$ snippet -f \"<arg1>\" hello world\nhello\nworld\n$ snippet -f \"<arg1...>\" hello world\nhello world\n$ snippet -f \"<arg1...|join:','>\" hello world\nhello,world\n``` \n\n### Executing commands\n\n```snippet``` can be used to easily execute alternating commands in sequence:\n```\n$ snippet -f \"echo 'hello <arg1>';\" arg1=snippet world | bash\nhello world\nhello snippet\n```\n\nUsing ```xargs``` the resulting commands can also be executed in parallel:\n```\nsnippet -f \"echo 'hello <arg1>';\" arg1=snippet arg1=world | xargs --max-procs=4 -I CMD bash -c CMD\nhello world\nhello snippet\n```\n\n## See also\n\nTo make the most out of this tool you might also consider to look into the following projects:\n* [bgl](https://github.com/bytebutcher/bgl) - manage global bash environment variables\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "An advanced snippet manager for the command-line.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/bytebutcher/snippet"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "52a23d2e92856e55c7567a4f890b6f83a4dd4b3499beddfe76bacd4c62c64323",
"md5": "f5e9836d913e5d8c56152305de5e6ae0",
"sha256": "1fa012319bcc2f4373f0e247f1eb024ff927f2bd87ae150b75c2bb48824ac43f"
},
"downloads": -1,
"filename": "snippet_cli-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5e9836d913e5d8c56152305de5e6ae0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 43365,
"upload_time": "2023-11-22T23:23:12",
"upload_time_iso_8601": "2023-11-22T23:23:12.827161Z",
"url": "https://files.pythonhosted.org/packages/52/a2/3d2e92856e55c7567a4f890b6f83a4dd4b3499beddfe76bacd4c62c64323/snippet_cli-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44e75b4a901344097382d25255f3bd7dc070b3dd3414920ab573c49f16b0f935",
"md5": "cc5f1b676adb0336e747b3e9360f6f81",
"sha256": "7bdb5ba5e974ee082133b58d70b076af1e2c03d75c2b0ee82aa551629f908dc8"
},
"downloads": -1,
"filename": "snippet-cli-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cc5f1b676adb0336e747b3e9360f6f81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37092,
"upload_time": "2023-11-22T23:23:15",
"upload_time_iso_8601": "2023-11-22T23:23:15.026849Z",
"url": "https://files.pythonhosted.org/packages/44/e7/5b4a901344097382d25255f3bd7dc070b3dd3414920ab573c49f16b0f935/snippet-cli-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-22 23:23:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bytebutcher",
"github_project": "snippet",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "snippet-cli"
}
JSON
