diff --git a/doc/.vuepress/config.js b/doc/.vuepress/config.js index 90afb59b4b..da17864b23 100644 --- a/doc/.vuepress/config.js +++ b/doc/.vuepress/config.js @@ -147,17 +147,6 @@ module.exports = { ] }, - { title: "Support for the Unix Command Line Interface", - path: "/reference/std/cli/", - children: [ - "cli/", - "cli/getopt", - "cli/shell", - "cli/print-exit", - "cli/multicall", - ] - }, - { title: "Miscellaneous Libraries", path: '/reference/std/misc/', children: [ diff --git a/doc/reference/std/errors.md b/doc/reference/std/errors.md index 93f9c92139..9c5aee9a1a 100644 --- a/doc/reference/std/errors.md +++ b/doc/reference/std/errors.md @@ -426,23 +426,7 @@ displaying the exception with `display-exception`). ``` Invokes `thunk` with an exception handler that dumps the exception -stack trace with `dump-stack-trace!` -if `(dump-stack-trace?)` is true (the default). - -### dump-stack-trace? -```scheme -(define dump-stack-trace? (make-parameter #t)) -``` -A parameter that controls whether `with-exception-stack-trace` -will actually dump a stack trace to standard error. - -You can `(dump-stack-trace? #f)` -or locally `(parameterize ((dump-stack-trace? #f)) ...)` -to disable this stack trace dump, -in case you are building a program for end-users rather than for developers, -and want to control what limited error output they see. -Or you can re-enable them based on a debug flag at the CLI -in cases you want them to provide you with extra debugging information. +stack trace with `dump-stack-trace!`. ### dump-stack-trace! ```scheme @@ -451,38 +435,3 @@ in cases you want them to provide you with extra debugging information. Displays the exception `exn`, dumping the stack trace of continuation `cont` if there is no stack trace information in the exception itself. - -### exit-with-error -```scheme -(exit-with-error exception) => [exit] -``` -Display the `exception` to current error port and exit with error code 2. - -### exit-on-error? -```scheme -(def exit-on-error? (make-parameter #t)) -``` -This parameter controls whether `call-with-exit-on-error`, `with-exit-on-error`, -`call-with-getopt`, and any function that indirectly uses them, -will exit if an error is caught, rather than pass on the error -and return to the REPL (or let a more fundamental function exit). - -### call-with-exit-on-error -```scheme -(call-with-exit-on-error thunk) -``` -Calls the `thunk` in an environment wherein if an error is caught and -`(exit-on-error)` is true, `exit-with-error` will be called, -causing an error message to be printed and the process to exit with exit code 2. -If `(exit-on-error)` is false, the error will simply be raised again. - -This mechanism enables users to modify the parameter -(e.g. via a flag passed at the Unix CLI or a change made at the Scheme REPL) -and control whether to exit with an error (e.g. for end-users) -or enter a debugger REPL (e.g. for developers). - -### with-exit-on-error -```scheme -(with-exit-on-error body ...) -``` -Evaluates the `body` as in a `thunk` passed to `call-with-exit-on-error`. diff --git a/doc/reference/std/getopt.md b/doc/reference/std/getopt.md index ef485817c2..726ef89f15 100644 --- a/doc/reference/std/getopt.md +++ b/doc/reference/std/getopt.md @@ -1,15 +1,188 @@ # Command Line Argument Parsing -This is the old name of the `:std/cli/getopt` module, -that provides facilities for command line argument parsing. - -As of Gerbil v0.19 this name is deprecated and -you should be using the new library instead, -but the old name remains available for now -for the sake of backward compatibility. +The `:std/getopt` library provides facilities for command line argument parsing. ::: tip usage -(import :std/cli/getopt) +(import :std/getopt) ::: -See [:std/cli/getopt](cli/getopt.md) for the module documentation. +## Interface + +### getopt +```scheme +(getopt ...) +=> + +specifier: + (command id [help: text] ) + ... + +cmd-specifier: + (flag id short [long]) + (option id short [long] [help: text] [value: proc] [default: value]) + (argument id [help: text] [value: proc]) + (optional-argument id [help: text] [value: proc] [default: value]) + (rest-arguments id [help: text] [value: proc]) + +``` + +`getopt` creates a command line parser, which can be used to parse arguments +with `getopt-parse`. + +### getopt-parse +```scheme +(getopt-parse args) +=> (values cmd-id options) + options +``` + +`getopt-parse` accepts a parser and a list of string arguments and parses +according to the parser specification. If it is parsing a specification with +subcommands, it returns two values, the command id and a hash table with the +parsed options. Otherwise it just returns the hash table with the parsed options. +An exception is raised if parsing the arguments fails. + +### getopt-error? +```scheme +(getopt-error? obj) +=> boolean +``` + +If parsing fails, then a `getopt-error` is raised, which can be guarded with +`getopt-error?`. + +### getopt-display-help +```scheme +(getopt-display-help program-name [port = (current-output-port)]) + + +tip: + + + +``` + +The procedure `getopt-display-help` can be used to display +a help message for a getopt error according to the argument specification. + +### getopt-display-help-topic +```scheme +(getopt-display-help-topic topic program-name [port = (current-output-port)]) +``` + +The procedure `getopt-display-help-topic` can be used to display a help page +for a subcommand. + +### getopt? +```scheme +(getopt? obj) +=> boolean +``` + +Returns true if the object is a getopt parser + +### getopt-object? +```scheme +(getopt-object? obj) +=> boolean +``` + +Returns true if the object is a getopt command or command specifier. + +### call-with-getopt +```scheme +(call-with-getopt proc args + program: program + help: (help #f) + exit-on-error: (exit-on-error? #t) + . gopts) +``` + +This shim around getopt parsing eliminates all the repetitive +boilerplate around argument parsing with getopt. + +It creates a getopt parser that parses with options `gopts`, automatically +including a help option or command accordingly. + +It then uses the parser to pare `args`, handling the exceptions and +displayin help accordingly; if `exit-on-error` is true (the default), +then parsing errors will exit the program. + +If the parse succeeds it invokes `proc` with the output of the parse. + +## Example + +For an example, here the a command line parser for the `gxpkg` program: +```scheme +(def (main . args) + (def install-cmd + (command 'install help: "install one or more packages" + (rest-arguments 'pkg help: "package to install"))) + (def uninstall-cmd + (command 'uninstall help: "uninstall one or more packages" + (flag 'force "-f" help: "force uninstall even if there are orphaned dependencies") + (rest-arguments 'pkg help: "package to uninstall"))) + (def update-cmd + (command 'update help: "update one or more packages" + (rest-arguments 'pkg help: "package to update; all for all packages"))) + (def link-cmd + (command 'link help: "link a local development package" + (argument 'pkg help: "package to link") + (argument 'src help: "path to package source directory"))) + (def unlink-cmd + (command 'unlink help: "unlink one or more local development packages" + (flag 'force "-f" help: "force unlink even if there are orphaned dependencies") + (rest-arguments 'pkg help: "package to unlink"))) + (def build-cmd + (command 'build help: "rebuild one or more packages and their dependents" + (rest-arguments 'pkg help: "package to build; all for all packages"))) + (def clean-cmd + (command 'clean help: "clean compilation artefacts from one or more packages" + (rest-arguments 'pkg help: "package to clean"))) + (def list-cmd + (command 'list help: "list installed packages")) + (def retag-cmd + (command 'retag help: "retag installed packages")) + (def search-cmd + (command 'search help: "search the package directory" + (rest-arguments 'keywords help: "keywords to search for"))) + + (call-with-getopt gxpkg-main args + program: "gxpkg" + help: "The Gerbil Package Manager" + install-cmd + uninstall-cmd + update-cmd + link-cmd + unlink-cmd + build-cmd + clean-cmd + list-cmd + retag-cmd + search-cmd)) + +(def (gxpkg-main cmd opt) + (let-hash opt + (case cmd + ((install) + (install-pkgs .pkg)) + ((uninstall) + (uninstall-pkgs .pkg .?force)) + ((update) + (update-pkgs .pkg)) + ((link) + (link-pkg .pkg .src)) + ((unlink) + (unlink-pkgs .pkg .?force)) + ((build) + (build-pkgs .pkg)) + ((clean) + (clean-pkgs .pkg)) + ((list) + (list-pkgs)) + ((retag) + (retag-pkgs)) + ((search) + (search-pkgs .keywords))))) + +``` diff --git a/doc/reference/std/misc/list.md b/doc/reference/std/misc/list.md index e3ce069915..1a4a4ae2bc 100644 --- a/doc/reference/std/misc/list.md +++ b/doc/reference/std/misc/list.md @@ -1,14 +1,14 @@ # List utilities ::: tip To use the bindings from this module: -```scheme +``` scheme (import :std/misc/list) ``` ::: ## length=?, length<? ... length>=? ## -```scheme +``` scheme (length=? lst1 lst2) -> boolean (length boolean (length<=? lst1 lst2) -> boolean @@ -37,7 +37,7 @@ lengths up-front. Also, either of these two lists is allowed to be circular, but not both. ::: tip Examples: -```scheme +``` scheme > (import :std/srfi/1) > (def small (iota 10)) ; => (0 1 ... 9) > (def large (iota 100)) ; => (0 1 ... 99) @@ -55,7 +55,7 @@ Also, either of these two lists is allowed to be circular, but not both. ## length=n?, length<n? ... length>=n? ## -```scheme +``` scheme (length=n? lst n) -> boolean | error (length boolean | error (length<=n? lst n) -> boolean | error @@ -83,7 +83,7 @@ the list for up to *n* elements instead of calculating *lst*'s length up-front. Also, *lst* is allowed to be circular. ::: tip Examples: -```scheme +``` scheme > (length=n? [#\a #\b #\c] 3) #t @@ -98,7 +98,7 @@ Also, *lst* is allowed to be circular. ## snoc, append1 ## -```scheme +``` scheme (snoc elem lst) -> list | error elem := element to append to lst @@ -112,7 +112,7 @@ Different from `cons`: `snoc` will signal an error when *lst* is not a proper list. `cons`, in contrast, constructs a pair out of these two input values. ::: tip Examples: -```scheme +``` scheme > (cons 4 [1 2 3]) (4 1 2 3) @@ -132,7 +132,7 @@ error ; expects a list as second argument ## append1 ## -```scheme +``` scheme (append1 lst elem) -> list | error lst := proper list @@ -150,7 +150,7 @@ Note that `snoc` and `append1` have the same function body, just with their two arguments swapped. ::: tip Examples: -```scheme +``` scheme > (append [1 2 3] 4) (1 2 3 . 4) @@ -170,7 +170,7 @@ error ; expects a list as first argument ## for-each! ## -```scheme +``` scheme (for-each! lst proc) -> void lst := proper or even improper list @@ -182,7 +182,7 @@ swapped which allows better nesting. Another slight difference: `for-each!` even accepts improper lists. ::: tip Examples: -```scheme +``` scheme > (def exprs [[2 + 0] [2 - 0] [0 * 2] [2 / 0] [0 / 2]]) > (for-each (match <> @@ -217,7 +217,7 @@ error ; list expected ## push! ## -```scheme +``` scheme (push! elem lst) -> unspecified | error elem := element to cons onto lst @@ -231,7 +231,7 @@ Note that the argument order is element first and list second, as is traditional with the original Lisp `PUSH` macro. ::: tip Examples: -```scheme +``` scheme > (def lst []) > (push! 10 lst) > (push! 20 lst) @@ -251,7 +251,7 @@ error ; uses set! internally, requires valid binding ## pop! ## -```scheme +``` scheme (pop! lst) -> #f | elem elem := first element from lst @@ -263,7 +263,7 @@ the car of that cons cell, and sets *lst* to the cdr of that cons cell, otherwise returns `#f`. ::: tip Examples: -```scheme +``` scheme > (def lst []) > (pop! lst) #f @@ -280,7 +280,7 @@ otherwise returns `#f`. ## flatten ## -```scheme +``` scheme (flatten tree) -> list tree := nested list of lists @@ -306,7 +306,7 @@ left to right into a list, that is returned. ## flatten1 ## -```scheme +``` scheme (flatten1 lst) -> list | error lst := proper nested list-of-lists @@ -320,7 +320,7 @@ Note: *lst* is expected to be a list of proper lists, association lists will signal an error. ::: tip Examples: -```scheme +``` scheme > (flatten1 [1 [2 3] [[4 5]]]) (1 2 3 (4 5)) @@ -340,7 +340,7 @@ error ; expects proper non-dotted list-of-lists ## unique, unique! ## -```scheme +``` scheme (unique lst [test = equal?]) -> list lst := proper list @@ -349,7 +349,7 @@ error ; expects proper non-dotted list-of-lists Alias for `delete-duplicates` and `delete-duplicates!` ([SRFI 1](https://srfi.schemers.org/srfi-1/srfi-1.html#delete-duplicates)). ::: tip Examples: -```scheme +``` scheme > (unique [1 2 3 2]) (1 2 3) @@ -361,7 +361,7 @@ Alias for `delete-duplicates` and `delete-duplicates!` ([SRFI 1](https://srfi.sc ## duplicates ## -```scheme +``` scheme (duplicates lst [test = equal?] [key: #f]) -> list lst := proper list @@ -373,7 +373,7 @@ that occurs more than once in `lst`. If `key:` is not `#f` the unary procedure is applied to every element before comparison. ::: tip Examples: -```scheme +``` scheme > (duplicates ['a 1 'a]) ((a . 2)) @@ -387,7 +387,7 @@ the unary procedure is applied to every element before comparison. ## rassoc ## -```scheme +``` scheme (rassoc elem alist [pred = eqv?]) -> pair | #f elem := element to search for in alist @@ -403,7 +403,7 @@ Returns the first pair in *alist* whose `cdr` satisfies the predicate *pred*, or otherwise. ::: tip Examples: -```scheme +``` scheme > (rassoc 2 '((a . 1) (b . 2) (c . 2) (d . 1))) (b . 2) @@ -420,7 +420,7 @@ otherwise. ## when/list ## -```scheme +``` scheme (when/list cond lst) -> list | [] cond := expression that evaluates to a generalized boolean @@ -432,7 +432,7 @@ It is meant to be used when a list is expected, for instance, a list of options that are only defined when some feature is enabled or other condition is true. ::: tip Examples: -```scheme +``` scheme > (when/list #t [mykw: 42]) (mykw: 42) > (when/list #f [mykw: 42]) @@ -444,7 +444,7 @@ that are only defined when some feature is enabled or other condition is true. ## when-list-or-empty ## -```scheme +``` scheme (when-list-or-empty lst body ...) -> body ... | [] lst := value or list on which expansion depends @@ -454,7 +454,7 @@ Macro which expands to *body* expressions only if *lst* is a non-empty list, otherwise an empty list is returned. ::: tip Examples: -```scheme +``` scheme > (let (nums [1 2 3]) (when-list-or-empty nums (cdr nums))) @@ -468,7 +468,7 @@ otherwise an empty list is returned. ## listify ## -```scheme +``` scheme (listify x) -> list x := expression that is returned if a list, or else [] is returned @@ -478,7 +478,7 @@ otherwise an empty list is returned. otherwise return the empty list `[]`. ::: tip Examples: -```scheme +``` scheme > (listify 42) () > (listify []) @@ -492,7 +492,7 @@ otherwise return the empty list `[]`. ## keyword-when ## -```scheme +``` scheme (keyword-when cond [value]) -> list keyword := arbitrary value, usually a keyword @@ -507,7 +507,7 @@ If `value` is not specified, the non-false value returned by `cond` is used `keyword` doesn't actually have to be a keyword. ::: tip Examples: -```scheme +``` scheme > (keyword-when mykw: #t 42) (mykw: 42) > (keyword-when mykw: #f 42) @@ -525,7 +525,7 @@ If `value` is not specified, the non-false value returned by `cond` is used ## slice ## -```scheme +``` scheme (slice lst start [limit = #f]) -> list lst := proper list @@ -537,7 +537,7 @@ Returns a list from `lst`, starting from the left at `start`, containing `limit` elements. ::: tip Examples: -```scheme +``` scheme > (slice [1 2 3 4] 2) (3 4) @@ -548,7 +548,7 @@ containing `limit` elements. ## slice-right ## -```scheme +``` scheme (slice-right lst start [limit = #f]) -> list lst := proper list @@ -560,7 +560,7 @@ Returns a list from `lst`, starting from the right at `start`, containing `limit` elements. ::: tip Examples: -```scheme +``` scheme > (slice-right [1 2 3 4] 2) (1 2) @@ -571,7 +571,7 @@ containing `limit` elements. ## slice! ## -```scheme +``` scheme (slice! lst start [limit = #f]) -> list lst := proper list @@ -583,7 +583,7 @@ Returns a sublist by potentially updating the input list `lst`. Starting from the left at `start`, containing `limit` elements. ::: tip Examples: -```scheme +``` scheme > (def lst [1 2 3 4 5]) > (slice! lst 2 2) (3 4) @@ -592,7 +592,7 @@ Starting from the left at `start`, containing `limit` elements. ## slice-right! ## -```scheme +``` scheme (slice-right! lst start [limit = #f]) -> list lst := proper list @@ -604,7 +604,7 @@ Returns a sublist by potentially updating the input list `lst`. Starting from the right at `start`, containing `limit` elements. ::: tip Examples: -```scheme +``` scheme > (def lst [1 2 3 4 5]) > (slice-right! lst 2 2) (2 3) @@ -613,7 +613,7 @@ Starting from the right at `start`, containing `limit` elements. ## butlast ## -```scheme +``` scheme (butlast lst) -> list lst := proper list @@ -623,7 +623,7 @@ Starting from the right at `start`, containing `limit` elements. When `lst` is empty, `lst` is returned as it is. ::: tip Examples: -```scheme +``` scheme > (butlast [1 2 3]) (1 2) @@ -634,7 +634,7 @@ When `lst` is empty, `lst` is returned as it is. ## split ## -```scheme +``` scheme (split lst proc [limit = #f]) -> list lst := proper list @@ -645,7 +645,7 @@ split the list `lst` into a list-of-lists using the value or unary procedure `stop`. If limit is set, split the list only limit times. ::: tip Examples: -```scheme +``` scheme (split '(1 2 "hi" 3 4) string?) > ((1 2) (3 4)) @@ -661,7 +661,7 @@ unary procedure `stop`. If limit is set, split the list only limit times. ## take-until! ## -```scheme +``` scheme (take-until pred lst) -> list pred := predicate @@ -672,7 +672,7 @@ unary procedure `stop`. If limit is set, split the list only limit times. `take-until!` is the linear-update variant of `take-until`. ::: tip Examples: -```scheme +``` scheme > (take-until number? ['a "hi" 1 'c]) (a "hi") ``` @@ -680,7 +680,7 @@ unary procedure `stop`. If limit is set, split the list only limit times. ## drop-until ## -```scheme +``` scheme (drop-until pred lst) -> list pred := predicate @@ -690,7 +690,7 @@ unary procedure `stop`. If limit is set, split the list only limit times. `drop-until` returns a list with all elements from the point on `pred` returns `#t`. ::: tip Examples: -```scheme +``` scheme > (drop-until number? ['a [] "hi" 1 'c]) (1 c) ``` @@ -698,7 +698,7 @@ unary procedure `stop`. If limit is set, split the list only limit times. ## group-consecutive ## -```scheme +``` scheme (group-consecutive lst [test = equal?]) -> list lst := proper list @@ -709,7 +709,7 @@ wherein elements that satisfy the predicate with the previous element are put in the same list, but those that don't are put in the next list. ::: tip Examples: -```scheme +``` scheme > (group-consecutive [1 2 2 3 1 1]) ((1) (2 2) (3) (1 1)) @@ -724,7 +724,7 @@ are put in the same list, but those that don't are put in the next list. ## group-n-consecutive ## -```scheme +``` scheme (group-n-consecutive n lst) -> list-of-list n := a positive integer @@ -740,7 +740,7 @@ If `lst` is an improper list, the last element of the result will be an improper list with the same terminator. ::: tip Examples: -```scheme +``` scheme > (group-n-consecutive 2 [1 2 2 3 1 1]) ((1 2) (2 3) (1 1)) @@ -761,7 +761,7 @@ improper list with the same terminator. ## group-same ## -```scheme +``` scheme (group-same lst key: [key] table: [table]) -> list-of-list lst := list @@ -781,7 +781,7 @@ and are each lists containing elements with the same key in the same order as their appear in the original list. ::: tip Examples: -```scheme +``` scheme > (group-same [1 2 2 3 1]) ((1 1) (2 2) (3)) @@ -792,7 +792,7 @@ in the same order as their appear in the original list. ## map/car ## -```scheme +``` scheme (map/car f pair) f := function acting on the car of the pair @@ -801,7 +801,7 @@ in the same order as their appear in the original list. returns a new pair where the first element (car) has been transformed by the function `f`. ::: tip Examples: -```scheme +``` scheme > (map/car (cut * 10 <>) (cons 3 4)) (30 . 4) ``` @@ -809,7 +809,7 @@ returns a new pair where the first element (car) has been transformed by the fun ## every-consecutive? ## -```scheme +``` scheme (every-consecutive? pred lst) ``` returns a boolean that is true if any two consecutive terms in the list satisfy the predicate. @@ -818,7 +818,7 @@ order predicate), then the list is totally ordered (respectively strictly totall according to the predicate. ::: tip Examples: -```scheme +``` scheme > (every-consecutive? <= [1 2 2 3 10 100]) #t @@ -829,7 +829,7 @@ according to the predicate. ## separate-keyword-arguments ## -```scheme +``` scheme (separate-keyword-arguments args [positionals-only]) -> (values positional-args keyword-args) ``` Given a list of arguments passed to a function, return two values, @@ -847,7 +847,7 @@ are filtered off so the first value is ready to be matched positionally against a list of variables of the same length (and/or with a rest argument). ::: tip Examples: -```scheme +``` scheme > (separate-keyword-arguments '(x a: 1 y b: 2 c: 3 z)) (x y z) (a: 1 b: 2 c: 3) @@ -864,14 +864,14 @@ against a list of variables of the same length (and/or with a rest argument). ## first-and-only ## -```scheme +``` scheme (first-and-only lst) ``` returns the first and only value of a singleton list, or raises an error if the argument wasn't a singleton list. ::: tip Examples: -```scheme +``` scheme > (first-and-only '(42)) 42 diff --git a/doc/reference/std/misc/string.md b/doc/reference/std/misc/string.md index 312e54979f..5323f0148b 100644 --- a/doc/reference/std/misc/string.md +++ b/doc/reference/std/misc/string.md @@ -184,109 +184,6 @@ perform, otherwise an error is signaled. ``` ::: -## string-substitute-char-if -``` scheme -(string-substitute-char-if string newchar predicate - [start: #f] - [end: #f] - [from-end: #f] - [count: #f] - [in-place: #f]) => string-with-substitutions -``` - -Substitutes/replaces in *string* the characters matching the *predicate* -with the character *newchar*. - -Only substitute characters in the substring -defined by the *start* index (included, defaults to `0`) and -the *end* index (excluded, defaults to the length of the string). - -The replacement starts *from-end* if specified as true, -which only matters if *count* is specified, in which case, -that *count* is a maximum limit on the number of replacements to be done. - -If *in-place* is true then the string itself is modified, -otherwise a modified copy is made. - -::: tip Examples: -``` scheme -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>)) -"bonono" -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>) start: 3) -"banono" -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>) end: 5) -"bonona" -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>)start: 1 end: 5) -"bonona" -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>) count: 2) -"bonona" -> (string-substitute-char-if "banana" #\o (cut eqv? #\a <>) count: 2 from-end: #t) -"banono" -> (string-substitute-char-if "banana" #\o (cut char>? #\c <>)) -"oonono" -> (string-substitute-char-if "banana" #\o (lambda (x) (not (equal? x #\a)))) -"oaoaoa" -> (string-substitute-char-if "banana" #\o (lambda (x) (equal? (char-upcase x) #\A))) -"bonono" -``` -::: - -## string-substitute-char -``` scheme -(string-substitute-char-if string newchar oldchar - [test: #f] - [test-not: #f] - [key: #f] - [start: #f] - [end: #f] - [from-end: #f] - [count: #f] - [in-place: #f]) => string-with-substitutions -``` - -Substitutes/replaces in *string* the characters matching the *oldchar* -with the character *newchar*. - -A character *char* matches if `(test oldchar (key char))`, where: - - for *key*, `#f` designates the `identity` function - - if `test` is `#f` and `test-not` isn't, then the test is - `(lambda (x y) (not (test-not x y)))` - - if both `test` and `test-not` are `#f`, then the test is `equal?`. - -Only substitute characters in the substring -defined by the *start* index (included, defaults to `0`) and -the *end* index (excluded, defaults to the length of the string). - -The replacement starts *from-end* if specified as true, -which only matters if *count* is specified, in which case, -that *count* is a maximum limit on the number of replacements to be done. - -If *in-place* is true then the string itself is modified, -otherwise a modified copy is made. - -::: tip Examples: -``` scheme -> (string-substitute-char "banana" #\o #\a) -"bonono" -> (string-substitute-char "banana" #\o #\a start: 3) -"banono" -> (string-substitute-char "banana" #\o #\a end: 5) -"bonona" -> (string-substitute-char "banana" #\o #\a start: 1 end: 5) -"bonona" -> (string-substitute-char "banana" #\o #\a count: 2) -"bonona" -> (string-substitute-char "banana" #\o #\a count: 2 from-end: #t) -"banono" -> (string-substitute-char "banana" #\o #\c test: char>?) -"oonono" -> (string-substitute-char "banana" #\o #\a test-not: equal?) -"oaoaoa" -> (string-substitute-char "banana" #\o #\A key: char-upcase) -"bonono" -``` -::: - ## string-whitespace? ``` scheme (string-whitespace? str) -> boolean @@ -400,19 +297,3 @@ used by the `:std/format` family of procedures. Considers the `:pr` ``` Global line ending convenience definitions. - -## as-string bool -``` -`as-string (as-string (as-string (ignore-errors 1 2 3) -3 -> (ignore-errors 1 (error "foo") 3) -#f -``` -::: - ## defmethod/alias ```scheme (defmethod/alias {method (alias ...) type}