README.md

   1 # Daki language Ruby interpreter
   2
   3 Daki is a small computer programming language influenced by Prolog and Datalog. [Read all about it.](https://macro.win/dakilang.html)
   4
   5 For fast prototyping and iteration, this first interpreter is written in Ruby.
   6
   7 ## Installation
   8
   9 You will only require a not-too-old Ruby binary.
  10
  11 ## Instructions
  12
  13 The Daki interpreter can be used both in interactive and non-interactive mode. In non-interactive mode, the interpreter input, read from files, is also outputted so as to mimic what would appear on a terminal on interactive mode.
  14
  15 In non-interactive mode, the interpreter reads one or more text files in sequence, and interpretes each line fully before advancing. A line can change the global state, which consists of logical assertions.
  16
  17 To launch the interpreter in interactive mode, use the `-i` flag:
  18
  19 ```sh
  20 ./dakilang -i
  21 ```
  22
  23 In non-interactive mode a syntax error will end the program, whereas nothing is stopped in interactive mode, so give it a go in interactive mode until you have a good grasp of the syntax.
  24
  25 To launch the interpreter in non-interactive mode, use `-c` with the file path to be executed:
  26
  27 ```sh
  28 ./dakilang -c examples/example1.dl
  29 ```
  30
  31 You can mix the modes, you can start the interpreter by including - _consulting_ - one or more files, and afterwards switching to interactive mode:
  32
  33 ```sh
  34 ./dakilang -i -c examples/example1.dl -c examples/example2.dl
  35 ```
  36
  37 Switching to interactive mode is always performed only after every consulted file is interpreted, in order.
  38
  39 ### Options
  40
  41 The full list of command line options are:
  42
  43 Option | Description
  44 ------ | -----------
  45 -h, --help | Print out the program manual and exit
  46 -v, --version | Print out the program name and version, and exit
  47 -c, --consult | Read file with path F and interpret each line
  48 -i, --interactive | Activate interactive mode after finishing consulting all files
  49 -d, --debug | Activate debug mode, which shows the output of the output of clause parsing and a trace of the query solver
  50 -t, --time | Changes the default query timeout time; N is a floating point value in seconds
  51 --disable-colors | Disable the use of colors in the interpreter's output
  52
  53 ## Tests
  54
  55 This interpreter has tests for the interpreter search algorithm itsef, and for the parser:
  56
  57 ```bash
  58 ./test_interpreter.sh
  59 ./test_parser.sh
  60 ```
  61
  62 If you find a bug, or the interpreter crashes, please open an issue with the faulty instructions.
  63
  64 ## Debugging
  65
  66 To debug the interpreter itself, first make sure the Ruby gem `pry` is installed system-wide:
  67
  68 ```bash
  69 gem install pry
  70 ```
  71
  72 Then plant a `binding.pry` instruction where you need a breakpoint, and start the interpreter from inside the src/ folder:
  73
  74 ```bash
  75 cd src
  76
  77 ruby dakilang.rb -c ../program_to_debug.dl
  78 ```
  79
  80 ---
  81
  82 Copyright (c) 2021 Gonçalo Mendes Ferreira
  83
  84 Permission to use, copy, modify, and/or distribute this software for any purpose
  85 with or without fee is hereby granted, provided that the above copyright notice
  86 and this permission notice appear in all copies.
  87
  88 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
  89 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  90 FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
  91 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
  92 OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  93 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  94 THIS SOFTWARE.