On this page:
1.1 polyglot/  projects
polyglot-project%
new
asset-path?
get-workflow-class
ensure-empty-distribution!
get-directory-name
copy-polyglot-skeleton-project!
useable-polyglot-directory?
find-closest-project
1.2 polyglot/  paths
polyglot-project-directory
polyglot-assets-directory
polyglot-dist-directory
polyglot-temp-directory
path-el/  c
project-rel
assets-rel
dist-rel
polyglot-rel
system-temp-rel
make-dist-path-string
make-temp-ephmod-directory
7.6

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.

class

polyglot-project% : class?

  superclass: object%

  extends: equal<%>

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?

Deletes (dist-rel) if it already exists, then creates an empty directory in its place.

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
Copies a polyglot project template by name to destination, and returns a project object pointing to destination. If force? is a true value, destination is deleted in advance.

The polyglot start command uses this procedure.

procedure

(useable-polyglot-directory? directory)  boolean?

  directory : path?
Assuming polyglot-project-directory was set to directory, returns #t if all of the following are true:

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?
Returns a project object for the first directory in (start, start/.., ... , <root>) where useable? is #t. Returns #f otherwise.

1.2 polyglot/paths

 (require polyglot/paths) package: polyglot-lib

This sets the base directory in which Polyglot will read asset files and write distribution files. If you encounter incorrect file I/O activity, make sure this value is what you expect it to be.

You normally set this using polyglot command lines.

This is a derived parameter that controls the base directory of assets-rel.

When #f (default), (polyglot-assets-directory) will evaluate to (build-path (polyglot-project-directory) "assets").

This is a derived parameter that controls the base directory of dist-rel.

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.

Polyglot uses this directory to read and write files contained within your content. To increase performance, set this to a directory using an in-memory filesystem like tempfs (Assuming that (find-system-path 'temp-rel) is not already on an in-memory filesystem).

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
These procedures behave like build-path, except each returns a path relative to a different directory:

procedure

(make-dist-path-string base [relative-to])  path-string?

  base : complete-path?
  relative-to : complete-path? = (dist-rel)
Given two complete paths, returns a relative path string that can be used in HTML, CSS, etc. to request an asset relative to the code’s enclosing file.

Behaves like find-relative-path, except if the simple forms of base and relative-to are equal, this will return "/" (meaning "webroot").

Creates a temporary directory in (polyglot-temp-directory). The new directory will contain a symbolic link called project pointing to (polyglot-project-directory).