First commit!

19 files changed, 344 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..954ae3c
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,23 @@
+.SUFFIXES: .puml .png
+
+docName = tfg
+outputFolder = out
+
+texFiles = tex/tfg.tex tex/introduction.tex tex/previousWorks.tex tex/interface.tex tex/implementation.tex
+diagramImgs = diagrams/gameRepresentation.png diagrams/modules.png diagrams/sgfModule.png diagrams/gtpEngine.png
+
+all: $(docName).pdf
+
+$(docName).pdf: $(texFiles) $(diagramImgs)
+	[ -d $(outputFolder) ] || mkdir $(outputFolder)
+	xelatex -output-directory $(outputFolder) tex/$(docName).tex
+	biber $(outputFolder)/$(docName)
+	xelatex -output-directory $(outputFolder) tex/$(docName).tex
+	mv $(outputFolder)/$(docName).pdf .
+
+.puml.png:
+	plantuml $<
+
+clean:
+	rm -r $(outputFolder)
+	rm diagrams/*.png
diff --git a/doc/diagrams/ASTNode.pumlc b/doc/diagrams/ASTNode.pumlc
new file mode 100644
index 0000000..05c13ac
--- /dev/null
+++ b/doc/diagrams/ASTNode.pumlc
@@ -0,0 +1,10 @@
+@startuml
+
+class ASTNode {
+	ASTNode[] children
+	Property properties
+	void addtoSequence()
+	GameTree toGameTree()
+}
+
+@enduml
diff --git a/doc/diagrams/GameMove.pumlc b/doc/diagrams/GameMove.pumlc
new file mode 100644
index 0000000..7dcb5e3
--- /dev/null
+++ b/doc/diagrams/GameMove.pumlc
@@ -0,0 +1,13 @@
+@startuml
+
+class GameMove {
+    int player
+    int row
+    int col
+    int[2] makesKo
+    int[] board
+    GameMove[] nextMoves
+    GameMove previousMove
+}
+
+@enduml
diff --git a/doc/diagrams/GameState.pumlc b/doc/diagrams/GameState.pumlc
new file mode 100644
index 0000000..db39d8f
--- /dev/null
+++ b/doc/diagrams/GameState.pumlc
@@ -0,0 +1,14 @@
+@startuml
+
+class GameState {
+    int player
+    int capturesBlack
+    int capturesWhite
+    List board
+    List prevBoards # for ko
+    GameTree gameTree
+    GameMove lastMove
+    GameData gameData
+}
+
+@enduml
diff --git a/doc/diagrams/GameTree.pumlc b/doc/diagrams/GameTree.pumlc
new file mode 100644
index 0000000..85859d8
--- /dev/null
+++ b/doc/diagrams/GameTree.pumlc
@@ -0,0 +1,8 @@
+@startuml
+
+class GameTree {
+    GameNode[] firstMoves
+	GameData gameData
+}
+
+@enduml
diff --git a/doc/diagrams/MoveParser.pumlc b/doc/diagrams/MoveParser.pumlc
new file mode 100644
index 0000000..4c0dc00
--- /dev/null
+++ b/doc/diagrams/MoveParser.pumlc
@@ -0,0 +1,7 @@
+@startuml
+
+class MoveParser {
+    int[] parseMove(input)
+}
+
+@enduml
diff --git a/doc/diagrams/SGF.pumlc b/doc/diagrams/SGF.pumlc
new file mode 100644
index 0000000..2c30202
--- /dev/null
+++ b/doc/diagrams/SGF.pumlc
@@ -0,0 +1,8 @@
+@startuml
+
+class SGF {
+    GameTree loadGameTree(file)
+    void saveGameTree(file)
+}
+
+@enduml
diff --git a/doc/diagrams/gameRepresentation.puml b/doc/diagrams/gameRepresentation.puml
new file mode 100644
index 0000000..9a869f1
--- /dev/null
+++ b/doc/diagrams/gameRepresentation.puml
@@ -0,0 +1,14 @@
+@startuml
+
+!include skinparams.puml
+
+!include GameState.pumlc
+!include GameTree.pumlc
+!include GameMove.pumlc
+
+GameState --> GameTree
+GameState --> GameMove: Current move
+GameTree *--> GameMove
+GameMove -> GameMove
+
+@enduml
diff --git a/doc/diagrams/gtpEngine.puml b/doc/diagrams/gtpEngine.puml
new file mode 100644
index 0000000..c4caf32
--- /dev/null
+++ b/doc/diagrams/gtpEngine.puml
@@ -0,0 +1,29 @@
+@startuml
+
+!include skinparams.puml
+
+class EngineCore {
+}
+
+class IO {
+    processComand()
+}
+
+!include GameState.pumlc
+
+'class EngineBoard {
+'    setSize()
+'    setKomi()
+'    play()
+'    undo()
+'}
+
+class EngineAI {
+    genmove(board)
+}
+
+EngineCore --> IO
+EngineCore --> GameState
+EngineCore --> EngineAI
+
+@enduml
diff --git a/doc/diagrams/modules.puml b/doc/diagrams/modules.puml
new file mode 100644
index 0000000..064be1d
--- /dev/null
+++ b/doc/diagrams/modules.puml
@@ -0,0 +1,9 @@
+@startuml
+
+!include ./skinparams.puml
+
+!include GameState.pumlc
+!include SGF.pumlc
+!include MoveParser.pumlc
+
+@enduml
diff --git a/doc/diagrams/sgfModule.puml b/doc/diagrams/sgfModule.puml
new file mode 100644
index 0000000..c8b51cd
--- /dev/null
+++ b/doc/diagrams/sgfModule.puml
@@ -0,0 +1,17 @@
+@startuml
+
+!include ./skinparams.puml
+
+package "SGF" {
+    !include sgflex.pumlc
+    !include sgfyacc.pumlc
+    !include ASTNode.pumlc
+}
+
+!include GameTree.pumlc
+
+sgflex <- sgfyacc
+sgfyacc -> "*" ASTNode
+ASTNode "1" -> "1" GameTree
+
+@enduml
diff --git a/doc/diagrams/sgflex.pumlc b/doc/diagrams/sgflex.pumlc
new file mode 100644
index 0000000..9b98885
--- /dev/null
+++ b/doc/diagrams/sgflex.pumlc
@@ -0,0 +1,8 @@
+@startuml
+
+object sgflex {
+	input()
+	token()
+}
+
+@enduml
diff --git a/doc/diagrams/sgfyacc.pumlc b/doc/diagrams/sgfyacc.pumlc
new file mode 100644
index 0000000..72a2f3f
--- /dev/null
+++ b/doc/diagrams/sgfyacc.pumlc
@@ -0,0 +1,8 @@
+@startuml
+
+object sgfyacc {
+	parse()
+}
+
+@enduml
+
diff --git a/doc/diagrams/skinparams.puml b/doc/diagrams/skinparams.puml
new file mode 100644
index 0000000..cde3da7
--- /dev/null
+++ b/doc/diagrams/skinparams.puml
@@ -0,0 +1,9 @@
+@startuml
+
+skinparam {
+    monochrome true
+    shadowing false
+    linetype polyline
+}
+
+@enduml
diff --git a/doc/tex/implementation.tex b/doc/tex/implementation.tex
new file mode 100644
index 0000000..9e42313
--- /dev/null
+++ b/doc/tex/implementation.tex
@@ -0,0 +1,64 @@
+\section{Implementation}
+
+\subsection{Engine}
+
+An engine implementing GTP.\@ It is designed to be used by a software controller
+but can also be directly run, mostly for debugging purposes. Its design is shown
+in \fref{fig:engine}
+
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/gtpEngine.png}
+		\caption{Design of the GTP engine.}\label{fig:engine}
+	\end{center}
+\end{figure}
+
+\subsection{Modules}
+
+One module to store the state of the game and the game tree. One module to parse
+moves. One module to read and write SGF files. Modules are shown in
+\fref{fig:modules}.
+
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/modules.png}
+		\caption{Modules.}\label{fig:modules}
+	\end{center}
+\end{figure}
+
+\subsection{Representation of a match}
+
+Strictly said, a match is composed of a series of moves. But since game review
+and variants exploration is an important part of Go learing, \program{} allows
+for navigation back and forth through the board states of a match and for new
+variants to be created from each of these board states. Therefore, a match is
+represented as a tree of moves. The state of the game must also be present so
+liberties, captures and legality of moves can be addressed, so it is represented
+with its own class, which holds a reference both to the game tree and the
+current move. This classes and their relationship can be seen in
+\fref{fig:gameRepresentation}.
+
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=0.7\textwidth]{diagrams/gameRepresentation.png}
+		\caption{A game is represented as a tree of moves.}\label{fig:gameRepresentation}
+	\end{center}
+\end{figure}
+
+\subsection{SGF}
+
+To parse SGF files a lexer and parser have been implemented using PLY.\@ The
+result of the parsing is an AST (Annotated Syntax Tree) reflecting the contents
+of the text input, each node with zero or more properties, and with the ability
+to convert themselves and their corresponding subtree into a GameTree. This is
+done for the root node, since from the SGF specification there are some
+properties only usable in the root node, like those which specify general game
+information and properties such as rank of players or komi. These components are
+shown in \fref{fig:sgfModule}.
+
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/sgfModule.png}
+		\caption{Components of the SGF file parsing module.}\label{fig:sgfModule}
+	\end{center}
+\end{figure}
diff --git a/doc/tex/interface.tex b/doc/tex/interface.tex
new file mode 100644
index 0000000..9caa78d
--- /dev/null
+++ b/doc/tex/interface.tex
@@ -0,0 +1,6 @@
+\section{Interface}
+
+\subsection{Importing and exporting games}
+
+The format chosen to read and write games is SGF (Smart Game Format). It is a
+widely used text format which allows for variants, comments and other metadata.
diff --git a/doc/tex/introduction.tex b/doc/tex/introduction.tex
new file mode 100644
index 0000000..6defbd9
--- /dev/null
+++ b/doc/tex/introduction.tex
@@ -0,0 +1,16 @@
+\section{Introduction}
+
+\begin{displayquote}
+	Go is an ancient game which, from its forgotten origins in China, spread first
+	to the rest of East Asia, and then to the entire world. How ancient? Historians
+	aren't sure; it has a definite history of over 3000 years, but according to
+	tradition Go was invented more than 4000 years ago. The English name comes from
+	the Japanese name Igo, which means ``surrounding boardgame''.
+
+	In this game, each player tries to use threats of death, capture, or isolation
+	to assert control over more of the board than his opponent. An abstract strategy
+	game at heart, Go has nonetheless been interpreted as a stylized representation
+	of fighting a war, settling a frontier, cornering a market, thrashing out an
+	argument, or even of fortune-telling and prophecy. Go has always been one of the
+	most played games in the world. \parencite{sl_go}
+\end{displayquote}
diff --git a/doc/tex/previousWorks.tex b/doc/tex/previousWorks.tex
new file mode 100644
index 0000000..6ba5dce
--- /dev/null
+++ b/doc/tex/previousWorks.tex
@@ -0,0 +1,21 @@
+\section{Previous works}
+
+\subsection{SGF}
+
+SGF (\textit{Smart Go Format} or \textit{Smart Game Format}) is a text file
+format specification for records of games or even collections of them. It was
+devised for Go but it supports other games with similar turns structure. It
+supports move variations, annotations, setups and game metadata. By supporting
+SGF, our application can be used to analyse existing games registered by other
+applications, such as those played on online Go servers.
+
+The SGF specification can be found at
+\url{https://www.red-bean.com/sgf/user_guide/index.html}
+
+\subsection{GTP}
+
+GTP (\textit{Go Text Protocol}) is a text based protocol for communication with
+computer go programs. [ref https://www.lysator.liu.se/~gunnar/gtp/] It is the
+protocol used by GNU Go and the more modern and powerful KataGo. By supporting
+GTP, our application can be used with existing GUIs and other programs, making
+it easier to use it with the tools users are already familiar with.
diff --git a/doc/tex/tfg.tex b/doc/tex/tfg.tex
new file mode 100644
index 0000000..9248748
--- /dev/null
+++ b/doc/tex/tfg.tex
@@ -0,0 +1,60 @@
+\documentclass{article}
+
+\usepackage{geometry}
+\usepackage{graphicx}
+\usepackage{booktabs}
+\usepackage{hyperref}
+\usepackage{csquotes}
+
+\usepackage[backend=biber, style=numeric-comp]{biblatex}
+\addbibresource{/home/taamas/docs/biber.bib}
+
+\geometry{left=4.5cm,top=2cm,bottom=2cm,right=4.5cm}
+
+\hypersetup{colorlinks=true,
+	linkcolor=black,
+	filecolor=magenta,
+	urlcolor=black,
+	bookmarks=true
+}
+
+\urlstyle{mono}
+
+%\renewcommand{\contentsname}{Contenidos}
+%\renewcommand{\figurename}{Figura}
+
+\newcommand{\program}{Go-AI}
+
+\newcommand{\inputtex}[1]{\input{tex/#1}}
+\newcommand{\fref}[1]{Fig.~\ref{#1}}
+%\newcommand{\uurl}[1]{\underline{\url{#1}}}
+
+\begin{document}
+
+\frenchspacing
+
+\title{\program}
+
+\author{Íñigo Gutiérrez Fernández}
+
+\date{}
+
+\maketitle
+
+\begin{abstract}
+	This is the abstract.
+\end{abstract}
+
+\tableofcontents
+
+\inputtex{introduction.tex}
+
+\inputtex{previousWorks.tex}
+
+\inputtex{interface.tex}
+
+\inputtex{implementation.tex}
+
+\printbibliography{}
+
+\end{document}