Jalog class

Jalog 1.3

io.github.JalogTeam.jalog
Class Jalog

java.lang.Object
  io.github.JalogTeam.jalog.Jalog

public class Jalog

Class Jalog represents the Prolog subsystem. Before running the Prolog program the Prolog subsystem is instantiated. Then the program is consulted from a file, a resource, or an array of strings. Running the system can consist of several calls. Each call is preceded by construction of input and output data structures. Then the instantiated system is used to run the program. The run call should be within a try-catch structure, because it can throw an exception. If the call succeeds, the results are recovered from the Prolog data structures. Finally the subsystem is disposed.

Typical calling pattern:

  static Jalog myJalog = new Jalog();
  myJalog.consult_file("source.pro");
  /* for each call */
    /* construct data structures, e.g.: */
      Jalog.Term count = Jalog.integer(7);
      Jalog.Term answer = Jalog.open();
    /* call the predicate */
      try {
        if (myJalog.call("predicate", count, answer))
        { /* success */
          if (answer.getType() == Jalog.INTEGER) {
            /* answer of expected type got */
            long result = answer.getIntegerValue();
          } else {
            /* wrong type, should not occur */
          }
        } else {
          /* predicate failed */
        }
      } catch (Jalog.Exit e) { 
        /* exception */
      }
  /* when everything is done */    
  myJalog.dispose();

Nested Class Summary
`static class`	`Jalog.Term` All data processed and produced by Jalog is of this class.
`static class`	`Jalog.Exit` Exception to be raised when exit predicate is executed.
`static class`	`Jalog.Output` Can be subclassed to redirect output.
`static class`	`Jalog.OutputErr` Can be subclassed to redirect error messages.
`static class`	`Jalog.ResourceManager` Can be subclassed to redirect input from resources.

Field Summary
`static String`	`CHARACTER` Code for character variable.
`static String`	`COMPOUND` Code for compound variable.
`static Output`	`err` Current error message stream.
`static String`	`INTEGER` Code for integer variable.
`static String`	`LIST` Code for list variable.
`static String`	`OPEN` Code for open variable.
`static Output`	`out` Current print stream.
`static String`	`REAL` Code for real variable.
`static String`	`STRING` Code for string variable.
`static String`	`SYMBOL` Code for symbol variable.

Constructor Summary
`Jalog()` Constructs a `Jalog` engine instance.

Method Summary
`static boolean`	`call(String predname, Jalog.Term ... args)` Calls a predicate defined in the consulted file.
`static Jalog.Term`	`character(char c)` Creates a new character term with value c.
`static Jalog.Term`	`compound(String name, Jalog.Term[] arguments)` Creates a new compound term with functor name `name` and components from arguments array. If the arguments array is empty, the result is of type symbol.
`static void`	`consult_data_file(String filename, String[] filter)` Consults (reads) facts from a file.
`static void`	`consult_data_stringlist(String[] lines, String[] filter, String name)` Consults (reads) facts from an array of strings.
`static void`	`consult_file(String filename)` Consults (reads and compiles) a Prolog source file.
`static void`	`consult_stringlist(String[] lines, String name)` Consults (compiles) Prolog source from an array of strings.
`static void`	`dispose()` Clears the database of program and data..
`static String`	`get_consult_dir()` Returns current consult directory.
`static InputStream`	`getResourceAsStream(String fileName)` Redirect resource access.
`static Jalog.Term`	`integer(long i)` Creates a new integer term with value i.
`static Jalog.Term`	`list(Jalog.Term[] elements)` Creates a new list term populated with items from `elements`
`static Jalog.Term`	`open()` Creates a new open variable.
`static Jalog.Term`	`real(double r)` Creates a new real term with value r.
`static void`	`set_comline_arg (String option, String argument)` Defines a command-line argument for the Jalog program.
`static void`	`set_consult_dir(String dirname)` Sets current consult directory.
`static void`	`setErr(Jalog.Output o)` Sets current error message stream.
`static void`	`setOut(Jalog.Output o)` Sets current print stream.
`static void`	`setResourceManager(Jalog.ResourceManager rm)` Sets current resource manager.
`static Jalog.Term`	`string(String s)` Creates a new string term with value s.
`static Jalog.Term`	`symbol(String name)` Creates a new symbol term with value name.

Field Detail

OPEN

public static final String OPEN = "open"

Code for open variable.

INTEGER

public static final String INTEGER = "integer"

Code for integer variable.

SYMBOL

public static final String SYMBOL = "symbol"

Code for symbol variable.

REAL

public static final String REAL = "real"

Code for real variable.

CHARACTER

public static final String CHARACTER = "character"

Code for character variable.

STRING

public static final String STRING = "string"

Code for string variable.

LIST

public static final String LIST = "list"

Code for list variable.

COMPOUND

public static final String COMPOUND = "compound"

Code for compound variable.

out

public static Jalog.Output out = new Jalog.Output();

Current output.

err

public static Jalog.Output err = new Jalog.OutputErr();

Current error output.

Constructor Detail

Jalog

public Jalog()
           throws Error

Constructs a Jalog inference engine. Limitation: Only one engine can exist at any time. After usage it must be disposed of using the dispose method.

Throws:: Error - if a Jalog inference engine already exists.
See Also:: dispose()

Method Detail

open

public static Jalog.Term open()

Creates a new open variable.

Returns:: the new open variable.

integer

public static Jalog.Term integer(long i)

Creates a new integer term with value i.

Parameters:: i - the value of the new integer.
Returns:: an integer term.

symbol

public static Jalog.Term symbol(String name)

Creates a new symbol term with value name.

Parameters:: name - the value of the new symbol.
Returns:: a symbol term.

real

public static Jalog.Term real(double r)

Creates a new real term with value r.

Parameters:: r - the value of the new real.
Returns:: a real term.

character

public static Jalog.Term character(char c)

Creates a new character term with value c.

Parameters:: c - the value of the new character.
Returns:: a character term.

string

public static Jalog.Term string(String s)

Creates a new string term with value s.

Parameters:: s - the value of the new string.
Returns:: a string term.

list

public static Jalog.Term list(Jalog.Term[] elements)

Creates a new list term populated with items from elements array.

Parameters:: elements - the items of the new list.
Returns:: a list term.

compound

public static Jalog.Term compound(String name, Jalog.Term[] arguments)

Creates a new compound term with functor name name and components from arguments array. If the arguments array is empty, the result is of type symbol.

Parameters:: name - the functor of the new compound.; arguments - the components of the new compound.
Returns:: a compound term.

consult_file

public static void consult_file(String filename)

Consults (reads and compiles) a Prolog source file.

Parameters:: filename - the name of the Prolog source file.

consult_stringlist

public static void consult_stringlist(String[] lines, String name)

Consults (compiles) Prolog source from an array of strings.

Parameters:: lines - Prolog source lines.; name - comment for error messages.

consult_data_file

public static void consult_data_file(String filename, String[] filter)

Consults (reads) facts from a file. Only facts specified in the filter are consulted. Filter is an array of strings, each containing a predicate indicator in form name/arity .

Parameters:: filename - the name of the Prolog source lines.; filter - predicate indicators.
Example:: consult_data_file("data.pro", new String[]{"cars/4", "houses/2"});

consult_data_stringlist

public static void consult_data_stringlist(String[] lines, String[] filter, String name)

Consults facts from an array of strings. Only facts specified in the filter are consulted. Filter is an array of strings, each containing a predicate indicator in form name/arity .

Parameters:: lines - the name of the Prolog source lines.; filter - predicate indicators.; name - comment for error messages.
Example:: String[] things = {; "cars(\"Volvo\", 17, 88, 36).",; "cars(\"Opel\", 5, 42, 150).",; "houses(\"Home\", 128000)."; };; consult_data_stringlist(things, new String[]{"cars/4", "houses/2"}, "things");

set_consult_dir

public static void set_consult_dir(String dirname)

Sets current consult directory, i.e. default directory for consult operations.

Parameters:: dirname - the name of the consult directory.

get_consult_dir

public static String get_consult_dir()

Returns current consult directory, i.e. default directory for consult operations. The directory name is absolute and always begins with "file:" or "res:". It can be used as an argument to set_consult_dir .

Returns:: the name of the current consult directory.

set_comline_arg

public static void set_comline_arg(String option, String argument)

Defines a command-line argument.

Parameters:: option - the name of the option.; argument - the value of the option.
Example:: To emulate the following command line arguments
-foo=bar -up report.txt
the calls; set_comline_arg("foo", "bar");; set_comline_arg("up", "");; set_comline_arg("", "report.txt");; store the following facts to the Jalog database; comline_arg(1, "foo", "bar").; comline_arg(2, "up", "").; comline_arg(3, "", "report.txt").

dispose

public static void dispose()

Clears the Prolog program, its data and the inference engine from the memory. Allows creating a new inference engine for another purpose.

call

public static boolean call(String predname, Jalog.Term ... args)
           throws Jalog.Exit

Calls a predicate defined in the consulted file.

Parameters:: predname - the name of the predicate to be called.; args - the arguments for the predicate.
Returns:: true if the predicate succeeds, false if the predicate fails.
Throws:: Jalog.Exit - when the program executes an exit predicate.

getResourceAsStream

public static InputStream getResourceAsStream(String fileName)
           throws IOException

Provides a stream for reading a resource file.

Parameters:: filename - the name of the resource file.
Returns:: an input stream for reading a resource.
Throws:: IOException - propagated from I/O system.

setErr

public static void setErr(Jalog.Output o)

Redirects error messages.

Parameters:: o - output class for error messages.

setOut

public static void setOut(Jalog.Output o)

Redirects output: print and println.

Parameters:: o - output class for error messages.
Example:: To add additional processing to the output define subclass of Jalog.Output:; public static class TestOutput extends Jalog.Output {; public void print(String s) {; System.out.print("|" + s);; }; }; Before calling the Prolog code redirect the output:; myJalog.setOut(new TestOutput());

setResourceManager

public static void setResourceManager(Jalog.ResourceManager rm)

To consult resource files from a non-standard place (e.g. in Android applications) define a subclass of Jalog.ResourceManager and introduce it with this function.

Parameters:: rm - new resource manager

Other Detail

dirname

Directory names can refer to directories either in the file system or in the resource system. In order to specifically refer to the file system prepend the name with "file:". In order to refer to a directory in the resource system prepend the name with "res:". If neither is specified and the dirname is an absolute path it refers to the file system. A relative path refers to a subdirectory of the current consult directory.

Examples:: "file:C:/data" - refers to the data directory at the root of the C disk.; "res:lib/routes" - refers to a resource directory.; "sub" - refers to the subdirectory sub of the current directory.

filename

File names can refer either to files in the file system or to resources of the jar package. In order to specifically refer to the file system prepend the name with "file:". In order to refer to a resource in the resource system prepend the name with "res:". If neither is specified and the filename is an absolute path it refers to the file system. A relative path refers to a file or resource in the current consult directory.

Examples:: "file:C:/data/trees.pro" - refers to a file in the file system.; "res:parameters.pro" - refers to a resource in the resource system.; "rules.pro" - refers to a file or a resource in the current directory.

Authors: Mikko Levanto, Ari Okkonen

io.github.JalogTeam.jalog Class Jalog