A shell DSL and function repository/manager for *nix operating systems written in POSIX shell.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Francesco Palumbo 564bf101ce added rr with sync 2 months ago
enabled added rr with sync 2 months ago
funcs added rr with sync 2 months ago
installer added rr with sync 2 months ago
COPYING version 0.2.2, changed license from MIT to GPL3 1 year ago
MANIFEST.bz2 added rr with sync 2 months ago
MANIFEST.bz2.SHA512 added rr with sync 2 months ago
README renamed serve option to share 10 months ago
shuman new entitle alias 4 months ago

README


^--__-_-^-_-^-_-^-__-___-__-_ .
Shell for Humans
_-^-_-^-_-^-_-__-__-_ .

A shell DSL and function repository/manager for *nix operating systems.
(inspired by Ruby and Elixir)


shuman (itself a shell function) is a collection of shell functions made (mainly for fun)
to simplify some common tasks. It also works like a 'function manager' as you can
create/edit/enable/disable/install/remove functions, save/share them on your server
and install all of this remotely from another machine using its builtin web server.
It can be installed as a normal user, and can replicate itself with new functions
of yours.


=======================================
Overview examples of included functions
=======================================

Do computations and for each digit do something:
> echo 12 45 | add 9 | mul 2 | chars | each ch puts digit is ch

Pass arguments through the pipeline:
> echo cat | pass of mine | words | wc -l

Sum all words of ls output:
> ls | words | map wc -c | add

Open the output of ls in Firefox as JSON:
> ls -l | get 2, | insert perms hlinks user group size month day time/year filename |\
> pivot | tojson | tofile list.json | asargs firefox


============
Installation
============

-------
Fastest
-------

> git clone https://codeberg.org/phranz/shuman ~/.shuman && . ~/.shuman/shuman


---------------
Custom home dir
---------------

> git clone https://codeberg.org/phranz/shuman
> cd /path/to/cloned/repo
> . ./shuman
> shuman home .


-----------
Without git
-----------
(Substitute xxx with desired version)

> wget https://codeberg.org/phranz/shuman/src/branch/master/installer/shuman-xxx-installer.sh &&
> wget https://codeberg.org/phranz/shuman/src/branch/master/installer/shuman-xxx-installer.sh.SHA512 &&
> sha512sum -c shuman-xxx-installer.sh.SHA512 &&
> sh shuman-xxx-installer.sh
> . ~/.shuman/shuman


===============================================================
Loading shuman with profile (assuming SHUMAN_HOME is ~/.shuman)
===============================================================

> echo ". ~/.shuman/shuman" >> ~/.bash_profile
> echo "shuman home ~/.shuman" >> ~/.bash_profile


=================
Usage and options
=================

shuman <option> [<subopts>]


list lists available functions and shows enabled ones
marked with an asterisk.

search <func> search by function name and shows enabled ones
marked with an asterisk.

new <func> creates a new function named <func> with default template.

edit [<func>] shortcut to edit a function named <func>; without
arguments edits shuman itself and sources it.

rename <func1> <func2> shortcut to rename a function; renames <func1> to <func2>.

remove <func> deletes function named <func> (warning, removal is permanent).

enable [<func>] enable a function named <func> or all functions.

disable [<func>] disable a function named <func> or all functions.

clean remove dead links relative to moved/renamed/dead functions.

show [<func>] shows contents of function named <func> or of shuman itself.

install <url> shortcut to download and install an externally provided
function at <url> (be careful using externally provided functions!).
You should always view the downloaded function code
(manually or with 'shuman show') before enabling, beware.

lang [<lang>] get (without arguments) or set $SHUMAN_LANG variable.
Option purpose is to show descriptions and help texts in a preferred
language (if the function has support for them);
default language is english.

home [<dir>] get (without arguments) or set $SHUMAN_HOME variable;
this variable is mandatory, and must be set either
with this (shortcut) option or manually.

regen extracts metadata from each function (see function
metadata below) and uses that to generate the MANIFEST file.

update downloads and updates the MANIFEST file from $SHUMAN_URL
overwriting the current one.

upgrade [<function>] upgrades shuman and functions, installing new ones,
and leaving custom functions created locally are unmodified.
If <function> is given, tries to upgrade only <function>.

replicate [<new dir>] creates a self-extracting installer (in $SHUMAN_HOME/installer)
with current content, optionally using <new dir> as the new
($SHUMAN_HOME). In addition, if <new dir> is specified,
this option immediately extracts freshly created archive
and changes current SHUMAN_HOME to <new dir>.
NOTE: this calls regen and overwrites MANIFEST file.

share [<port>] runs a web server (requires Ruby or Python) on <port>
(default 8080) to share your copy of shuman.

help [<func>] get general or function specific help.



=========
Variables
=========

SHUMAN_HOME main shuman directory (installation defaults to ~/.shuman).

SHUMAN_URL shuman remote URL (like a remote SHUMAN_HOME).

SHUMAN_LANG preferred language, default english.

SHUMAN_EDITOR editor to use when editing/creating functions.

SHUMAN_FUNCS_AUTHOR author of freshly created functions used by initial template.

SHUMAN_FUNCS_AUTHOR_EMAIL author's email for freshly created functions
used by initial template.

SHUMAN_FUNCS_AUTHOR_LOCATION author's location for freshly created functions
used by initial template.

SHUMAN_FUNCS_LICENSE_TEXT license text for freshly created functions
used by initial template.



=========================================================
Important files and directories (relative to SHUMAN_HOME)
=========================================================

shuman main shuman procedures.

funcs/ available functions.

enabled/ enabled functions (functions not enabled are not sourced).

installer/ location of generated installer.

MANIFEST.bz2 this file holds details about each function; every
line is composed by 3 fields: name, url and SHA512 checksum.
Updating, regenerating or replicating overwrites the original manifest.

COPYING License file.


=======
License
=======

GPL3 (see COPYING)


============================
Enabling/disabling functions
============================

By default, all functions coming with shuman are enabled,
you can check function state/description with:

> shuman list

the output should be like:

[*] add sum given numbers
[*] append appends text after last line
[*] pass usa stdin data as command line arguments
[*] rubystyle use commands with Ruby like syntax

Asterisks indicate that functions are enabled (they are sourced).


===================
Creating a function
===================

You can add new functions by using:

> shuman new myfunc

This will create a new function named myfunc in $SHUMAN_HOME/funcs,
filling it with template text and variables.

These are:

SHUMAN_FUNCS_AUTHOR author of freshly created functions used by initial template.

SHUMAN_FUNCS_AUTHOR_EMAIL author's email for freshly created functions
used by initial template.

SHUMAN_FUNCS_AUTHOR_LOCATION author's location for freshly created functions
used by initial template.

SHUMAN_FUNCS_LICENSE_TEXT license text for freshly created functions
used by initial template.

By default these variables have defaults to my personal data, feel
absolutely free to change it as needed.

After all, an editor will be opened (checks the EDITOR environment variable),
default/fallback is vim.

=================
Function metadata
=================

Every function has some metadata associated with it, like download URL,
description and help text.

These can be specified using a special syntax (always starting with a '#')
inside the file containing the function, and, when creating new functions
with 'shuman new' they will be automatically generated for you by using a default
template.

This special syntax is made of the following directives:

#url <function URL>

the download URL of the function

#<lang>desc <description>

a single line, short description of the function that will be showed
when executing 'shuman list'. <lang> indicates the language of
the description, and this form can be specified multiple times.
For example:

#endesc english description
#itdesc descrizione italiana
... ad so on

shuman defaults to #endesc.

#<lang>help
#<help text>
#<lang>help

a multiline help text encolsed between two #<lang>help directives.
This text will be showed when executing 'shuman help <function>', the
same logic of #<lang>desc apply. shuman defaults to #enhelp


===============================
Installing an external function
===============================

If you want to install an externally provided function located
at a specific URL, you can do it by giving, for example:

> shuman install https://mysite/path/myfunction

shuman will first search for myfunction.SHA512 on that server and
then download myfunction; if an hash is found, it will be used to check
for integrity and then install the function, otherwise shuman will ask
you to confirm the installation of the function.

The installed function is NOT enabled by default.

WARNING! Beware installing function from unknown/untrusted sources!
USE WITH CAUTION!


=============================
Updating shuman and functions
=============================

All functions and shuman itself can be upgraded
(using $SHUMAN_URL) by giving these commands:

> shuman update
> shuman upgrade


==================
Replicating shuman
==================

A local shuman installation can be used to create an custom installer
which can be used to install your customized shuman 'instance' with
your new functions elsewhere and so on.

To be able to do that, shuman has 'replicate' option (see options help).

Usage example:

Create your functions:

> shuman new myfunc1
> shuman new myfunc2

and then run

> shuman replicate

the MANIFEST metadata will be updated with new functions, and an installer
will be created at $SHUMAN_HOME/installer.

Then run (on machine A):

> shuman share

A web server will run on port 8080, exposing the content of your $SHUMAN_HOME.
Then from machine B, you can download the generated installer from machine A:

> wget machine_A_address:8080/installer/shuman-version-installer.sh

And optionally its checksum:

> wget machine_A_address:8080/installer/shuman-version-installer.sh.SHA512

And optionally verify its integrity (recommended):

> sha512sum -c shuman-version-installer.sh.SHA512

And, from machine B, run:

> sh shuman-version-installer.sh

Now you have installed on machine B a custom shared copy
of your shuman located on machine A.

To enable it on new machine:

> . ~/.shuman/shuman


=====
NOTES
=====

I've wrote this program and its 3rd party functions with portability
in mind, and so I tried to use mainly POSIX features,
so it should work under bash, dash, zsh and others.

Please feel free to send me bug reports and comments/ideas at phranz@subfc.net


==============
Special thanks
==============

I would especially like to thank:

Carme
Titina
Pico
Naples
Unix
Louis Pouzin
Douglas McIlroy
Ken Thompson
Patrick Volkerding
Yukihiro Matsumoto
Free software
Free knowledge