Nefarious Plastic Mannequins


    0.8.0 • Public • Published

    Build Status Master Source code documentation coverage Scrutinizer Code Quality

    Botlang JS

    Botlang Implementation for JavaScript.


    # Use the no-bin-links flag if you're running the program on a file system which does not support symlinks (like an usb stick) 
    $ npm install --no-bin-links

    Getting started with the cli

    Botlang ships with a command line application, which lets you easily explore your botlang scripts through in the command line. If you just want to play around with an example run npm start which loads the ELIZA bot example into the cli.


    $ ./bin/cli "<path-to-your-botlang-script>"

    Usage with docker

    # Build the container 
    $ docker build -t 'botlang:botlang-js' .
    # Start the ELIZA example 
    $ docker run -it 'botlang:botlang-js' npm start

    Builtin webserver

    Botlang.js provides a lightweight web-server for rapid development. Call npm run web to spawn the server or run docker-compose up to use the containerized version.

    Usage in your own application

      import * as fs from 'fs';
      import Botlang from 'botlang';
      const sourceCode = fs.readFileSync('path-to-your-botlang-script', {
              encoding : 'utf8',
              flag     : 'r'
            bot = new Botlang(sourceCode);

    Language features

    Pattern/ response model

    Botlang's underlying powerful pattern-response model is the core of the language. It allows you to define simple string pattern which enables the interpreter to response with one or more pre-defined responses. The interpreter is case insensitive.

    A pattern definition starts with a plus sign (+) followed by a string enclosed in double quotation marks ("). A response is defined by a minus sign (-) followed by a string enclosed in double quotation marks.


      + "Hey"
      - "Hi, how are you?"

    If you define more than one response the botlang interpreter will choose one randomly.


      + "Hey"
      - "Hi, how are you?"
      - "Hey, how are you?"
      - "Hi, how is it going?"


    Wild-cards in botlang are a powerful tool for writing more advanced matching pattern. A wild-card is represented by the asterisk character *.


      + "*"
      - "I'm not sure I understand you fully."
      - "Please go on."
      - "That is interesting. Please continue."
      - "Tell me more about that."
      - "Does talking about this bother you?"
      - "I see."

    Multiple choice matching

    The multiple choice matching pattern let you define an arbitrary array of matching options. Multiple choice options are enclosed by parenthesis and separated by the pipe character (option_one|option_two|...).

      + "* (bye|goodbye|done|exit|quit) *"
      - "Goodbye. It was nice talking to you."
      - "Goodbye. This was really a nice talk."

    String substitution

    Botlang's string substitution feature let you create more realistic conversations by picking up certain words from the user input. A string substitution is expressed by the dollar sign within your pattern.

      + "I $ you"
      - "Perhaps in your fantasies we $ each other."
      - "Do you wish to $ me?"


    For commenting your botlang scripts use the hash sign #.

    Source code documentation

    The project uses ESDoc for generating source code documentation. Consult the project website for related questions and use appropriate tags in the code. The standard output directory for local development is doc/. The build process can be triggered via the cli npm run make:doc.

    The online source code documentation can be found here.

    Update online documentation

    # To trigger the build process for the hosted documentation fire this curl cmd 
    # or follow the instruction on 
    $ curl -X POST \
           -H 'Accept: application/json' \
           -H 'content-type: application/x-www-form-urlencoded' \
           -d '' \


    This distribution is covered by the GNU GENERAL PUBLIC LICENSE, Version 3, 29 June 2007.

    Support & Contact

    Having trouble with this repository? Check out the documentation at the repository's site or contact and we’ll help you sort it out.

    Happy Coding



    npm i botlang


    DownloadsWeekly Downloads






    Last publish


    • avatar