Skip to content

Commit

Permalink
Add quickdoc via bb docs to auto-generate API docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@rjsheperd
rjsheperd committed Apr 16, 2024
1 parent 57d309e commit e5d9a30
Show file tree
Hide file tree
Showing 13 changed files with 1,822 additions and 329 deletions.
1,685 changes: 1,685 additions & 0 deletions API.md
View file

Large diffs are not rendered by default.

325 changes: 4 additions & 321 deletions README.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -518,328 +518,11 @@ clojure -M:systemd stop -r <REPO>
clojure -M:systemd restart -r <REPO>
#+end_src

** Utility Namespaces
*** triangulum.cli
The triangulum.cli namespace provides a command-line interface (CLI) for Triangulum applications. It includes functions for parsing command-line options, displaying usage information, and checking for errors in the provided arguments.
** API
See [[file:API.md][API.md]]

**** Usage
Use get-cli-options to parse command-line arguments and return the user's options.

**** Example
#+BEGIN_SRC clojure
(def cli-options {...})

(def cli-actions {...})
(def alias-str "...")

(get-cli-options command-line-args cli-options cli-actions alias-str)
#+END_SRC

**** Functions
***** get-cli-options
Takes the command-line arguments, a map of CLI options, a map of CLI actions, an alias string, and an optional config map. Checks for valid CLI calls and returns the user's options.
#+END_SRC
*** triangulum.errors

The triangulum.errors namespace provides error handling utilities for the Triangulum application. It includes functions and macros to handle exceptions and log errors.

**** Functions
***** init-throw

Takes a message string as input and throws an exception with the provided message.

****** Example

#+BEGIN_SRC clojure
(init-throw "Error: Invalid input")
#+END_SRC

***** try-catch-throw

Takes a function try-fn and a message string as input. Executes the function and, if it throws an exception, catches the exception, logs the error, and then throws an exception with the augmented input message.

****** Example

#+BEGIN_SRC clojure
(try-catch-throw (fn [] (throw (ex-info "Initial error" {}))) "Augmented error message")
#+END_SRC

Public Macros
***** nil-on-error

Catches any exceptions thrown within its body and returns nil if an exception occurs. If no exception occurs, it returns the result of the body's evaluation.

****** Example

#+BEGIN_SRC clojure
(nil-on-error (/ 1 0)) ; Returns nil
(nil-on-error (+ 2 3)) ; Returns 5
#+END_SRC
*** triangulum.response

You can set ~:response-type~ to configure the ~data-response~ function's default return type (~:json~, ~:edn~, ~:transit~).

*** triangulum.utils

The ~triangulum.utils~ namespace provides a collection of utility functions for various purposes, such as text parsing, shell command execution, response building, and operations on maps and namespaces.

**** Functions
***** Text Parsing
****** kebab->snake

Converts a kebab-cased string to a snake_cased string.

****** kebab->camel

Converts a kebab-cased string to a camelCased string.

****** format-str

Formats a string with placeholders (e.g., "%s") replaced by the provided arguments.

****** parse-as-sh-cmd

Splits a string into an array for use with ~clojure.java.shell/sh~.

****** end-with

Appends a specified string to the end of another string, if it is not already there.

****** remove-end

Removes a specified string from the end of another string, if it is there.

***** Shell Commands
****** shell-wrapper

A wrapper around ~babashka.process/shell~ that logs the output and errors. Accepts an optional opts map as the first argument, followed by the command and its arguments. The ~:log?~ key in the opts map can be used to control logging (default is true).

****** DEPRECATED: sh-wrapper

Runs a set of bash commands in a specified directory and environment. Parses the output, creating an array as described in ~parse-as-sh-cmd~.

***** Response Building
****** DEPRECATED: data-response

Use 'triangulum.response/data-response' instead. Creates a response object with a specified body, status, content type, and session.

Operations on Maps
****** mapm

Applies a function to each MapEntry of a map, returning a new map.

****** filterm

Filters a map based on a predicate applied to each MapEntry, returning a new map.

****** reverse-map

Reverses the key-value pairs in a given map.

***** Equality Checking
****** find-missing-keys

Checks if the keys of one map are a subset of another map's keys, including nested maps.

***** Namespace Operations
****** resolve-foreign-symbol

Attempts to require a namespace-qualified symbol's namespace and resolve the symbol within that namespace to a value.

****** delete-recursively

Recursively delete all files and directories under the given directory.Traverses the directory tree in reverse depth-first order.

*** triangulum.type-conversion

The triangulum.type-conversion namespace provides a collection of functions for converting between different data types and formats, including conversions between numbers, booleans, JSON, and PostgreSQL data types.

**** Functions
***** Converting Numbers
****** val->int

Converts a value to a Java Integer. Default value for failed conversion is -1.

****** val->long

Converts a value to a Java Long. Default value for failed conversion is -1.

****** val->float

Converts a value to a Java Float. Default value for failed conversion is -1.0. Note that Postgres real is equivalent to Java Float.

****** val->double

Converts a value to a Java Double. Default value for failed conversion is -1.0. Note that Postgres float is equivalent to Java Double.

***** Converting Booleans
****** val->bool

Converts a value to a Java Boolean. Default value for failed conversion is false.

***** JSON Conversions
****** json->clj

Converts a JSON string to its Clojure equivalent.

****** jsonb->json

Converts a PostgreSQL jsonb object to a JSON string.

****** jsonb->clj

Converts a PostgreSQL jsonb object to its Clojure equivalent.

****** clj->json

Converts a Clojure value to a JSON string.

***** PostgreSQL Conversions
****** str->pg

Converts a string to a PostgreSQL object of a specified type.

****** json->jsonb

Converts a JSON string to a PostgreSQL jsonb object.

****** clj->jsonb

Converts a Clojure value to a PostgreSQL jsonb object.
*** triangulum.sockets
The triangulum.sockets namespace provides functionality for creating and managing client and server sockets. It includes functions for opening and checking socket connections, sending messages to the server, and starting/stopping socket servers with custom request handlers. This namespace enables communication between distributed systems and allows you to implement networked applications.

**** Functions
***** Client Socket Functions
****** socket-open?

Checks if the socket at the specified host and port is open.

****** send-to-server!

Attempts to send a socket message. Returns ~:success~ if successful.

***** Server Socket Functions
****** stop-socket-server!

Stops the running socket server.

****** start-socket-server!

Starts a socket server at the specified port with a custom request handler.
*** triangulum.notify
The triangulum.notify namespace provides functions to interact with systemd for process management and notifications. It utilizes the SDNotify Java library to send notifications and check the availability of the current process. The functions in this namespace allow you to check if the process is managed by systemd, send "ready," "reloading," and "stopping" messages, and send custom status messages. These functions can be helpful when integrating your application with systemd for better process supervision and management.

**** Functions
***** available?

Checks if this process is a process managed by systemd.

***** ready!

Sends a ready message to systemd. Systemd file must include Type=notify to be used.

***** reloading!

Sends a reloading message to systemd. Must call send-notify! once reloading has been completed.

***** stopping!

Sends a stopping message to systemd.

***** send-status!

Sends a custom status message to systemd. (e.g. (send-status! \"READY=1\")).
*** triangulum.email

Triangulum provides some functionality for sending email from an SMTP server. Given the configuration inside ~:mail~. ~:base-url~ is used to configure the host url, used when sending links in emails. ~:auto-validate~ can be used in development mode, for example, to skip sending emails, which has to be configured.

*** triangulum.logging

To send a message to the logger use ~log~ or ~log-str~. ~log~ can take an
optional argument to specify not default behavior. The default values are
shown below. ~log-str~ always uses the default values.

#+begin_src clojure
(log "Hello world" {:newline? true :pprint? false :force-stdout? false})
(log-str "Hello" "world")
#+end_src

By default the above will log to standard out. If you would like to
have the system log to YYYY-DD-MM.log, set a log path. You can either specify
a path relative to the toplevel directory of the main project repository or an
absolute path on your filesystem. The logger will keep the 10 most recent logs
(where a new log is created every day at midnight). To stop the logging server
set path to "".

#+begin_src clojure
(set-log-path "logs")
(set-log-path "")
#+end_src

*** triangulum.database

To use ~triangulum.database~, first add your database connection
configurations to a ~config.edn~ file in your project's root directory.

For example:
#+begin_src clojure
;; config.edn
{:database {:host "localhost"
:port 5432
:dbname "pyregence"
:user "pyregence"
:password "pyregence"}}
#+end_src

To run a postgres sql command use ~call-sql~. Currently ~call-sql~
only works with postgres. With the second parameter can be an
optional settings map (default values shown below).

#+begin_src clojure
(call-sql "function" {:log? true :use-vec? false} "param1" "param2" ... "paramN")
#+end_src

To run a sqllite3 sql command use ~call-sqlite~. An existing sqllite3 database
must be provided.

#+begin_src clojure
(call-sqlite "select * from table" "path/db-file")
#+end_src

To insert new rows or update existing rows use ~insert-rows!~ and
~update-rows!~. If fields are not provided, the first row will be assumed to
be the field names.

#+begin_src clojure
(insert-rows! table-name rows-vector fields-map)
(update-rows! table-name rows-vector column-to-update fields-map)
#+end_src

*** Triangulum.worker

The ~triangulum.worker~ namespace is responsible for the management of worker lifecycle within the ~:server~ context, specifically those defined under the ~:workers~ key. This namespace furnishes functions to initiate and terminate workers, maintaining their current state within an atom.

**** Functions

***** start-workers!

Starts a set of workers based on the provided configuration. The workers parameter can be either a map (for nested workers) or a vector (for namespaced workers).

For nested workers, the map keys are worker names and values are maps with :start (a symbol representing the start function) and :stop keys. The start function is called to start the worker.

For namespaced workers, the vector elements are maps with ::name (the worker name), ::start (a symbol representing the start function), and ::stop keys. The start function is called to start each worker.

Arguments:
- workers: a map or vector representing the workers to be started.

***** stop-workers!

Stops a set of currently running workers. The workers to stop are determined based on the current state of the `workers` atom. If the `workers` atom contains a map, it's assumed to be holding nested workers. If it contains a vector, it's assumed to be holding namespaced workers.

The stop function is called with the value to stop each worker.

There are no arguments for this function.
** Docs
To generate docs, use: ~bb docs~

** License

Expand Down
7 changes: 7 additions & 0 deletions bb.edn
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{:tasks
{docs {:doc "Invoke quickdoc"
:extra-deps {io.github.borkdude/quickdoc {:git/sha "7c8bef54eda28367193ec433af01bb940114f012"}}
:task (exec 'quickdoc.api/quickdoc)
:exec-args {:git/branch "main"
:github/repo "https://github.com/sig-gis/triangulum"
:source-paths ["src"]}}}}
16 changes: 15 additions & 1 deletion src/triangulum/cli.clj
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
(ns triangulum.cli
"Provides a command-line interface (CLI) for Triangulum applications. It includes functions for parsing command-line options, displaying usage information, and checking for errors in the provided arguments."
(:require [clojure.string :as str]
[clojure.tools.cli :refer [parse-opts]]
[triangulum.utils :refer [format-str]]))
Expand Down Expand Up @@ -85,7 +86,20 @@
options))

(defn get-cli-options
"Checks for a valid call from the CLI and returns the users options."
"Checks for a valid call from the CLI and returns the users options.
Takes the command-line arguments, a map of CLI options, a map of CLI actions,
an alias string, and an optional config map.
Example:
```clojure
(def cli-options {...})
(def cli-actions {...})
(def alias-str \"...\")
(get-cli-options command-line-args cli-options cli-actions alias-str)
```"
[args cli-options cli-actions alias-str & [config]]
(let [{:keys [options defaults]} (separate-options-defaults cli-options)
{:keys [arguments errors options]} (->> options
Expand Down
Loading

0 comments on commit e5d9a30

Please sign in to comment.