From 2833a1f4a9ac8d202bf1c36392639865dfc86725 Mon Sep 17 00:00:00 2001
From: Tomas Pecka <peckato1@fit.cvut.cz>
Date: Tue, 10 Jul 2018 10:30:37 +0200
Subject: [PATCH] algo: document automaton::convert
---
alib2algo/src/automaton/convert/ToGrammar.h | 32 +++++++++++-
.../src/automaton/convert/ToGrammarLeftRG.h | 31 ++++++++++--
.../src/automaton/convert/ToGrammarRightRG.h | 30 ++++++++++--
.../convert/ToPostfixPushdownAutomaton.h | 30 ++++++++++--
alib2algo/src/automaton/convert/ToRegExp.h | 49 ++++++++++++++++++-
.../src/automaton/convert/ToRegExpAlgebraic.h | 38 ++++++++++++--
.../convert/ToRegExpStateElimination.cpp | 10 ++--
.../convert/ToRegExpStateElimination.h | 45 +++++++++++++++--
8 files changed, 234 insertions(+), 31 deletions(-)
diff --git a/alib2algo/src/automaton/convert/ToGrammar.h b/alib2algo/src/automaton/convert/ToGrammar.h
index eb75a107e1..4504b735bb 100644
--- a/alib2algo/src/automaton/convert/ToGrammar.h
+++ b/alib2algo/src/automaton/convert/ToGrammar.h
@@ -1,6 +1,22 @@
/*
* ToGrammar.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 9. 2. 2014
* Author: Jan Travnicek
*/
@@ -17,14 +33,26 @@ namespace automaton {
namespace convert {
+/**
+ * Conversion of finite automata to regular grammars.
+ * This class serves as a "default wrapper" over the conversion of FA to RG. It delegates to the right regular grammar conversion.
+ * @sa ToGrammarRightRG
+ */
class ToGrammar {
public:
/**
- * Performs conversion.
- * @return left regular grammar equivalent to source automaton.
+ * Performs the conversion (@sa ToGrammarRightRG::convert).
+ * @tparam SymbolType Type for symbols.
+ * @tparam StateType Type for states.
+ * @param automaton the automaton to convert
+ * @return right regular grammar equivalent to the input @p automaton
*/
template < class SymbolType, class StateType >
static grammar::RightRG < > convert(const automaton::NFA < SymbolType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static grammar::RightRG < > convert(const automaton::DFA < SymbolType, StateType > & automaton);
};
diff --git a/alib2algo/src/automaton/convert/ToGrammarLeftRG.h b/alib2algo/src/automaton/convert/ToGrammarLeftRG.h
index bd95158ee6..7cddacbf91 100644
--- a/alib2algo/src/automaton/convert/ToGrammarLeftRG.h
+++ b/alib2algo/src/automaton/convert/ToGrammarLeftRG.h
@@ -1,6 +1,23 @@
/*
* ToGrammarLeftRG.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *
* Created on: 9. 2. 2014
* Author: Tomas Pecka
*/
@@ -17,17 +34,21 @@ namespace automaton {
namespace convert {
/**
- * Finite automaton to right regular grammar converter.
- * Source: My own :)
+ * Converts a finite automaton to a left regular grammar.
*/
class ToGrammarLeftRG {
public:
/**
- * Performs conversion.
- * @return left regular grammar equivalent to source automaton.
+ * Performs the conversion of the finite automaton to left regular grammar.
+ * @param automaton a finite automaton to convert
+ * @return left regular grammar equivalent to the source @p automaton.
*/
static grammar::LeftRG < > convert(const automaton::NFA < > & automaton);
- static grammar::LeftRG < > convert(const automaton::DFA<>& automaton);
+
+ /**
+ * @overload
+ */
+ static grammar::LeftRG < > convert(const automaton::DFA < > & automaton);
};
} /* namespace convert */
diff --git a/alib2algo/src/automaton/convert/ToGrammarRightRG.h b/alib2algo/src/automaton/convert/ToGrammarRightRG.h
index a6b7f54e44..d3d29ee789 100644
--- a/alib2algo/src/automaton/convert/ToGrammarRightRG.h
+++ b/alib2algo/src/automaton/convert/ToGrammarRightRG.h
@@ -1,6 +1,22 @@
/*
* ToGrammarRightRG.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 9. 2. 2014
* Author: Tomas Pecka
*/
@@ -17,17 +33,21 @@ namespace automaton {
namespace convert {
/**
- * Finite automaton to right regular grammar converter.
- * Source: Melichar 2.104
+ * Converts a finite automaton to a right regular grammar (Melichar: Jazyky a překlady 2.104).
*/
class ToGrammarRightRG {
public:
/**
- * Performs conversion.
- * @return left regular grammar equivalent to source automaton.
+ * Performs the conversion of the finite automaton to right regular grammar.
+ * @param automaton a finite automaton to convert
+ * @return right regular grammar equivalent to the source @p automaton.
*/
static grammar::RightRG < > convert(const automaton::NFA < > & automaton);
- static grammar::RightRG < > convert(const automaton::DFA<>& automaton);
+
+ /**
+ * \overload
+ */
+ static grammar::RightRG < > convert(const automaton::DFA < > & automaton);
};
} /* namespace convert */
diff --git a/alib2algo/src/automaton/convert/ToPostfixPushdownAutomaton.h b/alib2algo/src/automaton/convert/ToPostfixPushdownAutomaton.h
index 6e9c9a4588..507e5b00f7 100644
--- a/alib2algo/src/automaton/convert/ToPostfixPushdownAutomaton.h
+++ b/alib2algo/src/automaton/convert/ToPostfixPushdownAutomaton.h
@@ -1,6 +1,22 @@
/*
* ToPostfixPushdownAutomaton.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 13. 3. 2017
* Author: Stepan Plachy
*/
@@ -17,16 +33,24 @@ namespace automaton {
namespace convert {
+/**
+ * Converts a finite tree automaton (FTA) to a pushdown automaton (PDA) that reads linearised trees in their postfix notation.
+ */
class ToPostfixPushdownAutomaton {
public:
/**
- * Performs conversion.
- * @return PDA equivalent to original finite tree automaton reading linearized postfix tree
+ * Performs the conversion of the deterministic FTA to the deterministic PDA
+ * @param dfta Deterministic finite tree automaton to convert
+ * @return (D)PDA equivalent to original finite tree automaton reading linearized postfix tree
*/
static automaton::DPDA < > convert ( const automaton::DFTA < > & dfta );
+ /**
+ * Performs the conversion of the nondeterministic FTA to the nondeterministic PDA.
+ * @param nfta Nondeterministic finite tree automaton to convert
+ * @return (N)PDA equivalent to original finite tree automaton reading linearized postfix tree
+ */
static automaton::NPDA < > convert ( const automaton::NFTA < > & nfta );
-
};
} /* namespace convert */
diff --git a/alib2algo/src/automaton/convert/ToRegExp.h b/alib2algo/src/automaton/convert/ToRegExp.h
index d67198a40a..bdbed7fa2d 100644
--- a/alib2algo/src/automaton/convert/ToRegExp.h
+++ b/alib2algo/src/automaton/convert/ToRegExp.h
@@ -1,6 +1,22 @@
/*
* ToRegExp.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 9. 2. 2014
* Author: Jan Travnicek
*/
@@ -20,22 +36,51 @@ namespace automaton {
namespace convert {
+/**
+ * Conversion of finite automata to regular expressions.
+ * This class serves as a "default wrapper" over the conversion of FA to RE. It delegates to the State Elimination algorithm.
+ * @sa ToRegExpStateElimination
+ */
class ToRegExp {
public:
/**
- * Performs conversion.
- * @return left regular grammar equivalent to source automaton.
+ * Performs the conversion (@sa ToRegExpStateElimination::convert).
+ * @tparam SymbolType Type for symbols.
+ * @tparam EpsilonType Type for the epsilon symbol.
+ * @tparam StateType Type for states.
+ * @param automaton the automaton to convert
+ * @return regular expression equivalent to the input @p automaton
*/
template < class SymbolType, class EpsilonType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::EpsilonNFA < SymbolType, EpsilonType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::MultiInitialStateNFA < SymbolType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::NFA < SymbolType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::DFA < SymbolType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::ExtendedNFA < SymbolType, StateType > & automaton);
+
+ /**
+ * @overload
+ */
template < class SymbolType, class StateType >
static regexp::UnboundedRegExp < > convert(const automaton::CompactNFA < SymbolType, StateType > & automaton);
};
diff --git a/alib2algo/src/automaton/convert/ToRegExpAlgebraic.h b/alib2algo/src/automaton/convert/ToRegExpAlgebraic.h
index a6bc5c239c..b1d8af0f8c 100644
--- a/alib2algo/src/automaton/convert/ToRegExpAlgebraic.h
+++ b/alib2algo/src/automaton/convert/ToRegExpAlgebraic.h
@@ -1,6 +1,22 @@
/*
* ToRegExpAlgebraic.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 11. 2. 2014
* Author: Tomas Pecka
*/
@@ -22,18 +38,32 @@ namespace convert {
// https://github.com/ferno/greenery/blob/bcc0a136335edbe94cd7725fc6e8cce0268d850c/fsm.py
/**
- * Converts FA to RE using Brzozowski's algebraic method using right regular equations.
- * Source : Melichar 2.122
+ * Converts a finite automaton to a regular expression using using the Brzozowski's algebraic method (Melichar: Jazyky a překlady 2.122).
+ * The algorithm creates a system of right regular equations that is then solved.
+ * The regular expression is returned as regexp::UnboundedRegExp.
*/
class ToRegExpAlgebraic {
public:
/**
- * Performs conversion.
- * @return regular expression equivalent to input automaton.
+ * Performs the actual conversion.
+ * @param automaton The automaton that is to be converted to the regular expression.
+ * @return regular expression equivalent to the input @p automaton.
*/
static regexp::UnboundedRegExp < > convert(const automaton::EpsilonNFA < > & automaton);
+
+ /**
+ * \overload
+ */
static regexp::UnboundedRegExp < > convert(const automaton::MultiInitialStateNFA < > & automaton);
+
+ /**
+ * \overload
+ */
static regexp::UnboundedRegExp < > convert(const automaton::NFA < > & automaton);
+
+ /**
+ * \overload
+ */
static regexp::UnboundedRegExp < > convert(const automaton::DFA < > & automaton);
};
diff --git a/alib2algo/src/automaton/convert/ToRegExpStateElimination.cpp b/alib2algo/src/automaton/convert/ToRegExpStateElimination.cpp
index 3dd0819a54..e98fd37840 100644
--- a/alib2algo/src/automaton/convert/ToRegExpStateElimination.cpp
+++ b/alib2algo/src/automaton/convert/ToRegExpStateElimination.cpp
@@ -61,11 +61,11 @@ automaton::ExtendedNFA < > ToRegExpStateElimination::eliminateState(const automa
for(const auto& p: newAutomaton.getStates()) {
for(const auto& r : newAutomaton.getStates()) {
- regexp::UnboundedRegExpStructure < DefaultSymbolType > concat = transition(extendedAutomaton, p, q);
- concat = regexp::RegExpConcatenate::concatenate(concat, regexp::RegExpIterate::iterate(transition(extendedAutomaton, q, q)));
- concat = regexp::RegExpConcatenate::concatenate(concat, transition(extendedAutomaton, q, r));
+ regexp::UnboundedRegExpStructure < DefaultSymbolType > concat = transitionsToRegExp(extendedAutomaton, p, q);
+ concat = regexp::RegExpConcatenate::concatenate(concat, regexp::RegExpIterate::iterate(transitionsToRegExp(extendedAutomaton, q, q)));
+ concat = regexp::RegExpConcatenate::concatenate(concat, transitionsToRegExp(extendedAutomaton, q, r));
- regexp::UnboundedRegExpStructure < DefaultSymbolType > alt = regexp::RegExpAlternate::alternate(concat, transition(extendedAutomaton, p, r));
+ regexp::UnboundedRegExpStructure < DefaultSymbolType > alt = regexp::RegExpAlternate::alternate(concat, transitionsToRegExp(extendedAutomaton, p, r));
newAutomaton.addTransition(p, regexp::simplify::RegExpOptimize::optimize(alt), r);
}
@@ -74,7 +74,7 @@ automaton::ExtendedNFA < > ToRegExpStateElimination::eliminateState(const automa
return newAutomaton;
}
-const regexp::UnboundedRegExpStructure < DefaultSymbolType > ToRegExpStateElimination::transition(const automaton::ExtendedNFA < > & automaton, const DefaultStateType& from, const DefaultStateType& to) {
+const regexp::UnboundedRegExpStructure < DefaultSymbolType > ToRegExpStateElimination::transitionsToRegExp(const automaton::ExtendedNFA < > & automaton, const DefaultStateType& from, const DefaultStateType& to) {
regexp::UnboundedRegExpStructure < DefaultSymbolType > ret(regexp::UnboundedRegExpEmpty < DefaultSymbolType > { });
for(const auto& transition: automaton.getTransitionsFromState(from))
diff --git a/alib2algo/src/automaton/convert/ToRegExpStateElimination.h b/alib2algo/src/automaton/convert/ToRegExpStateElimination.h
index c4a3cb5e7e..c16bd9e58f 100644
--- a/alib2algo/src/automaton/convert/ToRegExpStateElimination.h
+++ b/alib2algo/src/automaton/convert/ToRegExpStateElimination.h
@@ -1,6 +1,22 @@
/*
* ToRegExpStateElimination.h
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: 9. 2. 2014
* Author: Tomas Pecka
*/
@@ -21,24 +37,43 @@ namespace automaton {
namespace convert {
/**
- * Converts FSM to RE using State Elimination algorithm.
- * Source: Melichar 2.118
+ * Converts a finite automaton to a regular expression using using the State Elimination algorithm (Melichar: Jazyky a překlady 2.118).
+ * This algorithm returns the regular expression as regexp::UnboundedRegExp.
*/
class ToRegExpStateElimination {
public:
/**
* Performs conversion.
- * @param automaton automaton to convert
- * @return regular expression equivalent to source NFA.
+ * @tparam T type of the finite automaton
+ * @param automaton finite automaton to convert
+ * @return unbounded regular expression equivalent to the original automaton
*/
template<class T>
static regexp::UnboundedRegExp < > convert(const T& automaton);
private:
+ /**
+ * Helper function to create new initial and final states in the automaton for the algorithm.
+ * @param automaton extended finite automaton
+ */
static void extendExtendedNFA(automaton::ExtendedNFA < > & automaton);
- static const regexp::UnboundedRegExpStructure < DefaultSymbolType > transition(const automaton::ExtendedNFA < > & automaton, const DefaultStateType& from, const DefaultStateType& to);
+ /**
+ * Helper function to create a regexp from all transitions between states @p from and @p to.
+ * It creates the alternation regexp of all such transitions.
+ * @param automaton automaton to select the transitions
+ * @param from source state in @param automaton
+ * @param to destination state in @param automaton
+ * @return the regular expression node representing the transitions between states @p from and @p to
+ */
+ static const regexp::UnboundedRegExpStructure < DefaultSymbolType > transitionsToRegExp(const automaton::ExtendedNFA < > & automaton, const DefaultStateType& from, const DefaultStateType& to);
+ /**
+ * Helper function for the elimination of a single state according to the algorithm.
+ * @param extendedAutomaton automaton for the elimination
+ * @param state state to eliminate
+ * @return the @p extendedAutomaton after the elimination of a state @state.
+ */
static automaton::ExtendedNFA < > eliminateState(const automaton::ExtendedNFA < > & extendedAutomaton, const DefaultStateType& state);
};
--
GitLab