diff --git a/doc/d-utils.md b/doc/d-utils.md index 2f6a726..5dd67c2 100644 --- a/doc/d-utils.md +++ b/doc/d-utils.md @@ -74,3 +74,53 @@ Uses ```csv-parse-lines``` on lines read from given file ```fn```. (csv-split-header csv) Splits given loaded CSV into two tables at the first empty row. + +## util-git [module] + + (import util-git) + +This module provides basic git repository querying functionality. + +### git [procedure] + + (git repo + (defmodesym (quote output))) + + +* ```repo``` - a path to repository +* ```mode``` - return values mode for operations + +Returns a procedure that allows invocation of git in given ```repo``` +repository returning one or two values based on ```mode``` given: + +* ```#:exit``` - returns exit code +* ```#:output``` - returns the output lines (default) +* ```#:exit+output``` - returns both exit code and output lines + + +### git-status [procedure] + + (git-status repo) + + +* ```repo``` - git repository + +Returns a dictionary with the following keys: + +* ```'modified``` - list of modified files +* ```'untracked``` - list of untracked files +* ```'unknown``` - list of files with unknown status + + +### git-blame [procedure] + + (git-blame repo + fname) + + +* ```repo``` - git repository +* ```fname``` - file name (path) relative to the git repository + +Returns annotated source with information about originating commits +for each line. + diff --git a/doc/utils.md b/doc/utils.md index 2d82f07..1fbf891 100644 --- a/doc/utils.md +++ b/doc/utils.md @@ -139,34 +139,6 @@ Converts given number to a string with two-digit fractional part. Should the fractional part be 0, it is replaced with the string "--". -### Git - - (import util-git) - -This module provides basic git repository querying functionality. - - (git repo [mode]) - -* ```repo``` - a path to repository -* ```mode``` - return values mode for operations - -Returns a procedure that allows invocation of git in given ```repo``` -repository returning one or two values based on ```mode``` given: - -* ```#:exit``` - returns exit code -* ```#:output``` - returns the output lines (default) -* ```#:exit+output``` - returns both exit code and output lines - - (git-status repo) - -* ```repo``` - git repository - -Returns a dictionary with the following keys: - -* ```'modified``` - list of modified files -* ```'untracked``` - list of untracked files -* ```'unknown``` - list of files with unknown status - ### IO (import util-io) diff --git a/src/Makefile b/src/Makefile index 7fdae6d..b23cf8d 100644 --- a/src/Makefile +++ b/src/Makefile @@ -56,13 +56,13 @@ HACKERBASE-OBJS=hackerbase.o testing.o listing.o cal-month.o \ sgr-list.o sgr-block.o table-processor.o table-border.o \ table-style.o sgr-state.o util-utf8.o sgr-cell.o \ template-list-expander.o box-drawing.o util-list.o \ - export-web-static.o util-dir.o dokuwiki.o + export-web-static.o util-dir.o dokuwiki.o racket-kwargs.o -GENDOC-SOURCES=gendoc.scm duck-extract.import.scm \ - util-time.import.scm util-csv.import.scm +GENDOC-SOURCES=gendoc.scm duck-extract.import.scm \ + util-time.import.scm util-csv.import.scm util-git.import.scm GENDOC-OBJS=gendoc.o duck-extract.o util-time.o util-csv.o util-io.o \ - progress.o testing.o util-proc.o + progress.o testing.o util-proc.o util-git.o .PHONY: imports imports: $(HACKERBASE-DEPS) @@ -369,9 +369,9 @@ SPECIFICATION-SOURCES=specification.scm cal-period.import.scm specification.o: specification.import.scm specification.import.scm: $(SPECIFICATION-SOURCES) -UTIL-GIT-SOURCES=util-git.scm util-io.import.scm \ - util-dict-list.import.scm util-parser.import.scm \ - util-time.import.scm +UTIL-GIT-SOURCES=util-git.scm util-io.import.scm \ + util-dict-list.import.scm util-parser.import.scm \ + util-time.import.scm duck.import.scm racket-kwargs.import.scm util-git.o: util-git.import.scm util-git.import.scm: $(UTIL-GIT-SOURCES) @@ -412,6 +412,7 @@ util-dict-bst.import.scm: $(UTIL-DICT-BST-SOURCES) RACKET-KWARGS-SOURCES=racket-kwargs.scm +racket-kwargs.o: racket-kwargs.import.scm racket-kwargs.import.scm: $(RACKET-KWARGS-SOURCES) TABLE-SOURCES=table.scm sgr-list.import.scm sgr-block.import.scm \ diff --git a/src/gendoc.scm b/src/gendoc.scm index 2213f67..fdd8a3e 100644 --- a/src/gendoc.scm +++ b/src/gendoc.scm @@ -21,4 +21,5 @@ "Utility modules" "These are various utility modules for other HackerBase libraries." util-time - util-csv) + util-csv + util-git) diff --git a/src/racket-kwargs.scm b/src/racket-kwargs.scm index 59ac24e..36e3ef4 100644 --- a/src/racket-kwargs.scm +++ b/src/racket-kwargs.scm @@ -26,6 +26,8 @@ ;; CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ;; +(declare (unit racket-kwargs)) + (module racket-kwargs ( diff --git a/src/util-git.scm b/src/util-git.scm index ac15cf1..de7e02f 100644 --- a/src/util-git.scm +++ b/src/util-git.scm @@ -25,8 +25,11 @@ (declare (unit util-git)) -(module +(import duck) + +(module* util-git + #:doc ("This module provides basic git repository querying functionality.") ( git git-status @@ -39,13 +42,14 @@ util-io util-dict-list util-parser - util-time) + util-time + racket-kwargs) ;; Valid git operating modes (define git-modes - '((#:exit exit) - (#:output output) - (#:exit+output exit+output))) + '((exit exit) + (output output) + (exit+output exit+output))) ;; Used for actual invocation of git binary, returns two values: exit ;; code and output lines @@ -57,11 +61,20 @@ args)) ;; Curried git repo command wrapper - (define (git repo . defargs) - (let ((defmode (if (null? defargs) - 'output - ;; Raises an error if not valid - (cadr (assq (car defargs) git-modes))))) + (define*/doc (git repo (defmodesym 'output)) + (" +* ```repo``` - a path to repository +* ```mode``` - return values mode for operations + +Returns a procedure that allows invocation of git in given ```repo``` +repository returning one or two values based on ```mode``` given: + +* ```#:exit``` - returns exit code +* ```#:output``` - returns the output lines (default) +* ```#:exit+output``` - returns both exit code and output lines +") + ;; Raises an error if not valid + (let ((defmode (cadr (assq defmodesym git-modes)))) (case defmode ((exit) (lambda args @@ -83,7 +96,16 @@ ("??" untracked))) ;; Returns a dictionary of unknown, modified, deleted and added files - (define (git-status repo) + (define/doc (git-status repo) + (" +* ```repo``` - git repository + +Returns a dictionary with the following keys: + +* ```'modified``` - list of modified files +* ```'untracked``` - list of untracked files +* ```'unknown``` - list of files with unknown status +") (let* ((lines ((git repo) 'status '--porcelain)) (clean? (null? lines))) (let loop ((lines lines) @@ -105,7 +127,14 @@ ;; Returns detailed file annotation with each line being represented ;; by dictionary with keys from git output - (define (git-blame repo fname) + (define/doc (git-blame repo fname) + (" +* ```repo``` - git repository +* ```fname``` - file name (path) relative to the git repository + +Returns annotated source with information about originating commits +for each line. +") (let loop ((lines ((git repo) 'blame '--line-porcelain fname)) (blame (make-ldict)) (blames '()))