Update README.md

jachym · Apr 27, 2020 · 083d98e · 083d98e
1 parent c8c9a5d
commit 083d98e
Show file tree

Hide file tree

Showing 25 changed files with 2,577 additions and 2 deletions.
diff --git a/.clang-format b/.clang-format
@@ -0,0 +1,31 @@
+# Configuration file for clang-format, based on docs/CPP_STYLE.md.
+
+BasedOnStyle: Google
+IndentWidth: 2
+BreakBeforeBraces: Allman
+ColumnLimit: 100
+
+Language: Cpp
+AccessModifierOffset: -2
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: true
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+BreakConstructorInitializersBeforeComma: true
+ConstructorInitializerIndentWidth: 4
+DerivePointerAlignment: false
+IndentCaseLabels: false
+NamespaceIndentation: None
+PointerAlignment: Middle
+SortIncludes: true
+Standard: Cpp11
+
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^<.*\.h>'
+    Priority:        1
+  - Regex:           '^<.*'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        3
diff --git a/.github/workflows/ccpp.yml b/.github/workflows/ccpp.yml
@@ -0,0 +1,31 @@
+name: C/C++ CI
+
+on:
+  push:
+    branches: [ master, add-* ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: git_actions
+      run: git submodule update --init --recursive
+    - name: cmake
+      run: |
+        sudo apt update
+        sudo apt install mm-common g++-9
+        export CXX=g++-9
+        cmake .
+    - name: make
+      run: |
+       export CXX=g++-9
+       make
+    - name: run_tests
+      run: |
+        pwd
+        ctest --output-on-failure
diff --git a/.gitignore b/.gitignore
@@ -30,3 +30,12 @@
 *.exe
 *.out
 *.app
+
+# Other
+.DS_Store
+.idea/
+cmake-build-debug/
+CMakeFiles/
+Makefile
+*.cmake
+CMakeCache.txt
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "doctest"]
+	path = doctest
+	url = https://github.com/onqtam/doctest
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.6)
+
+project(just_gtfs LANGUAGES CXX VERSION 0.1)
+
+include_directories(include)
+include_directories(doctest/doctest)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED on)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Werror")
+
+enable_testing()
+
+add_subdirectory(tests)
+add_subdirectory(benchmarks)
diff --git a/LICENSE → LICENSE.MIT b/LICENSE → LICENSE.MIT
diff --git a/README.md b/README.md
@@ -1,2 +1,110 @@
-# just_gtfs
-C++17 header-only GTFS parsing library
+# just_gtfs - header-only modern C++ GTFS parsing library
+
+[![GTFS parser for C++](https://github.com/mapsme/just_gtfs/blob/add-the-most-important-readers/docs/logo.jpeg)](https://github.com/mapsme/just_gtfs)
+
+[![C++](https://img.shields.io/badge/c%2B%2B-17-informational.svg)](https://shields.io/)
+[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
+![](https://github.com/mapsme/just_gtfs/workflows/C%2FC%2B%2B%20CI/badge.svg)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/mapsme/just_gtfs/issues)
+
+ - Header-only
+ - C++17
+ - Tested on GCC and Clang
+ - STL-compatible containers
+ - Fast reading and parsing of GTFS feeds
+
+## Table of Contents
+- [Working with GTFS feeds](#working-with-gtfs-feeds)
+- [How to use just_library](#how-to-use-it)
+- [Used third-party tools](#used-third-party-tools)
+
+## Working with GTFS feeds
+The library implements reading static transit data in GTFS - [General Transit Feed Specification](https://developers.google.com/transit/gtfs/reference).
+It provides class for working with GTFS feeds: `gtfs::Feed`.
+GTFS csv files are mapped to the corresponding C++ classes. Every GTFS entity can be accessed through `gtfs::Feed`.
+
+:pushpin: Example of providing `gtfs::Feed` the feed path, reading it and working with GTFS entities such as stops and routes:
+```c++
+Feed feed("~/data/SFMTA/");
+if (feed.read_feed() == ResultCode::OK)
+{
+	Stops stops = feed.get_stops();
+	std::cout << stops.size() << std::endl;
+
+	Route route = feed.get_route("route_id_1009");
+	if (route)
+	{
+		std::cout << route->route_long_name << std::endl;
+	}
+}
+```
+
+GTFS feed can be wholly read from directory as in the example above or you can read GTFS files separately. E.g., if you need only shapes data, you can avoid parsing all other files and just work with the shapes.
+
+:pushpin: Example of reading only `shapes.txt` from the feed and working with shapes:
+```c++
+Feed feed("~/data/SFMTA/");
+if (feed.read_shapes() == ResultCode::OK)
+{
+	Shapes all_shapes = feed.get_shapes();
+	Shape shape = feed.get_shape("9367");
+}
+```
+
+
+## Methods for reading and writing GTFS entities
+Methods of the `Feed` class for working with agencies:
+
+Read agencies from the corresponding csv file.
+```c++
+Result read_agencies()
+```
+
+Get reference to `Agencies` - `std::vector` of `Agency` objects.
+```c++
+const Agencies & get_agencies()
+```
+
+Find agency by its id. This method returns `std::optional` so you should check if the result is `std::nullopt`.
+```c++
+std::optional<Agency> get_agency(const Id & agency_id)
+``` 
+
+Add agency to the feed.
+```c++
+void add_agency(const Agency & agency)
+```
+
+Add agency to the feed by filling agency object fields with parsed csv values. `row` is `std::map` with csv column titles as keys ans csv row items as values. 
+```c++
+Result add_agency(ParsedCsvRow const & row)
+```
+
+
+:pushpin: **There are similar methods for all other GTFS entities** for getting the list of entities, finding and adding them.
+For some of them additional methods are provided. 
+For example, you can find all the stop times for current stop by its id:
+```c++
+StopTimes get_stop_times_for_stop(const Id & stop_id)
+```
+
+Or you can find stop times for the particular trip:
+```c++
+StopTimes get_stop_times_for_trip(const Id & trip_id, bool sort_by_sequence = true)
+```
+
+## How to use library
+- For including the library in your own project: just_gtfs is completely contained inside a single header and therefore it is sufficient to copy include/just_gtfs/just_gtfs.h to your include pathes. The library does not have to be explicitly build.
+- For running library tests:
+Clone just_gtfs with `git clone --recursive` or run `git submodule update --init --recursive` after cloning.
+In the just_gtfs project directory build the project and run unit tests: 
+```
+cmake .
+make
+ctest --output-on-failure
+```
+The library makes use of the C++17 features and therefore you have to use appropriate compiler version.
+- For including as a submodule: use branch "for-usage-as-submodule" which consists of a single header.
+
+## Used third-party tools
+- [**doctest**](https://github.com/onqtam/doctest) for unit testing.
diff --git a/benchmarks/CMakeLists.txt b/benchmarks/CMakeLists.txt
diff --git a/docs/CPP_STYLE.md b/docs/CPP_STYLE.md
@@ -0,0 +1,6 @@
+## C++ Style Guide
+
+We use C++ code style similar to the [MAPS.ME project](https://github.com/mapsme/omim/blob/master/docs/CPP_STYLE.md) with some differences:
+- Use **CamelCase** for class names and **snake_case** for other entities like methods, variables, etc.
+- Use left-to-right order for variables/params: `const std::string & s` (reference to the const string).
+- Do not use prefixes like `m_` for member variables.
diff --git a/docs/logo.jpeg b/docs/logo.jpeg
diff --git a/doctest b/doctest