File	Date	Author	Commit
doc	2009-08-27	Martin Kopta	[ee12f2] git sf move
src	2009-10-13	Martin Kopta	[f7fa5e] minor bugfix in isl11
.gitignore	2009-07-16	Martin Kopta	[d6e733] gitignore update
AUTHORS	2009-07-31	Martin Kopta	[541016] release
COPYING	2009-07-31	Martin Kopta	[541016] release
ChangeLog	2009-10-13	Martin Kopta	[608002] actual actual release of 1.0.1
README	2009-07-31	Martin Kopta	[541016] release
TODO	2009-10-13	Martin Kopta	[2a9a51] release 1.0.1

Read Me

README.txt for poga: Processing of grammars and automata

WHAT IS POGA
  Poga is software for processing of formal languages, especially for processing
  automata and grammars.

FEATURES
    * CLI interface
    * Programed in C++ with OOP design
    * Modular architecture (shared objects)

INFORMATIONS
  Main page of poga is on this URL: http://poga.sourceforge.net/

SOURCES
  git clone git://poga.git.sourceforge.net/gitroot/poga

COMPILING
  cd src && make

RUNNING
  cd src && ./poga

INSTALLATION
  cd src && make install

UNINSTALLATION
  cd src && make uninstall

EXAMPLES
  For plaing with poga you can use some examples - directory examples/


User guide to poga
===================

Martin Kopta <martin@kopta.eu> http://martin.kopta.eu
May, 2009

Requirements
------------
Program and modules require presence of standard C and C++ libraries, library
for dynamic linking (libdl) and mathematical library (libm). For compilation of
the source code the C++ compiler is needed, GNU make is recomended. Hardware
requirements are irelevant. Operating system should be POSIX like.

Installation from source code
-----------------------------
Before installing the program, compilation of the source code is necessary.
Source code contains compiling directive 'Makefile', which can be invoked by
program 'make'. After succesfull compilation, the program can be installed into
the system using command 'make install'.

Example of compilation and installation:

  tar xf poga-1.0.0.tar.gz
  cd poga-1.0.0
  make
  make install

Modules are installed into directory /usr/lib/poga and program itself is copied
as /usr/bin/poga. If you don't have "make" program, you can follow compiling
directive manualy.

note: there is no configure script (yet)

Usage of poga
-------------

  poga <options> <inputfiles>

Options
- - - -
  -h, --help               show help
  -u, --usage              show usage
  -v, --version            print version
  -o file, --output file   set output file
  -a name, --action name   activate desired action
        use '-a help' for list of avalible actions
  -f format, --output-format format
                           set output format
  If format is not set, plain is used. For list of
  output formats use '--output-format=help'

If there is no output format set, the default "plain" is chosen.

Usage examples
- - - - - - -

  poga -a nfa2dfa -f dot -o mydfa.dot mynfa.poga

Converts NFA to DFA and result is converted into DOT language and save it into file.

  poga -a preg2aut -o automaton.poga plainregex.poga

Converts PlainRegex to an automaton.

  poga -a none -f dot automaton.poga

Converts given automaton to DOT language.

  poga -a complement -f dot automaton.poga | dot -T png > complement.png

For given automaton creates a complement and using graphviz creates a PNG image.

  poga -a isLL1 c_language.poga | less

Calculate FIRST, FOLLOW and parsing table.

  poga -a help | less

Gives a list of availible actions.

Format of datafiles
-------------------

Datafiles are just plain text files with ".poga" suffix (recommendation).
Files may contain these tokens:

Token                 | Example
----------------------+----------------
Left curly bracket    |    {
Right curly bracket   |    }
Dot                   |    .
Arrow                 |    ->
Arrow                 |    =>
Keyword               |    states
String                |    "alpha"

Occurence of any other token is invalid syntax. Whitespace ([\r\n\t ]) is
skipped.

Strings can contain any ASCII characters. Strings begin and end with double
quotes. If you need to write a double quote inside of string, you need to use a
backslash to escape it. And of course, if you need to write a backslash, you
need escape it as well.

  "this is string with double quote \" and with a backslash \\ and some text"

Input data must begin with this section:

  type { "data type" }

The "data type" can be:

  * automaton
  * grammar
  * plainregex

For each type of data are required some data sections. For data type 'automaton'
you have to specify sections alphabet, states, final, init and transactions. For
data type 'grammar' you have to specify sections terminals, nonterminals, rules
and init. For data type 'plainregex' you have to specify only section
plainregex. All data types can have one section 'comment' which can contain one
string.

Type automaton
- - - - - - - -
Section alphabet
~~~~~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one symbol of input alphabet of
automaton. Section defines input alphabet of automaton.

Section states
~~~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one state of automaton. Section
defines all states of automaton. According to syntax it can be empty, but
according to semantics at least one is needed (init state).

Section final
~~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one final state of automaton. Section
defines all final states of automaton. Contained strings must be also present in
section states.

Section init
~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one init state of automaton.
Section defines all init states of automaton. Contained strings must be also
present in section states. According to syntax it can be empty, but according to
semantics at least one is needed.

Section transitions
~~~~~~~~~~~~~~~~~~~
Group of 0 to N transitions. Syntax of one transitions:

  "Src" => "Dest"

(Arrow => and -> are both valid). Both strings must be present in section
states.

Type grammar
- - - - - -
Section terminals
~~~~~~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one terminal of grammar. Section
defines all terminals of grammar. None of given strings can be present in
section nonterminals.

Section nonterminals
~~~~~~~~~~~~~~~~~~~~
Group of 0 to N strings. Each string represents one nonterminal of grammar.
Section defines all nonterminals of grammar. None of given strings can be
present in section terminals. According to syntax this section can contain no
strings, but according to semantics at least one must be given (init).

Section rules
~~~~~~~~~~~~~
Group of 0 to N rules. Syntax of one rule:
  "A" => "B" "C" "D" "E" .
Right side of the rule may contain 0 to N strings. Each rule must have dot (.)
in the end. All strings must be in set of strings, created by union of sections
nonterminals and terminals.

Section init
~~~~~~~~~~~~
Exatly one string representing starting nonterminal of grammar. This string must
be present in section nonterminals.

Type plainregex
- - - - - - - -
Section plainregex
~~~~~~~~~~~~~~~~~~
Exactly one nonempty string representing plainregex.

All types
- - - - -
Section comment
~~~~~~~~~~~~~~~
Exactly one string containing any text. It's recommended to use for describing
data.

# EOF