#lang scribble/manual @(require (planet cce/scheme:6:0/scribble) scribble/eval (for-label scheme (this-package-in common))) @(define make-my-eval (make-eval-factory '(scheme (planet orseau/lazy-doc:1:5/common)))) @title[#:tag "common"]{Common Scheme Utilities} @(defmodule/this-package common) This module provides some useful functions and forms that are common to most of the files of this package and other future packages. @defform[(++ var)]{ Increments @scheme[var]. } @defform[(-- var)]{ Decrements @scheme[var]. } @defproc[(box-me [ b box? ] [ val any/c ]) (one-of/c val)]{ Puts @scheme[val] in the box @scheme[b] and returns @scheme[val]. Useful to return a value and box it as a side effect. } @defproc[(identity [ x any/c ] [ r any/c ] ...) (one-of/c x)]{ Returns only the first of the parameters. } @defproc[(symetric [ fxy procedure? ]) procedure?]{ Returns the symetric function of @scheme[fxy]. } @defproc[(to-proc [ x any/c ]) procedure?]{ Returns a procedure that accepts any number of arguments and returns @scheme[x]. If @scheme[x] was already a procedure, returns @scheme[x] without change. } @defproc[(get-type [ x any/c ]) (listof procedure?)]{ Returns (some of) the types that @scheme[x] matches. } @(examples #:eval (make-my-eval) (get-type '(a b c)) (get-type 101) (get-type get-type) ) @section{Lists} @defproc[(transpose [ ll (listof list?) ]) (listof list?)]{ Transposes a list of lists. } @(examples #:eval (make-my-eval) (transpose '((a b c) (0 1 2))) ) @defproc[(list-choose [ l list? ]) any]{ Chooses one element from @scheme[l]. } @(examples #:eval (make-my-eval) (list-choose '(a b c d e f g h i j)) (list-choose '(a b c d e f g h i j)) (list-choose '(a b c d e f g h i j)) ) @defproc[(first-value [ l list? ] ...) any]{ Returns the first value of @scheme[l] that is not @scheme[#f], or returns @scheme[#f] if none is found. Useful with functions that return a value or @scheme[#f] (like @scheme[get-env]). A default value can be set as the last element. } @(examples #:eval (make-my-eval) (first-value #f #f "plop" #f 'moustard) (first-value #f #f #f) ) @defproc[(mean [ n number? ] ...) number?]{ Returns the average value of the @scheme[n]. } @defproc[(list-set [ l list? ] [ n number? ] [ v any/c ]) list?]{ Returns the same list @scheme[l] where element at position @scheme[n] is replaced by @scheme[v]. } @(examples #:eval (make-my-eval) (list-set '(a b c d e) 3 'huh?) ) @defproc[(list->lines [ l list? ] [ sep any/c ]) (listof? list?)]{ Splits a list into "lines" (list of lists). } @(examples #:eval (make-my-eval) (list->lines '(a b c x d e x x f g h x o) 'x) ) @section{Functions and Applications} @defproc[(argbest [ proc procedure? ] [ lst list? ]) any]{ Returns the best element of @scheme[lst]. Each challenger is compared to the best value with @scheme[proc]. If @scheme[proc] returns @scheme[#t], the best wins. } @(examples #:eval (make-my-eval) (argbest < '(5 2 5 7 8 1 5)) (argbest > '(5 2 5 7 8 1 5)) (argbest (λ(best chall) (and (<= (first best) (first chall)) (< (second best) (second chall)))) '((3 6)(7 2)(8 3)(3 5)(3 7))) ) @defproc[(map/apply [ proc procedure? ] [ ll (listof list?) ] ...) list?]{ Applies @scheme[proc] to each list element of @scheme[ll]. } @defproc[(for-each/apply [ proc procedure? ] [ ll (listof list?) ] ...) void?]{ Like @scheme[map/apply] but with @scheme[for-each]. } @defproc[(ntimes [ n number? ] [ proc procedure? ]) void?]{ Does @scheme[proc] @scheme[n] times. } @defform[(times n val-max body ...)]{ Binds @scheme[n] to the values from 0 to @scheme[val-max] while doing @scheme[body] ... } @section{Vectors} @defform[(with-vector lst-id body ...)]{ Temporarily turns @scheme[lst-id] into a vector, does @scheme[body] ... then turns it back to a list } @defproc[(vector-clone [ v any/c ]) any]{ } @section{Strings} @defproc[(to-string [ x any/c ]) string?]{ Turns any value into a string. } @defproc[(protect-string [ x any/c ]) string?]{ Turns any value into a string. If @scheme[x] is already a string, quotes its quotes. } @(examples #:eval (make-my-eval) (protect-string "the string \"plop\" is a string.") ) @defproc[(trim [ s string? ] [ left number? 0] [ right number? left]) string?]{ Removes left and right characters from @scheme[s]. } @(examples #:eval (make-my-eval) (trim "abcdefghij" 3 1) ) @defproc[(string-reverse [ str string? ]) string?]{ Reverses @scheme[str]. } @(examples #:eval (make-my-eval) (string-reverse "emordnilap a ton ma I") ) @defproc[(string->lines [ str string? ] [ sep string? "\n"]) (listof string?)]{ Splits @scheme[str] at @scheme[sep]. } @(examples #:eval (make-my-eval) (string->lines "One\nTwo Three\nFour") ) @defproc[(regexp-matcher [ re (or/c string? pregexp? regpexp?) ]) procedure?]{ Returns a procedure that matches @scheme[re]. } @(examples #:eval (make-my-eval) (map (regexp-matcher "pl(.)p") '("aplipa" "youp" "coplop")) ) @defproc[(comment-section [ text string? ] [#:pre pre string? ";;; "] [#:post post string? (string-reverse pre)]) void?]{ Displays a comment string that can be copied into the source file. The width of the result depends on the with of @scheme[text]. } @(examples #:eval (make-my-eval) (comment-section "And now for something completely different") ) @defproc[(comment-chapter [ text string? ] [ pre string? " "] [ post string? (string-reverse pre)] [#:width width number? 80]) void?]{ Similar to @scheme[comment-section] but the width of the result does not depend on the width of @scheme[text]. } @(examples #:eval (make-my-eval) (comment-chapter "The Show Sets Sales" #:width 60) ) @defproc[(proc->string [ proc procedure? ]) string?]{ } @(examples #:eval (make-my-eval) (proc->string proc->symbol) ) @defproc[(proc->symbol [ proc procedure? ]) symbol?]{ } @(examples #:eval (make-my-eval) (proc->symbol proc->symbol) ) @section{Files and Directories} @defproc[(directory-list-rec [ path path-string? (current-directory)]) (listof (or/c string? path?))]{ Returns the list of files and directory contained in @scheme[path], recursively including sub-directories. The files are returned with their full path. } @defproc[(filter-file-list [ re (or/c string? pregexp? regpexp?) ] [ files (listof (or/c string? path?)) (directory-list)]) (listof (or/c string? path?))]{ Filters the list of files @scheme[files] with the regexp @scheme[re]. } @(examples #:eval (make-my-eval) (filter-file-list "parser\\.ss$" (directory-list)) ) @defproc[(file->lines/latin-1 [ file path-string? ]) (listof string?)]{ } @defproc[(file->name-ext [ file path-string? ]) any]{ Returns two values: the name part of the file and the extension part, without the dot. } @(examples #:eval (make-my-eval) (file->name-ext "common.scm.ss") ) @defproc[(path->quote-string [ path path-string? ]) string?]{ Returns the path as a string, and surround it with double-quotes if it contains spaces. } @(examples #:eval (make-my-eval) (path->quote-string "C:\\Program Files\\PLT") (path->quote-string "~/scheme/cabbages") ) @section{Classes and Objects} @defform/subs[(map/send message obj ...) ([message method (method arg ...)]) ]{ Sends @scheme[method] along with its arguments to each object and returns the list of results. } For example @schemeblock[(map/send my-method (list obj1 obj2 obj3))] is equivalent to @schemeblock[(map (λ(x)(send x my-method)) (list obj1 obj2 obj3))] and @schemeblock[(map/send (my-method 3 5) (list obj1 obj2 obj3))] is equivalent to @schemeblock[(map (λ(x)(send x my-method 3 5)) (list obj1 obj2 obj3))] @defform[(for-each/send method obj ...)]{ Like @scheme[map/send] but returns @scheme[(void)]. }