added documentation

This commit is contained in:
Daniel Knuettel 2017-03-09 16:36:27 +01:00
parent 01b214f53b
commit b6b3024910
8 changed files with 528 additions and 0 deletions

159
.bin/alldoc Normal file
View File

@ -0,0 +1,159 @@
#!/usr/bin/python3
#
# Copyright(c) 2017 Daniel Knüttel
#
# This program is free software.
# Anyways if you think this program is worth it
# and we meet shout a drink for me.
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program 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 Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
# Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
# der GNU Affero General Public License, wie von der Free Software Foundation,
# Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
# veröffentlichten Version, weiterverbreiten und/oder modifizieren.
#
# Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
# OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
# Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
# Siehe die GNU Affero General Public License für weitere Details.
#
# Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
# Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
"""
alldoc -- extract reStructuredText docstrings from all
sourcefiles.
This does include non-python files/languages.
Invoke alldoc using
::
python3 alldoc.py <outfile> <infile> {<infile>}
"""
import logging
# logging.basicConfig(level = logging.DEBUG)
logging.basicConfig()
start_alldoc = [ "<alldoc>", "<doc>", "startdoc", "SDOC"]
stop_alldoc = ["</alldoc>", "</doc>", "stopdoc", "EDOC"]
def indexof(str_, substr):
"""
This is handy if you want to get the next substr.
"""
try:
return str_.index(substr)
except:
return float("inf")
def extract_docs(str_, start_alldoc = start_alldoc, stop_alldoc = stop_alldoc):
"""
Extract all docstrings starting with ``start_alldoc`` and stopping with
``stop_alldoc``.
For instance:
::
/*
<DOC>
This is a docstring
</DOC>
*/
"""
lines_done = 0
while(1):
next_doc_start, start = min([(indexof(str_, start), start) for start in start_alldoc])
if(next_doc_start == float("inf")):
logging.debug("no more docstrings found in line "+ str(lines_done))
break
logging.debug("found docstart " + start)
unused, str_ = str_[:next_doc_start], str_[next_doc_start + len(start):]
lines_done += unused.count("\n")
logging.debug("docstart is in " + str(lines_done))
doc_stop, token = min([(indexof(str_, stop), stop) for stop in stop_alldoc])
if(doc_stop == float("inf")):
raise ExtractException("unterminated docstart: " + start + " in line " + str(lines_done))
doc, str_ = str_[:doc_stop], str_[doc_stop + len(token):]
logging.debug("found docstop " + token)
yield doc
lines_done += doc.count("\n")
logging.debug("docstop is in " + str(lines_done))
def docs_from_file(path, delim = "\n\n"):
"""
Read all docstrings from one file.
"""
with open(path) as f:
logging.debug("reading file " + path)
str_ = f.read()
docs = delim.join(extract_docs(str_))
f.close()
return docs
def collect_docs(files, delim = "\n\n"):
"""
Read all docstrings from multiple files
"""
for file_ in files:
yield docs_from_file(file_, delim)
def generate_rst_head(str_, underscore = "="):
"""
Generate a rst Heading.
"""
return str_ + "\n" + underscore * len(str_) + "\n"
def generate_docfile(fname, files, delim = "\n\n", add_rst_head = True):
"""
Read all docstrings and output one file.
FIXME: try to spend less memory.
"""
f = open(fname, "w")
f.write("".join(["".join(t) for t in zip([generate_rst_head(file) for file in files] , collect_docs(files))]))
f.close()
class ExtractException(Exception):
def __init__(self, *args):
Exception.__init__(self, *args)
if __name__ == "__main__":
import sys
if(len(sys.argv) < 3):
print("Usage:", sys.argv[0], "outfile infile {infile}")
print("extract docstrings from non-python files")
print("start tokens: ", start_alldoc)
print("stop tokens: ", stop_alldoc)
sys.exit(1)
outfile = sys.argv[1]
infiles = sys.argv[2:]
try:
generate_docfile(outfile, infiles)
except Exception as e:
print("Error:", e)
sys.exit(1)

View File

@ -1,9 +1,16 @@
CC=gcc CC=gcc
CFLAG= -O -g -o CFLAG= -O -g -o
alldoc=python3 $(PWD)/.bin/alldoc
objects=main.o\ objects=main.o\
playfield.o\ playfield.o\
input_output.o input_output.o
headers=conf.h\
playfield.h\
input_output.h
all:main all:main
%.o:%.c %.o:%.c
@ -15,3 +22,12 @@ main: clean $(objects)
clean: clean:
rm $(objects) || true rm $(objects) || true
doc.rst:$(headers)
$(alldoc) doc.rst.tmp $(headers)
printf "Documentation\n_____________\n\n" > doc.rst
cat doc.rst.tmp >> doc.rst
rm doc.rst.tmp
doc.pdf:
rst2pdf doc.rst

67
conf.h
View File

@ -1,7 +1,74 @@
/*
* Copyright(c) 2017 Daneil Knuettel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#ifndef __conf__h_ #ifndef __conf__h_
#define __conf__h_ #define __conf__h_
/*
<doc>
This file contains all configuration makros
used by the game. The default makros are:
::
#define WIDTH 50
#define LINES 20
#define KEY_DEFAULT '_'
#define KEY_RIGHT 'd'
#define KEY_LEFT 'a'
#define KEY_EXIT 'q'
#define CHAR_ME '#'
#define CHAR_ENEMY '*'
#define ESCAPE_RED "\033[31m"
#define ESCAPE_GREEN "\033[32m"
#define ESCAPE_RESET "\033[0m"
#define CHRS_TO_CLEAR_ESCAPE 7
They should not be set using the compiler's command line options.
</doc>
*/
#define WIDTH 50 #define WIDTH 50
#define LINES 20 #define LINES 20

View File

@ -1,3 +1,41 @@
/*
* Copyright(c) 2017 Daniel Knuettel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#include<stdio.h> #include<stdio.h>
#include<stdlib.h> #include<stdlib.h>
#include<unistd.h> #include<unistd.h>

View File

@ -1,3 +1,40 @@
/*
* Copyright(c) 2017 Daneil Knuettel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#ifndef __input_output_h_ #ifndef __input_output_h_
#define __input_output_h_ #define __input_output_h_
#include<stdio.h> #include<stdio.h>
@ -6,6 +43,58 @@
#include<sys/select.h> #include<sys/select.h>
#include<signal.h> #include<signal.h>
/*
<doc>
This file contains all required input/output functions.
There is a special global flag variable
::
static volatile char EOF_received = 0;
that will be set to ``1``, if the stdin stream reached ``EOF``.
This flag will break the mainloop.
The following input functions are defined:
::
char kb_hit(void);
returns 1, if there is a character on stdin.
::
char get_last_key_or_default(void);
Returns the last entered character from stdin.
If there is no character it will return the
default character defined in ``conf.h``.
If stdin reaches ``EOF`` the flag ``EOF_received`` will
be set.
The following output functions are defined:
::
void put_line(char * line);
Puts the given line ``line`` of the horizon or playfield
on the stdout stream. The line is inside a frame and
highlights special characters according to ``conf.h``.
::
void clear_screen(void);
Clears the screen. The number of lines and collumns
are calculated according to ``conf.h``.
</doc>
*/
#include "conf.h" #include "conf.h"
void put_line(char * line); void put_line(char * line);
void clear_screen(void); void clear_screen(void);

38
main.c
View File

@ -1,3 +1,41 @@
/*
* Copyright(c) 2017 Daniel Knüttel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#include<stdio.h> #include<stdio.h>
#include<stdlib.h> #include<stdlib.h>
#include<unistd.h> #include<unistd.h>

View File

@ -1,3 +1,41 @@
/*
* Copyright(c) 2017 Daniel Knüttel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#include<stdlib.h> #include<stdlib.h>
#include<stdio.h> #include<stdio.h>
#include"conf.h" #include"conf.h"

View File

@ -1,6 +1,89 @@
/*
* Copyright(c) 2017 Daneil Knuettel
*/
/* This program is free software.
* Anyways if you think this program is worth it
* and we meet shout a drink for me.
*/
/* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
* der GNU Affero General Public License, wie von der Free Software Foundation,
* Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
* veröffentlichten Version, weiterverbreiten und/oder modifizieren.
*
* Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
* OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
* Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
* Siehe die GNU Affero General Public License für weitere Details.
*
* Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
* Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
*/
#ifndef __playfield_h_ #ifndef __playfield_h_
#define __playfield_h_ #define __playfield_h_
/*
<doc>
This files contains all functions to control the
playfield and horizon.
The following functions are defined in this file:
::
void build_horizon(char *** horizon);
Allocates the horizon according to ``conf.h``.
In addition to this it prints enough newlines to
make space in the terminal for the playfield.
::
void horizon_drop_one_line(char ** horizon);
Moves all objects from one line to the next line of the
horizon. The first line of the horizon is filled with
blanks.
::
void print_horizon(char ** horizon);
Prints the entired horizon usinf ``put_line``.
::
void delete_horizon(char ** horizon);
Frees the horizon.
::
char * allocate_playfield(size_t width);
Allocates a playfield with the given width
(The parameter should be set according to ``conf.h``).
Fills the string with blanks.
</doc>
*/
void build_horizon(char *** horizon); void build_horizon(char *** horizon);
void horizon_drop_one_line(char ** horizon); void horizon_drop_one_line(char ** horizon);
void print_horizon(char ** horizon); void print_horizon(char ** horizon);