Skip to main content

module IO

rascal-0.34.0

Library functions for input/output.

Usage

import IO;

Dependencies

import Exception;

Description

The following input/output functions are defined:

function registerLocations

Register a logical file scheme including the resolution method via a table.

void registerLocations(str scheme, str authority, map[loc logical, loc physical] m)

Logical source location schemes, such as |java+interface://JRE/java/util/List| are used for precise qualified names of artifacts while abstracting from their physical location in a specific part of a file on disk or from some webserver or source repository location.

Using this function you can create your own schemes. The authority field is used for scoping the names you wish to resolve to certain projects. This way one name can resolve to different locations in different projects.

Benefits

  • Logical source locations are supported by IDE features such as hyperlinks
  • Logical source locations are supported by all IO functions as well

Pitfalls

  • Repeated calls to registerLocations for the same scheme and authority will overwrite the m map.
  • The registry is an intentional memory leak; so make sure you use it wisely. See also Unregister Locations.
  • When the files references by the physical locations are being written to (edited, removed), then you may expect problems. The registry is not automatically invalidated.

function unregisterLocations

Undo the effect of ((registerLocations))

void unregisterLocations(str scheme, str authority)

For debugging or for memory management you may wish to remove a lookup table.

function resolveLocation

loc resolveLocation(loc l)

function findResources

Finds files in the deployment locations of the configuration of the current runtime

set[loc] findResources(str fileName)

set[loc] findResources(loc path)
  • For the interpreter this looks at the source path and finds any file in there.
  • For the compiler this looks at the classpath and finds resources in there.

The goal of findResources is to access additional files that are distributed with a Rascal program. For example, the index.html file that comes with a server implemented using Webserver would be located using this function. Such an additional file is essential to the functioning of the given Rascal code.

There is a difference between Rascal programs under development and Rascal programs deployed (in a jar file). The idea is that calls to this function behave the same regardless of this mode. To make this true, the implementation of findResources makes the following assumptions:

  • In interpreter mode, the additional files are stored relative to the source roots of the current project. This means that all source roots are searched as configured for the current interpreter. It is possible that multiple files match the query, hence the result set. Because jar files and target folders are typically added to the source roots by the configuration code for Rascal's IDEs, this works out smoothly also for deployed projects.
  • In compiled mode, the additional files are stored relative to the roots of the classpath. This means they are jar files and target folders of active projects. Your Maven project configuration should take care to copy all relevant resources from source folders to target folders and to package those relative to the root of the jar for this to work in development mode. For deployment mode, the setup works through the resources API of the JVM that uses the Java ClassLoader API.

Benefits

By satisfying the above two assumptions it is possible to write Rascal code that uses findResources that is portable between interpreter and compiled mode, and does not change between development and deployed mode either.

Pitfalls

  • Avoid nesting resources in sub-folders in jar files (see Maven resources plugin) since nested files will not be found.
  • Inside jar files the root for module names should be the same as for resources
  • Inside source folders, the names of resources should be relative to the same root as the Rascal module names
  • findResources searches exhaustively for all files with the given name; which may come at an expensive for projects with large search paths. It makes sense to keep this in a constant module variable that is initialized only once.
  • Name clashes are bound to happen. Prepare to, at least, throw a meaningful error message in the case of name clashes. E.g. findResources("index.html") is very likely to produce more than one result. Either choose more unique names, or filter the result in a meaningful manner, or throw an exception that explains the situation to the user of your code. Specifically library project maintainers have to consider this happenstance. The recommendation is to nest resources next to qualified module names, like so: if lang/x/myLanguage/Syntax.rsc is a module name, then lang/x/myLanguage/examples/myExampleFile.mL is an example resource location.

function appendToFile

Append a value to a file.

void appendToFile(loc file, value V..., str charset=DEFAULT_CHARSET, bool inferCharset=!(charset?))
throws PathNotFound, IO

Append a textual representation of some values to an existing or a newly created file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

The existing file can be stored using any character set possible, if you know the character set, please use Append To File Enc. Else the same method of deciding the character set is used as in Read File.

Pitfalls

  • The same encoding pitfalls as the Read File function.

function appendToFileEnc

Append a value to a file.

void appendToFileEnc(loc file, str charset, value V...) throws PathNotFound, IO

Append a textual representation of some values to an existing or a newly created file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded using the charset provided.

function charsets

Returns all available character sets.

set[str] charsets()

function canEncode

Returns whether this charset can be used for encoding (use with ((writeFile)))

set[str] canEncode(str charset)

function bprintln

Print a value and return true.

bool bprintln(value arg)

Print a value and return true. This is useful for debugging complex Boolean expressions or comprehensions. The only difference between this function and Println is that its return type is bool rather than void.

Examples

rascal>import IO;
ok
rascal>bprintln("Hello World");
Hello World
bool: true

function exists

Check whether a given location exists.

bool exists(loc file)

Check whether a certain location exists, i.e., whether an actual file is associated with it.

Examples

rascal>import IO;
ok

Does the library file IO.rsc exist?

rascal>exists(|std:///IO.rsc|);
bool: true

function find

Find a named file in a list of locations.

loc find(str name, list[loc] path) throws PathNotFound

Examples

rascal>import IO;
ok

Find the file IO.rsc in the standard library:

rascal>find("IO.rsc", [|std:///|]);
loc: |std:///IO.rsc|

function isDirectory

Check whether a given location is a directory.

bool isDirectory(loc file)

Check whether the location file is a directory.

function iprint

Print an indented representation of a value.

void iprint(value arg, int lineLimit = 1000)

See IprintExp for a version that returns its argument as result and Iprintln for a version that adds a newline and IprintToFile for a version that prints to a file.

Examples

rascal>import IO;
ok
rascal>iprint(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
"fruits",
("snake":0,"spider":8),
[10,20,30]
]
ok

function iprintToFile

Print an indented representation of a value to the specified location.

void iprintToFile(loc file, value arg, str charset=DEFAULT_CHARSET)

See Iprint for a version that displays the result on the console and IprintExp for a version that returns its argument as result and Iprintln for a version that adds a newline.

Examples

rascal>import IO;
ok
rascal>iprintToFile(|file:///tmp/fruits.txt|, ["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
ok

function iprintToString

str iprintToString(value arg)

function iprintExp

Print an indented representation of a value and returns the value as result.

&T iprintExp(&T v)

See IprintlnExp for a version that adds a newline.

Examples

rascal>import IO;
ok
rascal>iprintExp(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
"fruits",
("snake":0,"spider":8),
[10,20,30]
]
list[value]: [
"fruits",
("snake":0,"spider":8),
[10,20,30]
]

function iprintlnExp

Print an indented representation of a value followed by a newline and returns the value as result.

&T iprintlnExp(&T v)

See IprintExp for a version that does not add a newline.

Examples

rascal>import IO;
ok
rascal>iprintlnExp(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
"fruits",
("snake":0,"spider":8),
[10,20,30]
]
list[value]: [
"fruits",
("snake":0,"spider":8),
[10,20,30]
]

function iprintln

Print a indented representation of a value and add a newline at the end.

void iprintln(value arg, int lineLimit = 1000)

See IprintlnExp for a version that returns its argument as result and Iprint for a version that does not add a newline.

By default we only print the first 1000 lines, if you want to print larger values, either use WriteTextValueFile or change the limit with the lineLimit parameter.

Examples

rascal>import IO;
ok
rascal>iprintln(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
"fruits",
("snake":0,"spider":8),
[10,20,30]
]
ok
rascal>iprintln([ {"hi"} | i <- [0..1000]], lineLimit = 10);
[
{"hi"},
{"hi"},
{"hi"},
{"hi"},
{"hi"},
{"hi"},
{"hi"},
{"hi"},
{"hi"},
...
ok

function isFile

Check whether a given location is actually a file (and not a directory).

bool isFile(loc file)

Check whether location file is actually a file.

function lastModified

Last modification date of a location.

datetime lastModified(loc file)

Returns last modification time of the file at location file.

Examples

rascal>import IO;
ok

Determine the last modification date of the Rascal standard library:

rascal>lastModified(|std:///IO.rsc|);
datetime: $2023-10-17T14:42:20.000+00:00$

function created

Creation datetime of a location.

datetime created(loc file)

Returns the creation time of the file at location file.

Examples

rascal>import IO;
ok

Determine the last modification date of the Rascal standard library:

rascal>created(|std:///IO.rsc|);
datetime: $2023-10-17T14:42:20.000+00:00$

function touch

Set the modification date of a file to now or create the file if it did not exist yet

void touch(loc file)

function setLastModified

Set the modification date of a file to the timestamp

void setLastModified(loc file, datetime timestamp)

function listEntries

List the entries in a directory.

list[str] listEntries(loc file)

List the entries in directory file.

Examples

rascal>import IO;
ok

List all entries in the standard library:

rascal>listEntries(|std:///|);
list[str]: ["Boolean.rsc","Content.rsc","DateTime.rsc","Exception.rsc","Grammar.rsc","IO.rsc","List.rsc","ListRelation.rsc","Location.rsc","Map.rsc","Message.rsc","Node.rsc","ParseTree.rsc","Prelude$1.class","Prelude$2.class","Prelude$3.class","Prelude$4.class","Prelude$Backtrack.class","Prelude$ByteBufferBackedInputStream.class","Prelude$Distance.class","Prelude$Less.class","Prelude$NodeComparator.class","Prelude$ReleasableCallback.class","Prelude$Sorting.class","Prelude.class","Prelude.rsc","Relation.rsc","Set.rsc","String.rsc","Type.class","Type.rsc","ValueIO.rsc","analysis","index.md","lang","resource","util","vis"]

function mkDirectory

Create a new directory.

void mkDirectory(loc file)
throws PathNotFound, IO

Create a directory at location file.

function print

Print a value without subsequent newline.

void print(value arg)

Print a value on the output stream. See Println for a version that adds a newline and PrintExp for a version that returns its argument as value.

Examples

Note that the only difference with Println is that no newline is added after the value is printed

rascal>import IO;
ok
rascal>print("Hello World");
Hello World
ok

NOTE: Since print does not add a newline, the prompt ok appears at a weird place, i.e., glued to the output of print.

function printExp

Print a value and return it as result.

&T printExp(&T v)

&T printExp(str msg, &T v)

Examples

rascal>import IO;
ok
rascal>printExp(3.14);
3.14
real: 3.14
rascal>printExp("The value of PI is approximately ", 3.14);
The value of PI is approximately 3.14
real: 3.14

function println

Print a value to the output stream and add a newline.

void println(value arg)

void println()

Print a value on the output stream followed by a newline. See Print for a version that does not add a newline and PrintlnExp for a version that returns its argument as value.

Examples

rascal>import IO;
ok
rascal>println("Hello World");
Hello World
ok

Introduce variable S and print it:

rascal>S = "Hello World";
str: "Hello World"
---
Hello World
---
rascal>println(S);
Hello World
ok

Introduce variable L and print it:

rascal>L = ["a", "b", "c"];
list[str]: ["a","b","c"]
rascal>println(L);
["a","b","c"]
ok

Use a string template to print several values:

rascal>println("<S>: <L>");
Hello World: ["a","b","c"]
ok

Just print a newline

rascal>println();
ok

function printlnExp

Print a value followed by a newline and return it as result.

&T printlnExp(&T v)

&T printlnExp(str msg, &T v)

Examples

rascal>import IO;
ok
rascal>printlnExp(3.14);
3.14
real: 3.14
rascal>printlnExp("The value of PI is approximately ", 3.14);
The value of PI is approximately 3.14
real: 3.14

NOTE: Since printExp does no produce a newline after its output, the result prompt real: 3.14 is glued to the output of printExp.

function rprint

Raw print of a value.

void rprint(value arg)

Pitfalls

This function is only available for internal use in the Rascal development team.

function rprintln

Raw print of a value followed by newline.

void rprintln(value arg)

Pitfalls

This function is only available for internal use in the Rascal development team.

function readFile

Read the contents of a location and return it as string value.

str readFile(loc file, str charset=DEFAULT_CHARSET, bool inferCharset=!(charset?))
throws PathNotFound, IO

Return the contents of a file location as a single string. Also see Read File Lines.

Pitfalls

  • In case encoding is not known, we try to estimate as best as we can.
  • We default to UTF-8, if the file was not encoded in UTF-8 but the first characters were valid UTF-8, you might get an decoding error or just strange looking characters.

function readFileEnc

Read the contents of a location and return it as string value.

str readFileEnc(loc file, str charset) throws PathNotFound, IO

Return the contents (decoded using the Character set supplied) of a file location as a single string. Also see Read File Lines Enc.

function readBase64

str readBase64(loc file)
throws PathNotFound, IO

function uuencode

str uuencode(loc file)

function writeBase64

void writeBase64(loc file, str content)
throws PathNotFound, IO

function uudecode

void uudecode(loc file, str content)

function readFileBytes

Read the contents of a file and return it as a list of bytes.

list[int] readFileBytes(loc file)
throws PathNotFound, IO

function readFileLines

Read the contents of a file location and return it as a list of strings.

list[str] readFileLines(loc file, str charset=DEFAULT_CHARSET)
throws PathNotFound, IO

Return the contents of a file location as a list of lines. Also see Read File.

Pitfalls

  • In case encoding is not known, we try to estimate as best as we can (see [readFile]).
  • We default to UTF-8, if the file was not encoded in UTF-8 but the first characters were valid UTF-8, you might get an decoding error or just strange looking characters (see Read File).

function writeFileLines

Writes a list of strings to a file, where each separate string is ended with a newline

void writeFileLines(loc file, list[str] lines, str charset=DEFAULT_CHARSET)

Benefits

Pitfalls

  • if the individual elements of the list also contain newlines, the output may have more lines than list elements

function readFileLinesEnc

Read the contents of a file location and return it as a list of strings.

list[str] readFileLinesEnc(loc file, str charset)
throws PathNotFound, IO

Return the contents (decoded using the Character set supplied) of a file location as a list of lines. Also see Read File Lines.

function remove

void remove(loc file, bool recursive=true) throws IO

function writeFile

Write values to a file.

void writeFile(loc file, value V..., str charset=DEFAULT_CHARSET)
throws PathNotFound, IO

Write a textual representation of some values to a file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded in UTF-8, in case this is not desired, use Write File Enc.

function writeFileBytes

Write a list of bytes to a file.

void writeFileBytes(loc file, list[int] bytes)
throws PathNotFound, IO

function writeFileEnc

Write values to a file.

void writeFileEnc(loc file, str charset, value V...) throws PathNotFound, IO

Write a textual representation of some values to a file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded using the charset provided.

function md5HashFile

Read the contents of a location and return its MD5 hash.

str md5HashFile(loc file)
throws PathNotFound, IO

MD5 hash the contents of a file location.

function md5Hash

str md5Hash(value v)
str createLink(str title, str target)

function toBase64

str toBase64(loc file)
throws PathNotFound, IO

function copy

void copy(loc source, loc target, bool recursive=false, bool overwrite=true) throws IO

function copyFile

void copyFile(loc source, loc target)

function copyDirectory

void copyDirectory(loc source, loc target)

function move

void move(loc source, loc target, bool overwrite=true) throws IO

function arbLoc

loc arbLoc()

data LocationChangeEvent

data LocationChangeEvent  
= changeEvent(loc src, LocationChangeType changeType, LocationType \type)
;

data LocationChangeType

data LocationChangeType  
= created()
| deleted()
| modified()
;

data LocationType

data LocationType  
= file()
| directory()
;

function watch

void watch(loc src, bool recursive, void (LocationChangeEvent event) watcher)

function unwatch

void unwatch(loc src, bool recursive, void (LocationChangeEvent event) watcher)