gate.yam
Class YamFile

java.lang.Object
  gate.yam.YamFile

All Implemented Interfaces:

Serializable

public class YamFile
extends Object
implements Serializable

Main interface to the YAM language and its translation. Target languages:

• (X)HTML
• LaTeX
• PDF, which first translates to LaTeX then attempts to execute pdflatex
• "TREE", which is a print representation of YAM parse trees used for testing
• "PRETTY", which is a pretty print of YAM (whitespace changes only)

Author:

Hamish Cunningham

See Also:

Serialized Form

Nested Class Summary

static class

YamFile.FileType The various file types involved with YAM and their filename suffixes.

Method Summary

YamParseTree	generate() Translate to target languages.
void	generateType(YamFile.FileType type) Trigger generation of the various output types.
static YamFile	get(File location) Static factory method for getting a YAM file.
static YamFile	get(org.springframework.core.io.FileSystemResource location) Static factory method for getting a YAM file.
String	getCanonicalPath() Giveas the canonical path of this YamFile
File	getHtmlFile() Get the File for HTML output.
String	getHtmlPath() Get the path for an HTML output file.
List<String>	getIncludes() Get the list of includes from this YAM file to other local files, as a list of canonical paths of those files.
List<String>	getLinks() Get the list of links from this YAM file to other local files, as a list of canonical paths of those files.
org.springframework.core.io.FileSystemResource	getLocation() Get the location of this file.
File	getOutputFile(YamFile.FileType type) Create a file of a particular output type.
List<String>	getOutputLocations() Get a List of those output file locations that are generated by this YamFile.
YamParseTree	getParseTree() Get the parse tree (and related state) created by generate().
static String	getPluginPackageName() Get the package name for YAM plugins.
String	getVersion() Get the language version number.
static YamFile	needsGeneration(org.springframework.core.io.FileSystemResource location) This method checks whether a dependent file (one that is generated from YAM) needs regeneration, and if so it returns a YamFile instance corresponding to the generated file.
static String	printErrors(YamParseTree parseTree) Print errors and warnings from parsing.
void	replaceInContext(String name) Reset the location of this YamFile in the directory pointed to by the context path.
void	setBibAnchorPrefix(String bibAnchorPrefix) Set the prefix added to citation keys, when forming a reference to a bibiography file entry
void	setBibPageUrl(org.springframework.core.io.UrlResource bibPageUrl) Set the URL within which citation keys will be resolved.
void	setContextPath(String contextPath) Set the path in which to check for existence of relative links.
void	setCreatePageUrl(String createPageUrl) Set the URL which non-existent links will be pointed at (which presumably is the "create new page" URL for the parent wiki).
void	setCreatePageUrl(org.springframework.core.io.UrlResource createPageUrl) Set the URL which non-existent links will be pointed at (which presumably is the "create new page" URL for the parent wiki).
void	setDoIncludes(boolean b) Should we process included files or not?
String	toString() Return a String representing this YamFile: the String representation of the underlying File.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getLocation

public org.springframework.core.io.FileSystemResource getLocation()

Get the location of this file.

getCanonicalPath

public String getCanonicalPath()
                        throws gate.util.GateException

Giveas the canonical path of this YamFile

Returns:

The canonical path of this YamFIle

Throws:

gate.util.GateException - If the canonical path of this YamFile causes an IOException

get

public static YamFile get(File location)

Static factory method for getting a YAM file. Implemented via get(FileSystemResource).

get

public static YamFile get(org.springframework.core.io.FileSystemResource location)

Static factory method for getting a YAM file. This method will create a YamFile for a particular location, or will return the YamFile dependency for a generated file (e.g. HTML). A null return value indicates that a dependent file was passed which is not generated from YAM.

Parameters:

location - a path that points to a YAM file or a file depending on a YAM file.

Returns:

either a YamFile instance or null.

setContextPath

public void setContextPath(String contextPath)

Set the path in which to check for existence of relative links.

Parameters:

contextPath - the path to search in.

replaceInContext

public void replaceInContext(String name)

Reset the location of this YamFile in the directory pointed to by the context path. I.e. the new location of the file will be contextPath + new file name. This method is useful for when a generate has been done out of place (e.g. in the CoW staging directory) but now dependency analysis needs to be done on the file as if it was in place (e.g. when saving an edit and checking in).

Parameters:

name - the file name of the

setCreatePageUrl

public void setCreatePageUrl(String createPageUrl)

Set the URL which non-existent links will be pointed at (which presumably is the "create new page" URL for the parent wiki).

Parameters:

createPageUrl - the link to point to.

setCreatePageUrl

public void setCreatePageUrl(org.springframework.core.io.UrlResource createPageUrl)

Set the URL which non-existent links will be pointed at (which presumably is the "create new page" URL for the parent wiki).

Parameters:

createPageUrl - the link to point to.

setBibPageUrl

public void setBibPageUrl(org.springframework.core.io.UrlResource bibPageUrl)

Set the URL within which citation keys will be resolved. The URL will be for a bibliogrpahy. Citation keys reference a part of this URL, an individual bibliographic entry. Citation keys will form the final fragment of this URL, and will be prefixed, as defined by the setBibAnchorPrefix method

Parameters:

bibPageUrl - the URL of the bibliogrpahy.

setBibAnchorPrefix

public void setBibAnchorPrefix(String bibAnchorPrefix)

Set the prefix added to citation keys, when forming a reference to a bibiography file entry

Parameters:

bibAnchorPrefix - The prefix added to citation keys.

See Also:

setBibPageUrl(UrlResource)

getOutputFile

public File getOutputFile(YamFile.FileType type)

Create a file of a particular output type.

getHtmlFile

public File getHtmlFile()

Get the File for HTML output.

getHtmlPath

public String getHtmlPath()

Get the path for an HTML output file.

generateType

public void generateType(YamFile.FileType type)

Trigger generation of the various output types.

getOutputLocations

public List<String> getOutputLocations()
                                throws gate.util.GateException

Get a List of those output file locations that are generated by this YamFile.

Returns:

a List of locations as Strings.

Throws:

gate.util.GateException - if there is an exception on the YamFile location.

needsGeneration

public static YamFile needsGeneration(org.springframework.core.io.FileSystemResource location)
                               throws gate.util.GateRuntimeException

This method checks whether a dependent file (one that is generated from YAM) needs regeneration, and if so it returns a YamFile instance corresponding to the generated file. If the file doesn't need regeneration or has not been generated from a YAM file the method returns null. A dependent file needs regeneration when

• The YAM source file has an earlier modification time than the dependent file.

Parameters:

location - a file that may be generated from a YAM source file

Returns:

either the YAM file that needs generation or null

Throws:

gate.util.GateRuntimeException - if we get an IO exception on the location file

getParseTree

public YamParseTree getParseTree()

Get the parse tree (and related state) created by generate(). If generate hasn't been run this will be null.

setDoIncludes

public void setDoIncludes(boolean b)

Should we process included files or not?

generate

public YamParseTree generate()
                      throws gate.util.GateException

Translate to target languages.

Returns:

the parse tree, or null if generation of any of our output types is currently underway in a different YamFile.

Throws:

gate.util.GateException - if parsing or translation fails.

getLinks

public List<String> getLinks()

Get the list of links from this YAM file to other local files, as a list of canonical paths of those files. For files dependent on a YAM file, then the path of the YAM file will be returned. For files not dpendent on YAM files, the path of the file will be returned. Any links that cannot be resolved from their local path are ignored.

Returns:

A list of the canonical paths of links in this YAM file. Null if the parse tree has not been generated via a call to generate(). Null if the parent directory of this YamFile cannot be resolved. Empty if there are no links.

getIncludes

public List<String> getIncludes()

Get the list of includes from this YAM file to other local files, as a list of canonical paths of those files. For files dependent on a YAM file, then the path of the YAM file will be returned. For files not dpendent on YAM files, the path of the file will be returned. Any includes that cannot be resolved from their local path are ignored.

Returns:

A list of the canonical paths of includes in this YAM file. Null if the parse tree has not been generated via a call to generate(). Null if the parent directory of this YamFile cannot be resolved. Empty if there are no includes.

getVersion

public String getVersion()

Get the language version number. Version 1 was derived from Terrence Parr's TML language (thanks Ter! See the ANTLR site). Version 2 was the first version of YAM proper. Version 3 added various new facilities and was the basis for the first version of CLIE. Version 4 was a complete rewrite, for GATE version 4 and for use in CoW. Version 5 is intended to be stable and backwards-compatible with future versions.

getPluginPackageName

public static final String getPluginPackageName()

Get the package name for YAM plugins.

toString

public String toString()

Return a String representing this YamFile: the String representation of the underlying File.

Overrides:

toString in class Object

Returns:

A String representing this YamFile

printErrors

public static String printErrors(YamParseTree parseTree)

Print errors and warnings from parsing.