~mil/mobroute

1fd172bee2f7647c87727e9c8da9f067779a0333 — Miles Alan 2 months ago 80025b7 
Cleanup CLI doc; add usage text to main ./mobroute cli
patch browse .tar.gz 
3 files changed, 94 insertions(+), 34 deletions(-)

M cli/const.go
M cli/mobroutecli.go
M doc/userguide_cli.md

M cli/const.go => cli/const.go +36 -3
@@ 18,7 18,39 @@ var (
)

const (
	subcmdRouteDoc = `
	cmdDoc = `Usage of %s:
  mobroute [subcommand]

Description:
  Mobroute is a general purpose FOSS public transportation router (e.g. trip planner). See: http://sr.ht/~mil/mobroute

Subcommands:
  - route: Perform a routing request from GTFS dataload, to CSA algorithm calculation, and formatting 
  - mobsql: Diagnostic tool which can query and manipulate the underlying SQLiteDB via the underlying mobsql library
  - version: Display the version information for this release
`

	subcmdRouteDesc = `
The route subcommand is the primary command for the CLI (and
is a passthrough to the underlying Mobroute library OneshotRoute
function). This subcommand allows you to perform routing calculations using
the CSA algorithm. All functionality from loading GTFS data (by feed
id), to loading the required data to memory, to performing the routing
calculation via the CSA algorithm, and finally to formatting the result
in several formats is handled by this single CLI subcommand.
	`

	subcmdMobsqlDesc = `
The mobsql subcommand is a diagnostic command (and a passthrough to
the underlying Mobroute library OneshotMobsql function) which allows
you to both alter and query the status of GTFS (and GTFS-derived data)
in the local SQLite database. In normal scenarios & functioning end-users
shouldn't need to use this subcommand at all as this is just a debugging
tool. See mobsql documentation for specifics on the functionality of
each operation (op).
	`

	subcmdRouteDocParams = `
JSON Parameters for oneshot route subcommand, should be in format of: {"route_params": {"feed_ids": [516],...}}

Required route parameters:


@@ 29,7 61,7 @@ Required route parameters:
  - output_formats: Array of formats for the output may include - may include "legs", "geojson", "diagnostics", "mapurl", "request" (ex: ["legs", "geojson"])

Optional route parameters:
  - time: Datetime at which route should depart in RFC3339 format (default: current system time)
  - time: Datetime string at which route should depart in RFC3339 format (default: current system time)
  - max_walk_seconds: Maximum seconds walking distance on start/end of trip to get to/from origin/destination stops (default: 1200)
  - max_trip_seconds: Maximum seconds the entire route/trip can take (default: 14400)
  - min_transfer_seconds: Minimum seconds each transfer in the route can take (default: 180)


@@ 37,7 69,8 @@ Optional route parameters:
  - max_n_transfers: Maximum number of transfers a route can contain (default: 20)
  - walkspeed_km_hr: Ratio of kilometers per hour the user walk (default: 4.5)
`
subcmdMobsqlDoc = ` JSON Parameters for oneshot mobsql subcommand, should be in format of: {"mobsql_params": {"feed_ids": [767], "op": "status"}}
	subcmdMobsqlDocParams = `
JSON Parameters for oneshot mobsql subcommand, should be in format of: {"mobsql_params": {"feed_ids": [767], "op": "status"}}

Required mobsql parameters:
  - feed_ids: Array of integer feed IDs (MDBID) to use for mobsql requests (ex: [767])


M cli/mobroutecli.go => cli/mobroutecli.go +10 -5
@@ 7,6 7,7 @@ import (
	"flag"
	"fmt"
	"os"
	"strings"

	"git.sr.ht/~mil/mobroute"
	"git.sr.ht/~mil/mobroute/util/utilfuncs"


@@ 16,9 17,9 @@ func main() {
	var (
		flagBaseDebugCategories, flagBaseDebugProfile string
		flagMobsqlSet                                 = flag.NewFlagSet("mobsql", flag.ExitOnError)
		flagMobsqlParams                              = flagMobsqlSet.String("mp", "", subcmdMobsqlDoc)
		flagMobsqlParams                              = flagMobsqlSet.String("mp", "", subcmdMobsqlDocParams)
		flagRouteSet                                  = flag.NewFlagSet("route", flag.ExitOnError)
		flagRouteParams                               = flagRouteSet.String("rp", "", subcmdRouteDoc)
		flagRouteParams                               = flagRouteSet.String("rp", "", subcmdRouteDocParams)
	)

	// Debug Same usage for all subcommands


@@ 34,7 35,7 @@ func main() {
	// Run command
	validSubcommands := []string{"version", "route", "mobsql"}
	if len(os.Args) < 2 || !utilfuncs.StringInArray(validSubcommands, os.Args[1]) {
		fmt.Println("Provide valid subcommand as first arg, valid subcommands:", validSubcommands)
		fmt.Fprintf(os.Stderr, cmdDoc, os.Args[0])
		os.Exit(1)
	} else if os.Args[1] == "route" {
		cmdRoute(flagRouteSet, flagRouteParams)


@@ 48,7 49,9 @@ func main() {
func cmdRoute(flagRouteSet *flag.FlagSet, flagRouteParams *string) {
	var routeParams mobroute.OneshotRouteRequest
	flagRouteSet.Usage = func() {
		fmt.Fprintf(os.Stderr, "Usage of %s route:\n", os.Args[0])
		fmt.Fprintf(os.Stderr, "Usage of %s route:\n\n", os.Args[0])
		fmt.Fprintf(os.Stderr, "Description:\n  %s\n\n", strings.Trim(strings.Replace(subcmdRouteDesc, "\n", " ", -1), " "))
		fmt.Fprintf(os.Stderr, "Flags: \n")
		flagRouteSet.PrintDefaults()
		fmt.Fprintf(os.Stderr, "\nExamples:\n")
		for exName, exCmd := range subcmdRouteExamples {


@@ 73,7 76,9 @@ func cmdRoute(flagRouteSet *flag.FlagSet, flagRouteParams *string) {
func cmdMobsql(flagMobsqlSet *flag.FlagSet, flagMobsqlParams *string) {
	var mobsqlParams mobroute.OneshotMobsqlRequest
	flagMobsqlSet.Usage = func() {
		fmt.Fprintf(os.Stderr, "Usage of %s mobsql:\n", os.Args[0])
		fmt.Fprintf(os.Stderr, "Usage of %s mobsql:\n\n", os.Args[0])
		fmt.Fprintf(os.Stderr, "Description:\n  %s\n\n", strings.Trim(strings.Replace(subcmdMobsqlDesc, "\n", " ", -1), " "))
		fmt.Fprintf(os.Stderr, "Flags: \n")
		flagMobsqlSet.PrintDefaults()
		fmt.Fprintf(os.Stderr, "\nExamples:\n")
		for exName, exCmd := range subcmdMobsqlExamples {


M doc/userguide_cli.md => doc/userguide_cli.md +48 -26
@@ 10,9 10,10 @@ Go codebase and then running routing requests locally.

- *1:* [Primer Documentation](#strongprimer-documentationstrong)
- *2:* [Mobroute CLI: Install](#strongmobroute-cli-installstrong)
- *3:* [Mobroute CLI: Route subcommand](#strongmobroute-cli-route-subcommandstrong)
- *4:* [Mobroute CLI: Mobsql subcommand](#strongmobroute-cli-mobsql-subcommandstrong)
- *5:* [Further Resources & Documentation](#strongfurther-resources-amp-documentationstrong)
- *3:* [Mobroute CLI: Usage](#strongmobroute-cli-usagestrong)
- *4:* [Mobroute CLI: Route subcommand](#strongmobroute-cli-route-subcommandstrong)
- *5:* [Mobroute CLI: Mobsql subcommand](#strongmobroute-cli-mobsql-subcommandstrong)
- *6:* [Further Resources & Documentation](#strongfurther-resources-amp-documentationstrong)

## **Primer Documentation**



@@ 42,10 43,29 @@ Go codebase and then running routing requests locally.
    - (4) Install as:
      - `cp mobroute /usr/bin/`

## **Mobroute CLI: Usage**
```sh
Usage of ./mobroute:
  mobroute [subcommand]

Description:
  Mobroute is a general purpose FOSS public transportation router (e.g. trip planner). See: http://sr.ht/~mil/mobroute

Subcommands:
  - route: Perform a routing request from GTFS dataload, to CSA algorithm calculation, and formatting
  - mobsql: Diagnostic tool which can query and manipulate the underlying SQLiteDB via the underlying mobsql library
  - version: Display the version information for this release
```

## **Mobroute CLI: Route subcommand**

```sh
Usage of ./mobroute route:

Description:
  The route subcommand is the primary command for the CLI (and is a passthrough to the underlying Mobroute library OneshotRoute function). This subcommand allows you to perform routing calculations using the CSA algorithm. All functionality from loading GTFS data (by feed id), to loading the required data to memory, to performing the routing calculation via the CSA algorithm, and finally to formatting the result in several formats is handled by this single CLI subcommand.

Flags:
  -d string
        Verbose debug categories: (i) Information (w) Warn (d) Debug (default "i")
  -dprof string


@@ 56,14 76,14 @@ Usage of ./mobroute route:
        JSON Parameters for oneshot route subcommand, should be in format of: {"route_params": {"feed_ids": [516],...}}

        Required route parameters:
          - feed_ids: Array of integer feed IDs (MDBID) to use for routing requests
          - from: Array of two floats; [lat, lon]
          - to: Array of two floats; [lat, lon]
          - time: Datetime at which route should depart in RFC3339 format
          - transfer_categories: Array of transfers categories to load - "f" for feed, "i" for implicit, "g" for generated, e.g. ["f", "i"]
          - output_formats: Array of formats for the output may include - ["legs", "geojson", "diagnostics", "mapurl", "request"]
          - feed_ids: Array of integer feed IDs (MDBID) to use for routing requests (ex: [516, 510])
          - from: Array of two floats in lat, lon format (ex: [50.012338, 19.88192])
          - to: Array of two floats in lat, lon format (ex: [50.012338, 19.88192])
          - transfer_categories: Array of transfers categories to load - may include "f" for feed, "i" for implicit, "g" for generated (ex: ["f", "i"])
          - output_formats: Array of formats for the output may include - may include "legs", "geojson", "diagnostics", "mapurl", "request" (ex: ["legs", "geojson"])

        Optional route parameters:
          - time: Datetime string at which route should depart in RFC3339 format (default: current system time)
          - max_walk_seconds: Maximum seconds walking distance on start/end of trip to get to/from origin/destination stops (default: 1200)
          - max_trip_seconds: Maximum seconds the entire route/trip can take (default: 14400)
          - min_transfer_seconds: Minimum seconds each transfer in the route can take (default: 180)


@@ 74,14 94,11 @@ Usage of ./mobroute route:

Examples:
  NYC Routing Example:
    mobroute route -rp '{"route_params":{"feed_ids":[516],"from":[40.70940,-74.00537],"to":[40.72879,-73.95215],"transfer_categories":["f","i"],"output_formats
":["legs","diagnostics","mapurl","request"]}}'
    mobroute route -rp '{"route_params":{"feed_ids":[516],"from":[40.70940,-74.00537],"to":[40.72879,-73.95215],"transfer_categories":["f","i"],"output_formats":["legs","diagnostics","mapurl","request"]}}'
  Brussels Routing Example:
    mobroute route -rp '{"route_params":{"feed_ids":[1088],"from":[50.85728,4.351426],"to":[50.83214,4.350534],"transfer_categories":["f","i"],"output_formats"
:["legs","diagnostics","mapurl","request"]}}'
    mobroute route -rp '{"route_params":{"feed_ids":[1088],"from":[50.85728,4.351426],"to":[50.83214,4.350534],"transfer_categories":["f","i"],"output_formats":["legs","diagnostics","mapurl","request"]}}'
  Krakow Routing Example:
    mobroute route -rp '{"route_params":{"feed_ids":[1270],"from":[50.012338,19.88192],"to":[50.08785,20.02387],"transfer_categories":["f","i"],"output_formats
":["legs","diagnostics","mapurl","request"]}}'
    mobroute route -rp '{"route_params":{"feed_ids":[1270],"from":[50.012338,19.88192],"to":[50.08785,20.02387],"transfer_categories":["f","i"],"output_formats":["legs","diagnostics","mapurl","request"]}}'
```




@@ 89,36 106,41 @@ Examples:

```sh
Usage of ./mobroute mobsql:

Description:
  The mobsql subcommand is a diagnostic command (and a passthrough to the underlying Mobroute library OneshotMobsql function) which allows you to both alter and query the status of GTFS (and GTFS-derived data) in the local SQLite database.
 In normal scenarios & functioning end-users shouldn't need to use this subcommand at all as this is just a debugging tool. See mobsql documentation for specifics on the functionality of each operation (op).

Flags:
  -d string
        Verbose debug categories: (i) Information (w) Warn (d) Debug (default "i")
  -dprof string
        Write debug pprof CPU profile to file
  -h    Show this usage message
  -mp string
        JSON Parameters for oneshot mobsql subcommand, should be in format of: {"mobsql_params": {"feed_ids": [767], "op": "status"}}.

        JSON Parameters for oneshot mobsql subcommand, should be in format of: {"mobsql_params": {"feed_ids": [767], "op": "status"}}

        Required mobsql parameters:
          - feed_ids: Array of integer feed IDs (MDBID) to use for mobsql requests
          - op: Operation to perform, one of - ["status", "load", "compute", "purge_gtfs", "purge_computed", "purge_all"]
          - feed_ids: Array of integer feed IDs (MDBID) to use for mobsql requests (ex: [767])
          - op: Operation to perform - may be one of "status", "load", "compute", "purge_gtfs", "purge_computed", "purge_all" (ex: "status")


Examples:
  Determine GTFS Feed Status:
    mobroute mobsql -mp '{"mobsql_params": {"op": "status", "feed_ids": [767]}}'
  Load a GTFS Feed:
    mobroute mobsql -mp '{"mobsql_params": {"op": "load", "feed_ids": [767]}}'
  Compute Routing-Optimized GTFS Derived Tables:
    mobroute mobsql -mp '{"mobsql_params": {"op": " compute", "feed_ids": [767]}}'
    mobroute mobsql -mp '{"mobsql_params": {"op": "compute", "feed_ids": [767]}}'
  Purge GTFS Feed Data:
    mobroute mobsql -mp '{"mobsql_params": {"op": " purge_gtfs", "feed_ids": [767]}}'
    mobroute mobsql -mp '{"mobsql_params": {"op": "purge_gtfs", "feed_ids": [767]}}'
  Purge Computed Tables:
    mobroute mobsql -mp '{"mobsql_params": {"op": " purge_computed", "feed_ids": [767]}}'
    mobroute mobsql -mp '{"mobsql_params": {"op": "purge_computed", "feed_ids": [767]}}'
  Purge All Tables:
    mobroute mobsql -mp '{"mobsql_params": {"op": " purge_all", "feed_ids": [767]}}'
  Determine GTFS Feed Status:
    mobroute mobsql -mp '{"mobsql_params": {"op": "status", "feed_ids": [767]}}'
    mobroute mobsql -mp '{"mobsql_params": {"op": "purge_all", "feed_ids": [767]}}'
```



## **Further Resources & Documentation**

- [Automated Test Results / Metros](https://ci.lrdu.org/tests_results/): If you're curious about metros that have been well-tested and MDBIDs which you can experiment with for routing, this page has a number of working routing requests (lat/lon pairs and MDBIDs)