Awesome

shinclude

Include file contents or ouptut of shell commands in a code/markup comments

         █████       ███                      ████                 █████
        ░░███       ░░░                      ░░███                ░░███
  █████  ░███████   ████  ████████    ██████  ░███  █████ ████  ███████   ██████
 ███░░   ░███░░███ ░░███ ░░███░░███  ███░░███ ░███ ░░███ ░███  ███░░███  ███░░███
░░█████  ░███ ░███  ░███  ░███ ░███ ░███ ░░░  ░███  ░███ ░███ ░███ ░███ ░███████
 ░░░░███ ░███ ░███  ░███  ░███ ░███ ░███  ███ ░███  ░███ ░███ ░███ ░███ ░███░░░
 ██████  ████ █████ █████ ████ █████░░██████  █████ ░░████████░░████████░░██████
░░░░░░  ░░░░ ░░░░░ ░░░░░ ░░░░ ░░░░░  ░░░░░░  ░░░░░   ░░░░░░░░  ░░░░░░░░  ░░░░░░

• INSTALL
  • Project specific
  • System-wide
  • Home directory
• OPTIONS
  • -h, --help
  • -V, --version
  • -i, --inplace
  • -p, --shinclude-path PATH
  • -c, --comment-style COMMENT_STYLE
  • -cs, --comment-start COMMENT_START
  • -csa, --comment-start-alternative COMMENT_START_ALTERNATIVE
  • -ce, --comment-end COMMENT_END
  • -d, --info
  • -dd, --debug
  • -ddd, --trace
• BLOCK DIRECTIVES
  • EVAL
    • Options
      • -w, --wrap BEFORE AFTER
  • INCLUDE
  • RENDER
  • MARKDOWN-TOC
    • $MARKDOWN_TOC_INDENT
    • $HEADING_REGEX
    • Heading-to-Link algorithm
  • BANNER
    • Options
      • -f, --font FONT
      • -i, --indent INDENT
      • -w, --wrap BEFORE AFTER
      • -b, --blurb TEXT
      • -L, --license TEXT
      • -C, --copyright TEXT
• COMMENT STYLES
  • xml
  • markdown
  • pound
  • slashstar
  • doubleslash
  • doublequote
  • doubleslashbang
  • Vim fold

INSTALL

Project specific

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

System-wide

To install system-wide (/usr/local/bin/shinclude):

make install

Home directory

To install to your home directory ($HOME/.local/bin/shinclude):

make install PREFIX=$HOME/.local

OPTIONS

-h, --help

help

-V, --version

Show version

-i, --inplace

Edit the file in-place

-p, --shinclude-path PATH

Add path to path to look for INCLUDE and RENDER.

Can be repeated to add multiple paths.

Default: ("$PWD")

-c, --comment-style COMMENT_STYLE

Comment style. See COMMENT STYLES.

Use -c list to get a list of available styles.

-cs, --comment-start COMMENT_START

 Comment start. Overrides language-specific comment start.

See COMMENT STYLES.

-csa, --comment-start-alternative COMMENT_START_ALTERNATIVE

 Alternative comment start. Overrides language-specific comment start.

Useful for vim folds

See COMMENT STYLES.

-ce, --comment-end COMMENT_END

 Comment end. Overrides language-specific comment end.

See COMMENT STYLES.

-d, --info

Enable debug logging ($LOGLEVEL=1)

-dd, --debug

Enable trace logging ($LOGLEVEL=2).

-ddd, --trace

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>

BLOCK DIRECTIVES

EVAL

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

Options

-w, --wrap BEFORE AFTER

Wrap in lines. E.g -w '<pre>' '</pre'

INCLUDE

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

RENDER

Renders a file to markdown using a shrender.

Runs on first pass

MARKDOWN-TOC

(source, test)

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

$MARKDOWN_TOC_INDENT

String to indent a single level. Default:

$HEADING_REGEX

Regex used to detect and tokenize headings.

Default: ^(##+)\s*(.*)

Heading-to-Link algorithm

Replace markdown links in heading with just the link text Link text: Remove [ ] Indentation: Concatenate $MARKDOWN_TOC_INDENT times the number of leading #- 2

BANNER

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

Options

-f, --font FONT

Specify font. See /usr/share/figlet for a list of fonts.

-i, --indent INDENT

Specify indent. Example: -i " ", -i ' '

-w, --wrap BEFORE AFTER

Wrap in lines. E.g -w '<pre>' '</pre'

-b, --blurb TEXT

Text to append, e.g. license information. Example: `-b 'Licensed under MIT'

-L, --license TEXT

License of the file. Example -L MIT

-C, --copyright TEXT

Copyright of the file. Example -L "2016, John Doe

COMMENT STYLES

xml

Comment style:

  <!-- BEGIN-... -->
  <!-- END-... -->

File Extensions:

• .html
• *.xml

markdown

Comment style:

[]: BEGIN-...
[]: END-...

Extensions:

• *.ronn
• *.md

pound

Comment style:

# BEGIN-...
# END-...

Extensions:

• *.sh
• *.bash
• *.zsh
• *.py
• *.pl
• *.PL
• *.coffee

slashstar

Comment style:

/* BEGIN-... */
/* END-... */

File Extensions:

• *.cpp
• *.cxx
• *.java

doubleslash

File Extensions:

// BEGIN-...
// END-...

File Extensions:

• *.c
• *.js

doublequote

Comment style:

" BEGIN-...
" END-...

File Extensions:

• *.vim

doubleslashbang

Comment style:

//! BEGIN-...
//! END-...

Extensions:

• *.jade
• *.pug

Vim fold

Comment style:

#{{{ BEGIN-...
#}}} END-...