chewax / Ginseng

Table of Contents

• About the Project
• Getting Started
• Usage
• Roadmap
• Contributing
• License
• Contact

About The Project

This is a lightweight header only library that will help you build REPL tools faster. It is based on the ncurses library. Before proceeding with installation please make sure you have this library installed.

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

1. c++11
2. ncurses

Installation

1. Clone the Ginseng into repo into your libs

git clone https://github.com/chewax/Ginseng.git

Usage

Basic usage.

#include "Ginseng.h"

int main() 
{
	Ginseng repl;
	repl.start();
	return 0;
}

This example will setup a basic REPL tool with empty commands. At this stage you can use commands such as help or exit.

Configuring Delimiter.

You can setup your own delimiter using the first parameter for such thing.

#include "Ginseng.h"

int main() 
{
	Ginseng repl("$delim>");
	repl.start();
	return 0;
}

Configuring custom greet and farewell functions.

Ginseng will let you handle certain events in your REPL. Such is the case of (obviously) commands. But also you can set up handlers for greet and goodbye if you wish.

#include "Ginseng.h"

int main() 
{
	
	Ginseng repl("$test>",
	  [&repl]() {
	    repl.println("WELCOME TO MY AWESOME RELP!");
	    repl.println("Type \"help\" to start");
	    repl.println("");
	    repl.println("HAVE FUN!");
	  },
	  [&repl]() {
	    repl.println("BYE!");
	  });
	repl.start();
	return 0;
}

Setting up commands.

Commands can be created using add_command function. Such function receives 3 paramenters Namely:

1. Command Name
2. Command Handler (or Callback)
3. Command Help Struct

Help struct is used to let Ginseng know how to print help information. Help struct is just 2 strings one for the argument list and one for the actual description.

// Help(std::string desc, std::string args);
Help hello_help("Says hello back at you", "[name]");

Callback function will be called passing a vector contining the list of arguments (including the command name) collected from the console. Vector will contain at least 1 element (namely: the command name).

Callback function is required to return a success/fail return type Exit. Possible values are

	[ SUCCESS|INVALID_ARGUMENTS|ERROR ]
	//eg: Exit::SUCCESS

This is important to let Ginseng know of the result of the command.

Here is the final code for a more advanced setup with "Hello" Command:

#include "Ginseng.h"

int main()
{
  //Create Ginseng REPL
  Ginseng repl(
      "$test>",
      [&repl]() {
        repl.println("WELCOME TO MY AWESOME RELP!");
        repl.println("Type \"help\" to start");
        repl.println("");
        repl.println("HAVE FUN!");
      },
      [&repl]() {
        repl.println("BYE!");
      });

  // Create Help struct for hello command
  Help hello_help("Says hello back at you", "[name]");

  // Add "hello" command to the REPL
  repl.add_command(
      "hello",
      [&repl](std::vector<std::string> args) -> int {
        if (args.size() < 2)
          return Exit::INVALID_ARGUMENTS;
        repl.printf("HELLO %s\n", args[1].c_str());
        return Exit::SUCCESS;
      },
      hello_help);

  repl.start();
  return 0;
}

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Project Link: https://github.com/chewax/Ginseng