From e87d791e54758cbd4461bc1ef258843152efae00 Mon Sep 17 00:00:00 2001 From: mahlon Date: Sat, 1 Jul 2023 08:43:30 +0000 Subject: [PATCH] Cleanup comments for nimdoc, add 'latest' Makefile task. FossilOrigin-Name: 8835929c59b4fecb29f7bb2e96ca455ea17c4024839c8dce4c6ff01297c6594a --- Makefile | 9 +++++++-- src/lib/config.nim | 25 +++++++++++++------------ src/lib/logging.nim | 31 ++++++++++++++----------------- src/lib/message.nim | 33 ++++++++++++++++----------------- src/lib/util.nim | 35 ++++++++++++++++++----------------- src/sieb.nim | 15 +++++++++------ 6 files changed, 77 insertions(+), 71 deletions(-) diff --git a/Makefile b/Makefile index 570d207..0f86493 100644 --- a/Makefile +++ b/Makefile @@ -23,8 +23,7 @@ release:dependencies ${FILES} mv src/sieb . docs: - nim doc ${FILES} - mv src/htmldocs docs + nim doc --project --outdir:release/doc src/sieb.nim clean: fossil clean --dotfiles -f -v @@ -32,3 +31,9 @@ clean: clobber: fossil clean -x -v +latest: clobber docs + tar -C .. --exclude .f\* -zcvf ../sieb-latest.tar.gz sieb + mkdir release + mv ../sieb-latest.tar.gz release + fossil uv add release/sieb-latest.tar.gz + diff --git a/src/lib/config.nim b/src/lib/config.nim index 7f31186..5f0afcf 100644 --- a/src/lib/config.nim +++ b/src/lib/config.nim @@ -1,12 +1,13 @@ # vim: set et nosta sw=4 ts=4 : -# -# Methods for finding and parsing sieb rules from YAML. -# +## +## Methods for finding and parsing sieb rules from YAML. +## -############################################################# + +#------------------------------------------------------------ # I M P O R T S -############################################################# +#------------------------------------------------------------ import std/os, @@ -18,9 +19,9 @@ import import util -############################################################# +#------------------------------------------------------------ # C O N S T A N T S -############################################################# +#------------------------------------------------------------ const CONFFILES = @[ "/usr/local/etc/sieb/config.yml", @@ -28,9 +29,9 @@ const CONFFILES = @[ ] -############################################################# +#------------------------------------------------------------ # T Y P E S -############################################################# +#------------------------------------------------------------ type Rule* = object @@ -46,12 +47,12 @@ type rules* {.defaultVal: @[]}: seq[Rule] -############################################################# +#------------------------------------------------------------ # M E T H O D S -############################################################# +#------------------------------------------------------------ proc parse( path: string ): Config = - ## Return a parsed configuration from yaml. + ## Return a parsed configuration from yaml at `path`. "Using configuration at: $#".debug( path ) let stream = newFileStream( path ) try: diff --git a/src/lib/logging.nim b/src/lib/logging.nim index af4f94e..bca4d53 100644 --- a/src/lib/logging.nim +++ b/src/lib/logging.nim @@ -1,11 +1,11 @@ # vim: set et nosta sw=4 ts=4 : -# -# A global logger. Just write stuff to disk safely. -# +## +## A global logger. Just write stuff to disk safely. +## -############################################################# +#------------------------------------------------------------ # I M P O R T S -############################################################# +#------------------------------------------------------------ import std/math, @@ -16,28 +16,25 @@ import std/times -############################################################# +#------------------------------------------------------------ # T Y P E S -############################################################# +#------------------------------------------------------------ type Logger = object fh: File start: MonoTime -############################################################# +#------------------------------------------------------------ # G L O B A L E X P O R T S -############################################################# +#------------------------------------------------------------ -var logger*: Logger +var logger*: Logger ## The exported logger object. -############################################################# -# M E T H O D S -############################################################# - proc createLogger*( parentdir: string, filename: string ): void = - ## Get in line to open a write lock to the configured logfile at +path+. + ## Get in line to open a write lock to the configured logfile at + ## `filename` under `parentdir` directory. ## This will block until it can get an exclusive lock. let path = joinPath( parentdir, filename ) try: @@ -62,12 +59,12 @@ proc close*( l: Logger ): void = proc closed*( l: Logger ): bool = - ## Returns +false+ if the logfile has been opened. + ## Returns `false` if the logfile has been opened. return l.fh.isNil proc log*( msg: string ): void = - ### Emit a line to the logfile. + ## Emit a line to the logfile. if logger.closed: return logger.fh.writeLine( msg ) diff --git a/src/lib/message.nim b/src/lib/message.nim index 70ef0f9..043938d 100644 --- a/src/lib/message.nim +++ b/src/lib/message.nim @@ -1,12 +1,13 @@ # vim: set et nosta sw=4 ts=4 : -# -# A class that represents an individual Maildir, and a Nessage class to nanage -# files underneath them. -# -############################################################# +## +## A class that represents an individual Maildir, and a Message class to nanage +## files underneath them. +## + +#------------------------------------------------------------ # I M P O R T S -############################################################# +#------------------------------------------------------------ import std/os, @@ -24,9 +25,9 @@ import util -############################################################# +#------------------------------------------------------------ # C O N S T A N T S -############################################################# +#------------------------------------------------------------ const OWNERDIRPERMS = { fpUserExec, fpUserWrite, fpUserRead } @@ -36,14 +37,14 @@ const BUFSIZE = 8192 # reading and writing buffer size -############################################################# +#------------------------------------------------------------ # T Y P E S -############################################################# +#------------------------------------------------------------ # A Maildir object. # type Maildir* = ref object - path*: string # Absolute path to the encapsualting dir + path*: string ## Absolute path to the encapsuating dir cur: string new: string tmp: string @@ -63,13 +64,12 @@ var msgId = "" # The parsed Message-ID -############################################################# +#------------------------------------------------------------ # M E T H O D S -############################################################# +#------------------------------------------------------------ -#------------------------------------------------------------ # Maildir -#------------------------------------------------------------ +#------------ proc newMaildir*( path: string ): Maildir = ## Create and return a new Maildir object, making it on-disk if necessary. @@ -95,9 +95,8 @@ proc subDir*( dir: Maildir, path: string ): Maildir = result = newMaildir( dir.path & "/" & path ) -#------------------------------------------------------------ # Message -#------------------------------------------------------------ +#------------ proc newMessage*( dir: Maildir ): Message = ## Create and return a Message - an open FileStream under a specific Maildir diff --git a/src/lib/util.nim b/src/lib/util.nim index 1a79940..d0c7616 100644 --- a/src/lib/util.nim +++ b/src/lib/util.nim @@ -1,11 +1,12 @@ # vim: set et nosta sw=4 ts=4 : -# -# Various helper functions that don't have a better landing spot. -# -############################################################# +## +## Various helper functions that don't have a better landing spot. +## + +#------------------------------------------------------------ # I M P O R T S -############################################################# +#------------------------------------------------------------ import std/parseopt, @@ -16,12 +17,12 @@ import logging -############################################################# +#------------------------------------------------------------ # C O N S T A N T S -############################################################# +#------------------------------------------------------------ const - VERSION = "v0.1.0" + VERSION = "v0.1.0" ## The current Sieb version USAGE = """ ./sieb [-c] [-d] [-h] [-v] @@ -114,9 +115,9 @@ const """ -############################################################# +#------------------------------------------------------------ # T Y P E S -############################################################# +#------------------------------------------------------------ type Opts = object config*: string # The path to an explicit configuration file. @@ -124,16 +125,16 @@ type Opts = object logfile*: string # Log actions to disk. -############################################################# +#------------------------------------------------------------ # G L O B A L E X P O R T S -############################################################# +#------------------------------------------------------------ -var opts*: Opts +var opts*: Opts ## Parsed command line options. -############################################################# +#------------------------------------------------------------ # M E T H O D S -############################################################# +#------------------------------------------------------------ proc hl( msg: string, fg: ForegroundColor, bright=false ): string = ## Quick wrapper for color formatting a string, since the 'terminal' @@ -152,7 +153,7 @@ proc deferral*( msg: string ) = proc debug*( msg: string, args: varargs[string, `$`] ) = - ## Emit +msg+ if debug mode is enabled, coercing arguments into a string for + ## Emit `msg` if debug mode is enabled, coercing arguments into a string for ## formatting. if opts.debug or not logger.closed: var str = msg % args @@ -161,7 +162,7 @@ proc debug*( msg: string, args: varargs[string, `$`] ) = proc parseCmdline*() = - ## Populate the opts object with the user's preferences. + ## Populate the global opts object with the user's preferences. # Config object defaults. # diff --git a/src/sieb.nim b/src/sieb.nim index a28d487..2a60ad4 100644 --- a/src/sieb.nim +++ b/src/sieb.nim @@ -1,8 +1,11 @@ # vim: set et nosta sw=4 ts=4 : +## +## Primary logic for a single email delivery. +## -############################################################# +#------------------------------------------------------------ # I M P O R T S -############################################################# +#------------------------------------------------------------ import std/exitprocs, @@ -15,9 +18,9 @@ import lib/util -############################################################# +#------------------------------------------------------------ # S E T U P -############################################################# +#------------------------------------------------------------ # Without this, we got nuthin'! if not existsEnv( "HOME" ): @@ -39,9 +42,9 @@ var finalTasks = proc: void = finalTasks.addExitProc -############################################################# +#------------------------------------------------------------ # M A I N -############################################################# +#------------------------------------------------------------ # Parse the YAML ruleset. let conf = getConfig( opts.config )