Skip to content

Components

Jump to bottom
dobragab edited this page Apr 29, 2017 · 6 revisions

Components

ccsh is not a simple executable like bash. It consists of four main front-ends, and two other components for developers, which are described in this page.

Front-ends are:

Other components

  • Tests (test folder)
  • Samples (sample folder)

Tests are standard GoogleTest suites of the scripting library. See Examples page for samples.

Scripting library

This is the engine of ccsh. It is written and usable in standard C++11, provides headers to include and a shared object to link.

Note: All ccsh packages should include a .pc file for pkg-config support.

sample.cpp:

#include <ccsh/ccsh.hpp>
int main()
{
    ccsh::shell("ls");
}
$ g++ `pkg-config --cflags --libs ccsh` sample.cpp -o sample
$ ./sample

GCC 4.8+ and Clang 3.5+ are supported.

See Running commands for scripting documentation.

Compiler helper

If you want to use ccsh as a small, standalone script instead of a shell / python script, you may find the three-step editing - compiling - running development process annoying. This component merges two steps of this (compiling and running) into one, using shebang.

sample.cpp:

#!/usr/bin/ccshc -pedantic

#include <iostream>

int main(int argc, const char* const* argv)
{
    std::cout << "Got " << argc-1 << " arguments." << std::endl;
}
$ ./sample.cpp example-arg1 example-arg2
Got 2 arguments.

Shebang specifies the ccshc executable, that compiles and runs your program. The compiler is either $(CXX), or (if CXX environment variable is not specified) /usr/bin/c++. Its arguments must be somewhat GCC-compatible.

The arguments specified after the executable path will be passed to the compiler. The arguments you pass in the command line are passed to your program. If you specify non-GCC arguments in shebang, ccshc may misbehave.

The -c switch is treated specially. If you specify this in shebang, ccshc will compile your code, but won't run it. This is mostly useful for static syntax checking without trying out your code.

Note: All ccsh packages should place the most recent version of ccshc to /usr/bin/ccshc.

Interactive shell

This is a bash-like interactive C++ "interpreter", namely ccsh executable. It might come useful if you want to play around ccsh, but not intended for scripting or everyday use. It uses cling as a backend, which is a C++ Just-In-Time compiler, it gives you a prompt and compiles your code line-by-line.

ccsh does nothing more than loading the scripting library into cling, and loading your ccshrc.hpp. That is either /etc/ccsh/ccshrc.hpp or ~/.ccshrc.hpp. In addition to standard ccsh features, you can customize ccsh prompt as shown in the default ccshrc.hpp.

See cling for more documentation.

Wrappers for native binaries

As you will see in Running commands page, specifying arguments as strings is uncomfortable, and lacks the static type-safe checking that C++ could provide. In addition to that, binaries' arguments are highly inconsistent. Wrappers of ccsh attempt to translate program arguments and switches into constructors and functions. So instead of

shell("ls", {"-l", "--color=auto"});

you may write

ls{}.l().color(ls::auto_);

Function names are intended to be completely consistent, following this pattern:

  • Beginning dashes are ignored.
  • Single-character arguments cannot be specified together, e.g.-la means .l().a(); and .la() is invalid.
  • -l is translated to .l()
  • --file-type is translated to .file_type(), all non-alphanumeric characters in the middle of a switch are replaced with underscore (_).
  • -1 is translated to .one(), when the possible numbers are closed-set (e.g. -2 is not allowed, like ls).
  • -n, where n is any number, is translated to the function call operator with a negative argument.
  • +n, where n is any number, is translated to the function call operator with a positive argument.
  • Switches with more than one arguments are trivially translated to functions with multiple arguments. (e.g. +1:8 means (1, 8))
  • If the argument name happens to be a C++ keyword, it is extended with a trailing underscore.

Arguments with closed-set values are translated to nested enums, and functions expect enum values as arguments.

  • ls --color=auto is translated to ls{}.color(ls::auto_).
  • If the enum value happens to be a C++ keyword, it is extended with a trailing underscore (like auto_).

These functions may throw exceptions if the format is non-conforming to the target command.

Bad thing is, we haven't found a stable way to parse all documentations of all commands and generating functions, so these have to be translated manually. Thus these are still under construction.

These wrappers are organized into folders within ccsh root include folder with the following conventions:

  • For each folder, there is a folder.hpp which includes all files from folder. Individual command wrappers might be included as well.
  • Except community, those must be included individually. Anyone can install ccsh wrappers for any command.
  • Every wrapper is header-only, no additional linking required.

Currently core is the only reserved folder.

See Contributing page for more information.

Clone this wiki locally