Include file contents or ouptut of shell commands in a code/markup comments
█████ ███ ████ █████
░░███ ░░░ ░░███ ░░███
█████ ░███████ ████ ████████ ██████ ░███ █████ ████ ███████ ██████
███░░ ░███░░███ ░░███ ░░███░░███ ███░░███ ░███ ░░███ ░███ ███░░███ ███░░███
░░█████ ░███ ░███ ░███ ░███ ░███ ░███ ░░░ ░███ ░███ ░███ ░███ ░███ ░███████
░░░░███ ░███ ░███ ░███ ░███ ░███ ░███ ███ ░███ ░███ ░███ ░███ ░███ ░███░░░
██████ ████ █████ █████ ████ █████░░██████ █████ ░░████████░░████████░░██████
░░░░░░ ░░░░ ░░░░░ ░░░░░ ░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░░░░ ░░░░░░░░ ░░░░░░
You can just clone the repository and call the shinclude binary.
If you want to use it in your scripts, Makefile or git hooks, use
either the full path to the shinclude script or add it to the
PATH:
export PATH="/path/to/shinclude/repo:$PATH"
./myscript.sh
To install system-wide (/usr/local/bin/shinclude):
make install
To install to your home directory ($HOME/.local/bin/shinclude):
make install PREFIX=$HOME/.local
help
Show version
Edit the file in-place
Add path to path to look for INCLUDE and RENDER.
Can be repeated to add multiple paths.
Default: ("$PWD")
Comment style. See COMMENT STYLES.
Use -c list to get a list of available styles.
Comment start. Overrides language-specific comment start.
See COMMENT STYLES.
Alternative comment start. Overrides language-specific comment start.
Useful for vim folds
See COMMENT STYLES.
Comment end. Overrides language-specific comment end.
See COMMENT STYLES.
Enable debug logging ($LOGLEVEL=1)
Enable trace logging ($LOGLEVEL=2).
Enable trace logging ($LOGLEVEL=2) and print every statement as it is executed.
Included content is fenced by comments that contain
BEGIN-<block-type> and END-<block-type> respectively.
Fencing comments must start at the start of the line.
<block-type> ::= "EVAL" | "INCLUDE" | "RENDER" | "BANNER" | "MARKDOWN-TOC"
<nl> ::= "\n"
<spc> ::= " "
<begin-line> ::= <com-start> <spc> BEGIN-<block-type> <block-arg>+ <spc>? <com-end>?
<end-line> ::= <com-start> <spc> END-<block-type> <spc>? <com-end>?
<directive> ::= <begin-line> <nl> <content-line>* <end-line> <nl>
Evaluates the arguments as a shell expression. BE CAREFUL
EVAL Runs on first pass
# BEGIN-EVAL wc *
# END-EVAL
will be transformed to
# BEGIN-EVAL wc *
21 171 1085 LICENSE
51 106 978 Makefile
290 461 4058 README.md
558 1267 12212 shinclude
275 828 5565 shinclude.1
1723 4100 36080 total
# END-EVAL
Wrap in lines. E.g -w '<pre>' '</pre'
Include data from a file.
INCLUDE runs on first pass.
# BEGIN-INCLUDE LICENSE
# END-INCLUDE
will be transformed to
# BEGIN-INCLUDE LICENSE
The MIT License (MIT)
Copyright (c) 2016 Konstantin Baierer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# END-INCLUDE
Renders a file to markdown using a shrender.
Runs on first pass
Reads in the file and outputs a table of contents of the markdown headings.
Runs on second pass
# First Heading
[rem]: BEGIN-MARKDOWN-TOC
[rem]: END-MARKDOWN-TOC
## Second-Level Heading
will be transformed to (shinclude -cs '[rem]:' -ce '' -)
# First Heading
[rem]: BEGIN-MARKDOWN-TOC
* [First Heading](#first-heading)
* [Second-Level Heading](#second-level-heading)
[rem]: END-MARKDOWN-TOC
## Second-Level Heading
String to indent a single level. Default:
Regex used to detect and tokenize headings.
Default: ^(##+)\s*(.*)
Replace markdown links in heading with just the link text
Link text: Remove [ ]
Indentation: Concatenate $MARKDOWN_TOC_INDENT times the number of leading #- 2
Shows a banner using FIGlet or TOIlet
BANNER Runs on first pass
# BEGIN-BANNER -f standard -w '<pre>' '</pre>' -C '2016 John Doe' foo
# END-BANNER
will be transformed to
# BEGIN-BANNER -f standard -w '<pre>' '</pre>' foo
<pre>
__
/ _| ___ ___
| |_ / _ \ / _ \
| _| (_) | (_) |
|_| \___/ \___/
Copyright (c) 2016 John Doe
</pre>
# END-EVAL
Specify font. See /usr/share/figlet for a list of fonts.
Specify indent. Example: -i " ", -i ' '
Wrap in lines. E.g -w '<pre>' '</pre'
Text to append, e.g. license information. Example: `-b 'Licensed under MIT'
License of the file. Example -L MIT
Copyright of the file. Example -L "2016, John Doe
Comment style:
<!-- BEGIN-... -->
<!-- END-... -->
File Extensions:
.html*.xml
Comment style:
[]: BEGIN-...
[]: END-...
Extensions:
*.ronn*.md
Comment style:
# BEGIN-...
# END-...
Extensions:
*.sh*.bash*.zsh*.py*.pl*.PL*.coffee
Comment style:
/* BEGIN-... */
/* END-... */
File Extensions:
*.cpp*.cxx*.java
File Extensions:
// BEGIN-...
// END-...
File Extensions:
*.c*.js
Comment style:
" BEGIN-...
" END-...
File Extensions:
*.vim
Comment style:
//! BEGIN-...
//! END-...
Extensions:
*.jade*.pug
Comment style:
#{{{ BEGIN-...
#}}} END-...