1 Projects
Polyglot prescribes a filesystem structure so that applications can easily build paths and define projects under the same assumptions.
1.1 polyglot/projects
| (require polyglot/projects) | package: polyglot-lib |
polyglot/projects defines Polyglot project structure and common project-level operations.
A project is defined as a directory in a file system that contains, at minimum, an assets directory named assets. The directory containing the assets directory is called the project directory. When a project is constructed, a new distribution directory named dist will appear in the project directory.
A project directory may contain a .polyglotrc.rkt runtime configuration file. If it exists, it must (provide polyglot+%), where polyglot+% is a workflow class like polyglot/functional%, polyglot/imperative%, or a subclass of polyglot/base% or unlike-assets% for lower-level workflows. If .polyglotrc.rkt does not exist or fails to provide a workflow class, this module does not define how to respond.
constructor
(new polyglot-project% [directory directory])
→ (is-a?/c polyglot-project%) directory : useable-polyglot-directory? An instance of this class encapsulates file I/O and validation for a Polyglot project located at directory.Two instances are equal? if their directory fields are equal?.
When relevant, methods use parameterize to set polyglot-project-directory to directory.
method
(send a-polyglot-project asset-path? complete-path) → boolean?
complete-path : complete-path? Returns #t if complete-path is a valid asset path for the project. This method does not consult the filesystem.
method
(send a-polyglot-project get-workflow-class [ fail-thunk #:live? live?]) → (or/c class? #f) fail-thunk : (-> any) = (lambda () ...) live? : any/c = #f If .polyglotrc.rkt does not exist in the project, this returns the result of fail-thunk. By default, fail-thunk raises exn:fail.If .polyglotrc.rkt exists in the project, this is equivalent to:
(dynamic-require (build-path directory ".polyglotrc.rkt") 'polyglot+% fail-thunk)
If live? is a true value, then this method will lead with a dynamic-rerequire.
method
(send a-polyglot-project ensure-empty-distribution!) → void?
method
(send a-polyglot-project get-directory-name) → string?
Returns the name of the project directory. Equivalent to:
(let-values ([(base name must-be-dir?) (split-path (get-field directory project))]) name)
procedure
(copy-polyglot-skeleton-project! name [ destination #:force? force?]) → (is-a?/c polyglot-project%) name : (or/c "functional" "imperative")
destination : (or/c path-string? path?) = (make-temporary-file "polyglot~a" 'directory) force? : any/c = #f
The polyglot start command uses this procedure.
procedure
(useable-polyglot-directory? directory) → boolean?
directory : path?
directory exists and is both readable and writeable.
The asset directory exists and is readable.
The .polyglotrc.rkt does not exist, OR it does exist and is readable.
This method does not attempt to load or instantiate .polyglotrc.rkt if it exists.
procedure
(find-closest-project start)
→ (or/c (is-a?/c polyglot-project%) boolean?) start : directory-exists?
1.2 polyglot/paths
| (require polyglot/paths) | package: polyglot-lib |
value
: (parameter/c (and/c complete-path? directory-exists?)) = (current-directory)
You normally set this using polyglot command lines.
value
: (parameter/c (and/c complete-path? directory-exists?)) = #f
When #f (default), (polyglot-assets-directory) will evaluate to (build-path (polyglot-project-directory) "assets").
value
When #f (default), (polyglot-dist-directory) will evaluate to (build-path (polyglot-project-directory) "dist").
Unlike (polyglot-assets-directory), a directory referenced by (polyglot-dist-directory) is not expected to exist.
value
: (parameter/c (and/c complete-path? directory-exists?)) = (find-system-path 'temp-rel)
value
path-el/c :
(and/c (or/c path-for-some-system? path-string?) (not/c complete-path?))
procedure
(project-rel path-element ...) → complete-path?
path-element : path-el/c
procedure
(assets-rel path-element ...) → complete-path?
path-element : path-el/c
procedure
(dist-rel path-element ...) → complete-path?
path-element : path-el/c
procedure
(polyglot-rel path-element ...) → complete-path?
path-element : path-el/c
procedure
(system-temp-rel path-element ...) → complete-path?
path-element : path-el/c
project-rel is relative to (polyglot-project-directory).
assets-rel is relative to (polyglot-assets-directory). This is where Polyglot will look for files you use to develop your website.
dist-rel is relative to (polyglot-dist-directory). This is where Polyglot will write output files that can be published for end-users to consume.
system-temp-rel is relative to (polyglot-temp-directory).
polyglot-rel is relative to the Polyglot package’s installation directory on your system. This should not be used for production, but you can use this to access private modules and experiment with self-hosting builds.
procedure
(make-dist-path-string base [relative-to]) → path-string?
base : complete-path? relative-to : complete-path? = (dist-rel)
Behaves like find-relative-path, except if the simple forms of base and relative-to are equal, this will return "/" (meaning "webroot").
procedure