v1.1.0 bump + release notes + docs (#101)

README.md

@@ -1,4 +1,4 @@
-# tcframe 1.0.1
+# tcframe 1.1.0
 
 [![GitHub Release](https://img.shields.io/github/release/tcframe/tcframe.svg)](https://github.com/tcframe/tcframe)
 [![Build Status](https://img.shields.io/travis/tcframe/tcframe/master.svg)](https://travis-ci.org/tcframe/tcframe)

docs/api-ref/api-ref.rst

@@ -79,6 +79,51 @@ The following macros are exposed to define input/output formats:
 
     Defines an empty line.
 
+.. py:function:: RAW_LINE(string variable name)
+
+    Defines a line of raw string. The variable must be of ``std::string`` type.
+
+    Example:
+
+    .. sourcecode:: cpp
+
+        void InputFormat() {
+            RAW_LINE(S);
+        }
+
+    With **S** = "Hello, world!", the above format will produce:
+
+    ::
+
+        Hello, world!
+
+.. py:function::
+    RAW_LINES(vector of string variable name)
+    RAW_LINES(vector of string variable name) % SIZE(number of elements)
+
+    Defines multiple lines, each consisting of raw string. The variable must be of ``std::vector<std::string>`` type.
+
+    If the size is not given, then this must be the last segment in the I/O format.
+
+    Example:
+
+    .. sourcecode:: cpp
+
+        void InputFormat() {
+            RAW_LINES(X) % SIZE(2);
+            RAW_LINES(Y);
+        }
+
+    With **X** = {"Hello, world!", "Happy new year."}, **Y** = {"lorem", "ipsum", "dolor sit amet"}, the above format will produce:
+
+    ::
+
+        Hello, world!
+        Happy new year.
+        lorem
+        ipsum
+        dolor sit amet
+
 .. py:function:: LINE(comma-separated elements)
 
     Defines a single line containing space-separated scalar or vector variables. In case of vector variables, the elements are separated by spaces as well.
@@ -107,9 +152,13 @@ The following macros are exposed to define input/output formats:
         1 2 3 100 200 300 400
         2 7 8
 
-.. py:function:: LINES(comma-separated vector/matrix variable names) % SIZE(number of elements)
+.. py:function::
+    LINES(comma-separated vector/matrix variable names)
+    LINES(comma-separated vector/matrix variable names) % SIZE(number of elements)
 
-    Defines multiple lines, each consisting space-separated elements of given vector/matrix variables.
+    Defines multiple lines, each consisting of space-separated elements of given vector/matrix variables.
+
+    If the size is not given, this must be the last segment in the I/O format.
 
     Example:
 
@@ -118,9 +167,10 @@ The following macros are exposed to define input/output formats:
         void InputFormat() {
             LINES(V) % SIZE(2);
             LINES(X, Y) % SIZE(N);
+            LINES(Z);
         }
 
-    With **V** = {1, 2}, **X** = {100, 110, 120}, **Y** = {200, 210, 220}, **N** = 3, the above format will produce:
+    With **V** = {1, 2}, **X** = {100, 110, 120}, **Y** = {200, 210, 220} **N** = 3, **Z** = {1, 2, 3, 4} the above format will produce:
 
     ::
 
@@ -129,6 +179,10 @@ The following macros are exposed to define input/output formats:
         100 200
         110 210
         120 220
+        1
+        2
+        3
+        4
 
     If a matrix variable is given, it must occur as the last argument, and the number of rows must match with the number of elements of the other vector variables (if any). It is not required that each row of the matrix consists of the same number of columns.
 

docs/conf.py

@@ -53,9 +53,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '1.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.1'
+release = '1.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/getting-started/getting-started.rst

@@ -44,7 +44,7 @@ Installation
 
 Firstly, we must get **tcframe** on our system. It consists of C++ header files and a few helper scripts.
 
-Download the latest **tcframe** `here <https://github.com/tcframe/tcframe/releases/download/v1.0.1/tcframe_1.0.1.zip>`_. Extract the zip file somewhere on your system; for example, ``~/tcframe``. We will call this directory "**tcframe** home". Confirm that you extracted it correctly by verifying that the directory ``include`` exists directly inside **tcframe** home.
+Download the latest **tcframe** `here <https://github.com/tcframe/tcframe/releases/download/v1.1.0/tcframe_1.1.0.zip>`_. Extract the zip file somewhere on your system; for example, ``~/tcframe``. We will call this directory "**tcframe** home". Confirm that you extracted it correctly by verifying that the directory ``include`` exists directly inside **tcframe** home.
 
 Then, add the following lines to your ``~/.bashrc``. This will set the environment variable ``TCFRAME_HOME`` to our **tcframe** home directory, and make ``tcframe`` command available everywhere.
 

docs/release-notes/1_0_0.rst

@@ -3,7 +3,7 @@
 1.0.0
 =====
 
-Nov 27, 2016
+November 27, 2016
 
 .. note::
 

docs/release-notes/1_0_1.rst

@@ -3,7 +3,7 @@
 1.0.1
 =====
 
-Nov 28, 2016
+November 28, 2016
 
 Bugfixes
 --------

docs/release-notes/1_1_0.rst

@@ -0,0 +1,30 @@
+.. _v1_1_0:
+
+1.1.0
+=====
+
+December 4, 2016
+
+New features
+------------
+
+- It is now possible to omit ``SIZE()`` for a ``LINES()`` segment, as long as it is the last segment in an I/O format.
+- Brand new segments: ``RAW_LINE()`` and ``RAW_LINES()``, which accept strings containing whitespaces.
+
+Enhancements
+------------
+
+- I/O format errors after a vector/matrix now have the last indices reported in the error message. For example,
+
+  Before:
+
+  ::
+
+      Expected: <newline> after 'D'
+
+
+  Now:
+
+  ::
+
+      Expected: <newline> after 'D[1]'

docs/release-notes/release-notes.rst

@@ -6,6 +6,7 @@ Release Notes
 .. toctree::
    :maxdepth: 1
 
+   1_1_0
    1_0_1
    1_0_0
    0_7_0

docs/topic-guides/io-formats.rst

@@ -43,10 +43,38 @@ The list of supported segments is given below. In all segments, it must be noted
 - The terms scalar, vector, and matrix below refer to the :ref:`I/O variable types described in the previous chapter <io-variables>`.
 - Vectors and matrices will have 0-based indexing. This is strict and there is no way to enforce 1-based indexing.
 
+There are two categories of I/O segments: raw segments and tokenized segments.
+
+Raw segments
+************
+
+These segments do not do any special formatting to the value of the variables; they will print/parse them as-is.
+
 Empty line
     Specified by the macro ``EMPTY_LINE()``. Represents a single, empty line.
 
-Singe line
+Raw line
+    Specified by the macro ``RAW_LINE(...)``. Represent a line of the string given as the only argument. The argument must be of ``std::string`` type.
+
+    For example: "... the next line consists of a sentence containing arbitrary printable ASCII characters **S**" can be specified by  ``RAW_LINE(S)`` (where ``S`` is a string).
+
+Multiple raw lines
+    Specified by the macro ``RAW_LINES(...) % SIZE(<size>)``. Represent lines of string given as the only argument. The argument must be of ``std::vector<std::string>`` type.
+
+    For example: "... each of the next N lines consists of a sentence containing arbitrary printable ASCII characters **S**" can be specified by  ``RAW_LINES(S) % SIZE(N)`` (where ``S`` is a vector of strings).
+
+    The size can also be omitted, as long as this is the last segment.
+
+Tokenized segments
+******************
+
+These segments do some formatting to the value of the variables. For example, the elements of a vector variable in a line will be printed space-separated.
+
+.. note::
+
+    In tokenized segments, string variables cannot have whitespaces. For example, ``hello, world!`` is considered to have two string variables: ``hello,`` and ``world!``. Use raw segments if you want to work with strings containing whitespaces.
+
+Single line
     Specified by the macro ``LINE(...)``. Represents space-separated values in a single line.
 
     The macro accepts one or more I/O variables as arguments. The value of the variables will be space-separated. For example: "... the first line consists of two space-separated integers **N** and **M**" can be specified by ``LINE(N, M)``.
@@ -55,7 +83,7 @@ Singe line
 
     You can freely combine scalars and vectors in ``LINE()``; for example, ``LINE(N, A % SIZE(N), C % SIZE(2))`` would represent a line consisting of ``N A[0] A[1] ... A[N-1] C[0] C[1]``.
 
-    Lastly, you can specify a vector without fixed size, as long as it is the last argument. For example: "... the input consists an integer **X** followed by space-separated integers" can be specified by ``LINE(X, A)`` (assuming ``A`` is a vector).
+    Lastly, you can specify a vector without fixed size, as long as it is the last argument. For example: "... the input consists an integer **X** followed by space-separated integers" can be specified by ``LINE(X, A)`` (where ``A`` is a vector).
 
 Multiple lines
     Specified by the macro ``LINES(...) % SIZE(<size>)``. Represents multiple lines, each containing an element of a vector given as the argument.
@@ -66,8 +94,10 @@ Multiple lines
 
     You also could specify jagged vector as the last argument. This is useful for input format like, "... then **M** lines follow. Each line begins with a string **op**. If **op** is ``UPDATE``, then it is followed by two integers **x** **y**. If it is ``QUERY``, then it is followed by a single integer **z**". This can be specified by ``LINES(op, data)`` where ``op`` is a ``vector<string>`` and ``data`` is a ``vector<vector<int>>``. Then, ``data[i]`` represents a vector of integers in the i-th line, which can consist of one or two elements.
 
+    Lastly, the size can also be omitted, as long as this is the last segment.
+
 Grid
-    Specified by the macro ``GRID(...) % SIZE(<row>, <column>)``. Represents a grid containing elements of a matrix given as the argument, laid out in a grid.
+    Specified by the macro ``GRID(...) % SIZE(<row>, <column>)``. Represents a grid containing elements of a matrix given as the only argument, laid out in a grid.
 
     For example: "... each fo the next **R** lines contain **C** integers **G**\ [i][j]" can be specified by ``GRID(G) % SIZE(R, C)``.