# -*- coding: utf-8 -*-
'''manually define and add shell builtins into the store
unfortunately the bash section for builtins isn't written in a way
explainshell can understannd, so we have to resort to manually
writing these down and adding them.'''
import textwrap
from explainshell import store, config
sp = store.paragraph
so = store.option
sm = store.manpage
BUILTINS = {}
def _add(names, synopsis, options):
name = names[0]
# hack: fake a source man page (this breaks the outgoing links from
# explainshell, oh well)
names.append('bash-%s' % name)
BUILTINS[name] = sm('bash-%s.1.gz' % name, name, synopsis, options, [(name, 20) for name in names])
_add([':'], 'the command does nothing', [so(sp(0, '''No effect; the command does nothing beyond expanding arguments and performing any specified redirections. A zero
exit code is returned.''', '', True), [], [], False, True, False)])
source = textwrap.dedent(''' . filename [arguments]
source filename [arguments]
Read and execute commands from filename in the current shell environment and return the exit status of
the last command executed from filename. If filename does not contain a slash, filenames in PATH are used
to find the directory containing filename. The file searched for in PATH need not be executable. When
bash is not in posix mode, the current directory is searched if no file is found in PATH. If the
sourcepath option to the shopt builtin command is turned off, the PATH is not searched. If any
arguments are supplied, they become the positional parameters when filename is executed. Otherwise
the positional parameters are unchanged. The return status is the status of the last command exited within
the script (0 if no commands are executed), and false if filename is not found or cannot be read.''')
_add(['source', '.'], 'read and execute commands in the current shell', [so(sp(0, source, '', True), [], [], False, True, False)])
_add(['break'], 'exit from within a for, while, until, or select loop',
[so(sp(0, '''If n is specified, break n levels. n must be ≥ 1. If n is greater than the number of enclosing loops, all enclosing loops are exited. The return value is 0 unless n is not greater than or equal to 1.''', '', True), [], [], False, True, False)])
_add(['history'], 'display the command history list with line numbers',
[so(sp(0, '''history [n]
history -c
history -d offset
history -anrw [filename]
history -p arg [arg ...]
history -s arg [arg ...]
With no options, display the command history list with line numbers. Lines listed with a * have been modified.
An argument of n lists only the last n lines. If the shell variable HISTTIMEFORMAT is set
and not null, it is used as a format string for strftime(3) to display the time stamp associated with each
displayed history entry. No intervening blank is printed between the formatted time stamp and the history
line. If filename is supplied, it is used as the name of the history file; if not, the value of
HISTFILE is used.''', '', True), [], [], False, True, False),
so(sp(1, '-c Clear the history list by deleting all the entries.', '', True), ['-c'], [], False, False, False),
so(sp(2, textwrap.dedent(''' -d offset
Delete the history entry at position offset.'''), '', True), ['-d'], [], 'offset', False, False),
so(sp(3, textwrap.dedent(''' -a Append the ``new'' history lines (history lines entered since the beginning of the current bash session)
to the history file.'''), '', True), ['-a'], [], False, False, False),
so(sp(4, textwrap.dedent(''' -n Read the history lines not already read from the history file into the current history list. These are
lines appended to the history file since the beginning of the current bash session.'''), '', True), ['-n'], [], False, False, False),
so(sp(5, textwrap.dedent(''' -r Read the contents of the history file and append them to the current history list.'''), '', True), ['-r'], [], False, False, False),
so(sp(6, textwrap.dedent(''' -w Write the current history list to the history file, overwriting the history file's contents.'''), '', True), ['-w'], [], 'filename', False, False),
so(sp(7, textwrap.dedent(''' -p Perform history substitution on the following args and display the result on the standard output.
Does not store the results in the history list. Each arg must be quoted to disable normal history expansion.'''), '', True), ['-p'], [], 'arg', True, False),
so(sp(8, textwrap.dedent(''' -s Store the args in the history list as a single entry. The last command in the history list is
removed before the args are added.'''), '', True), ['-s'], [], 'arg', False, False)])
if __name__ == '__main__':
import logging.config
logging.config.dictConfig(config.LOGGING_DICT)
s = store.store('explainshell', config.MONGO_URI)
for m in BUILTINS.values():
s.addmanpage(m)