Package org.forgerock.maven.plugins.xcite

Class Citation

java.lang.Object
org.forgerock.maven.plugins.xcite.Citation
public class Citation extends Object
A citation references part of a text file to quote.

The string representation includes the path to the file to cite, and optionally start and end markers to frame the text to quote.

For example, [/path/to/script.sh:# start:# end]

Notice that the example has a UNIX-style path, /path/to/script.sh, a start marker, # start, and an end marker, # end. The file, script.sh, could have text to quote between the markers. For example, script.sh might have the following content: 

 #!/bin/bash

 # start
 wall <<EOM
     Hello world
 EOM
 # end

 exit
In this case the quote would be the following: 
 wall <<EOM
     Hello world
 EOM
Start and end markers depend on the language of the source text. Markers should make sense to people who mark up the source text, and so they should be composed of visible characters. Markers must not include the delimiter character that is used to separate the path and the markers.

Markers either both be on the same line as the text to quote, or should be on separate lines from the text to quote. In other words, you can prepare a text to quote a single line either by adding a start marker on the line before and an end marker on the line after, or by prepending a start marker to the line before the text to quote and appending an end marker after.

The following example shows markers on separate lines. 

 #start
 This is the text to quote.
 #end

The following example shows markers on the same line as the text to quote. 

 #start This is the text to quote. #end
More formally, the citation string representation is as follows. 

 citation     = "[" path delimiter start-marker delimiter end-marker "]"
 citation     / "[" path delimiter start-marker "]"
 citation     / "[" path "]"

 path         = File.getPath()                ; Depends on the OS,
                                              ; does not include delimiter

 delimiter    = ":" / "%"                     ; Default: ":"

 start-marker = 1*(VCHAR excluding delimiter) ; Depends on source language

 end-marker   = 1*(VCHAR excluding delimiter) ; Depends on source language
Most systems allow file names that can cause problems with this scheme. Working around the problem is an exercise for the reader.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Citation(String path)
    Construct a citation from a path alone.
    Citation(String path, char delimiter, String start)
    Construct a citation from a path, delimiter, and start marker, when the start marker and the end marker are the same.
    Citation(String path, char delimiter, String start, String end)
    Construct a citation from a path, delimiter, start marker, and end marker.

  • Method Summary

    Modifier and Type
    Method
    Description
    char
    getDelimiter()
    Returns the value of the delimiter.
    String
    getEnd()
    Returns the value of the start marker, which can be empty.
    String
    getPath()
    Returns the value of the path.
    String
    getStart()
    Returns the value of the start marker, which can be empty.
    void
    setDelimiter(char delimiter)
    Sets the value of the delimiter.
    void
    setEnd(String end)
    Sets the value of the end marker, which must not contain the delimiter.
    void
    setPath(String path)
    Sets the pathname string for the file to quote.
    void
    setStart(String start)
    Sets the value of the start marker, which must not contain the delimiter.
    String
    toString()
    Returns the string representation of this citation.
    static Citation
    valueOf(String citation)
    Returns a Citation from the string representation, assuming the default delimiter, :.
    static Citation
    valueOf(String citation, String delimiter)
    Returns a Citation from the string representation.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Citation

      public Citation(String path)
      Construct a citation from a path alone.

      The path cannot be null.

      Parameters:
      path - The pathname string for the file to quote. Not null.
      Throws:
      IllegalArgumentException - Path is broken somehow.

    • Citation

      public Citation(String path, char delimiter, String start)
      Construct a citation from a path, delimiter, and start marker, when the start marker and the end marker are the same.

      The path cannot be null.

      The start marker cannot contain the delimiter.

      Parameters:
      path - The pathname string for the file to quote. Not null.
      delimiter - The delimiter for path, markers.
      start - The start marker. If null or "", only path is useful.
      Throws:
      IllegalArgumentException - Path or marker is broken somehow.

    • Citation

      public Citation(String path, char delimiter, String start, String end)
      Construct a citation from a path, delimiter, start marker, and end marker.

      The path cannot be null.

      The markers cannot contain the delimiter.

      Parameters:
      path - The pathname string for the file to quote. Not null.
      delimiter - The delimiter for path, markers.
      start - The start marker. If null or "", only path is useful.
      end - The end marker. If null or "", start is both.
      Throws:
      IllegalArgumentException - Path or marker is broken somehow.

  • Method Details

    • getPath

      public String getPath()
      Returns the value of the path.
      Returns:
      The value of the path.

    • setPath

      public void setPath(String path)
      Sets the pathname string for the file to quote.
      Parameters:
      path - The pathname string for the file to quote.
      Throws:
      IllegalArgumentException - Path cannot be null.

    • getDelimiter

      public char getDelimiter()
      Returns the value of the delimiter.
      Returns:
      The value of the delimiter.

    • setDelimiter

      public void setDelimiter(char delimiter)
      Sets the value of the delimiter.
      Parameters:
      delimiter - The delimiter for path, markers.

    • getStart

      public String getStart()
      Returns the value of the start marker, which can be empty.
      Returns:
      The value of the start marker, which can be empty.

    • setStart

      public void setStart(String start)
      Sets the value of the start marker, which must not contain the delimiter.
      Parameters:
      start - The value of the start marker.
      Throws:
      IllegalArgumentException - Start marker contains the delimiter.

    • getEnd

      public String getEnd()
      Returns the value of the start marker, which can be empty.
      Returns:
      The value of the start marker, which can be empty.

    • setEnd

      public void setEnd(String end)
      Sets the value of the end marker, which must not contain the delimiter.
      Parameters:
      end - The value of the end marker.
      Throws:
      IllegalArgumentException - End marker contains the delimiter.

    • toString

      public String toString()
      Returns the string representation of this citation.
      Overrides:
      toString in class Object
      Returns:
      The string representation of this citation.

    • valueOf

      public static Citation valueOf(String citation, String delimiter)
      Returns a Citation from the string representation.
      Parameters:
      citation - The string representation.
      delimiter - One of ":" or "%".
      Returns:
      A Citation corresponding to the string representation, or null if the string representation does not parse.

    • valueOf

      public static Citation valueOf(String citation)
      Returns a Citation from the string representation, assuming the default delimiter, :.
      Parameters:
      citation - The string representation.
      Returns:
      A Citation corresponding to the string representation, or null if the string representation does not parse.