| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Text.AsciiDiagram
Contents
Description
This module gives access to the ascii diagram parser and SVG renderer.
Ascii diagram, transform your ASCII art drawing to a nicer representation
/---------+
+---------+ | |
| ASCII +---->| Diagram |
+---------+ | |
|{flat} | +--+------/
\---*-----/<=======/
::: .flat .filled_shape { fill: #DDD; }
To render the diagram as a PNG file, you have to use the library rasterific-svg and JuicyPixels.
As a sample usage, to save a diagram to png, you can use the following snippet.
import Codec.Picture( writePng ) import Text.AsciiDiagram( imageOfDiagram ) import Graphics.Rasterific.Svg( loadCreateFontCache ) saveDiagramToFile :: FilePath -> Diagram -> IO () saveDiagramToFile path diag = do cache <- loadCreateFontCache "asciidiagram-fonty-fontcache" imageOfDiagram cache 96 diag writePng path img
Synopsis
- svgOfDiagram :: Diagram -> Document
- parseAsciiDiagram :: Text -> Diagram
- saveAsciiDiagramAsSvg :: FilePath -> Diagram -> IO ()
- imageOfDiagram :: FontCache -> Diagram -> IO (Image PixelRGBA8)
- pdfOfDiagram :: FontCache -> Diagram -> IO ByteString
- svgOfDiagramAtSize :: GridSize -> Document -> Diagram -> Document
- data GridSize = GridSize {}
- defaultGridSize :: GridSize
- saveAsciiDiagramAsSvgAtSize :: FilePath -> GridSize -> Diagram -> IO ()
- imageOfDiagramAtSize :: FontCache -> GridSize -> Diagram -> IO (Image PixelRGBA8)
- pdfOfDiagramAtSize :: FontCache -> GridSize -> Diagram -> IO ByteString
- defaultLibrary :: GridSize -> Document
- data Diagram = Diagram {
- _diagramElements :: Set Element
- _diagramCellWidth :: !Int
- _diagramCellHeight :: !Int
- _diagramStyles :: [Text]
- data TextZone = TextZone {}
- data Shape = Shape {
- shapeElements :: ![ShapeElement]
- shapeIsClosed :: !Bool
- shapeTags :: !(Set Text)
- shapeChildren :: ![Element]
- data ShapeElement
- data Anchor
- data Segment = Segment {
- _segStart :: !Point
- _segEnd :: !Point
- _segKind :: !SegmentKind
- _segDraw :: !SegmentDraw
- data SegmentKind
- data SegmentDraw
- type Point = V2 Int
Documentation
Ascii diagram, transform your ASCII art drawing to a nicer representation
/---------+
+---------+ | |
| ASCII +---->| Diagram |
+---------+ | |
|{flat} | +--+------/
\---*-----/<=======/
::: .flat .filled_shape { fill: #DED; }
Lines
The basic syntax of asciidiagrams is made of lines made out of '-' and '|' characters. They can be connected with anchors like '+' (direct connection) or '\' and '/' (smooth connections)
-----
-------
| |
| |
| \----
|
+-----
You can use dashed lines by using : for vertical lines or '=' for
horizontal line
-----
-=-----
| :
| |
| \----
|
+--=--
Arrows are made out of the '<', '>', '^' and 'v' characters. If the arrows are not connected to any lines, the text is left as is.
^
|
|
<----+---->
| < > v ^
|
v
Shapes
If the lines are closed, then it is detected as such and rendered differently
+------+
| |
| +--+
| | |
+---+--+ |
| |
+-----+
If any of the segment posess one of the dashing markers (':' or '=') Then the full shape will be dashed.
+--+ +--+ +=-+ +=-+ | | : | | | | : +--+ +--+ +--+ +-=+
Any of the angle of a shape can curved one of the smooth corner anchor ('\' or '/')
/--+ +--\ +--+ /--+ | | | | | | | | +--+ +--+ \--+ +--+ /--+ /--\ /--+ /--\ . | | | | | | | | +--/ +--+ \--/ +--/ /--\ . | | \--/ .
Bullets
Adding a '*' on a line or on a shape add a little circle on it. If the bullet is not attached to any shape or lines, then it will be render like any other text.
*-*-*
| | *----*
+---/ |
* * *
When used at connection points, it behaves like the '+' anchor.
Styles
The shapes can ba annotated with a tag like `{tagname}`. Tags will be inserted in the class attribute of the shape and can then be stylized with a CSS.
+--------+ +--------+
| Source +-------->| op1 |
| {src} | \---+----/
+--------+ |
+-------*<--/
+------+<--| op2 |
| Dest | +-------+
|{dst} |
+------+
::: .src .filled_shape { fill: #AAF; }
::: .dst .filled_shape { stroke: #FAA; stroke-width: 3px; }
Inline css styles are introduced with the ":::" prefix at the beginning of the line. They are introduced in the style section of the generated CSS file
The generated geometry also possess some predefined class which are overidable:
- "dashed_elem" is applied on every dashed element.
- "filled_shape" is applied on every closed shape.
- "arrow_head" is applied on arrow head.
- "bullet" on every bullet placed on a shape or line.
- "line_element" on every line element, this include the arrow head.
You can then customize the appearance of the diagram as you want.
Hierarchical styles
Starting with version 1.3, all shapes, text and lines are hierachised, a shape within a shape will be integrated within the same group. This allows more complex styling:
/------------------------------------------------------\ .
|s100 |
| /----------------------------\ |
| |s1 /--------\ | e1 /--------\ |
| | *--->| s2 | +------->| s10 | |
| +----+ \---+----/ | \--------/ |
| | i4 | | | ^ |
| |{ii}+---------\| e1 {lo} | | |
| +----+ vv | ealarm | | e0 /-------------\ .
| | /--------\ +-----------/ +---------->| s50 |
| +----\ | s3 {lu}| | | \-------------/
| | o5 | e2 \--+-----/ | |
| |{oo}|<---------/ |<-\ |
| \-+--+--------------------+--/ | |
| | | | eReset |
| | \-----/ |
| v |
| /--------\ |
| | s20 | {li} |
| \--------/ |
\------------------------------------------------------/
::: .li .line_element { stroke: purple; }
::: .li .arrow_head, .li text { fill: gray; }
::: .lo .line_element { stroke: blue; }
::: .lo .arrow_head, .lo text { fill: green; }
::: .lu .line_element { stroke: red; }
::: .lu .arrow_head, .lu text { fill: orange; }
::: .ii .filled_shape { fill: #DDF; }
::: .ii text { fill: blue; }
::: .oo .filled_shape { fill: #DFD; }
::: .oo text { fill: pink; }
In the previous example, we can see that the lines color are 'shape scoped' and the tag applied to the shape above them applies to them
Shapes
From version 1.3, you can substitute the shape of your element with one from a shape library. Right now the shape library is relatively small:
+---------+ +----------+
| | | |
| circle | | |
| | | io |
|{circle} | | {io} |
+---------+ +----------+
+----------+ +----------+
|document | | |
| | | |
| | | storage |
|{document}| | {storage}|
+----------+ +----------+
::: .circle .filled_shape { shape: circle; }
::: .document .filled_shape { shape: document; }
::: .storage .filled_shape { shape: storage; }
::: .io .filled_shape { shape: io; }
The mechanism use CSS styling to change the shape, if a CSS rule
possess a shape pseudo attribute, then the generated shape is replaced
with a SVG use tag with the value of the shape attribute as href
But, you can create your own style library and change the default stylesheet. You can retrieve the default one with the shell command `asciidiagram --dump-library default-lib.svg`
You can then add your own symbols tag in it and use it by calling `asciidiagram --with-library your-lib.svg`.
Functions
svgOfDiagram :: Diagram -> Document Source #
Transform an Ascii diagram to a SVG document which can be saved or converted to an image.
parseAsciiDiagram :: Text -> Diagram Source #
Analyze an ascii diagram and extract all it's features.
saveAsciiDiagramAsSvg :: FilePath -> Diagram -> IO () Source #
Helper function helping you save a diagram as a SVG file on disk.
imageOfDiagram :: FontCache -> Diagram -> IO (Image PixelRGBA8) Source #
Render a Diagram as an image. The Dpi is 96. The IO dependency is there to allow loading of the font files used in the document.
pdfOfDiagram :: FontCache -> Diagram -> IO ByteString Source #
Render a Diagram into a PDF file. IO dependency to allow loading of the font files used in the document.
Customized rendering
svgOfDiagramAtSize :: GridSize -> Document -> Diagram -> Document Source #
Transform an Ascii diagram to a SVG document which can be saved or converted to an image, with a customizable grid size.
Simple type describing the grid size used during render.
Constructors
| GridSize | |
Fields
| |
defaultGridSize :: GridSize Source #
Default grid size used in the simple render functions
saveAsciiDiagramAsSvgAtSize :: FilePath -> GridSize -> Diagram -> IO () Source #
Helper function helping you save a diagram as a SVG file on disk with a customized grid size.
imageOfDiagramAtSize :: FontCache -> GridSize -> Diagram -> IO (Image PixelRGBA8) Source #
Render a Diagram as an image with a custom grid size. The Dpi is 96. The IO dependency is there to allow loading of the font files used in the document.
pdfOfDiagramAtSize :: FontCache -> GridSize -> Diagram -> IO ByteString Source #
Render a Diagram into a PDF file with a custom grid size. IO dependency to allow loading of the font files used in the document.
Library
defaultLibrary :: GridSize -> Document Source #
Document description
Describe the geomtry of a full Ascii Diagram document
Constructors
| Diagram | |
Fields
| |
Describe where to place a text snippet.
Constructors
| TextZone | |
Fields | |
Shape extracted from the text
Constructors
| Shape | |
Fields
| |
data ShapeElement Source #
Describe a composant of shapes. Can be composed of anchors like "+*/\" or segments.
Constructors
| ShapeAnchor !Point !Anchor | |
| ShapeSegment !Segment |
Instances
| Eq ShapeElement Source # | |
Defined in Text.AsciiDiagram.Geometry | |
| Ord ShapeElement Source # | |
Defined in Text.AsciiDiagram.Geometry Methods compare :: ShapeElement -> ShapeElement -> Ordering # (<) :: ShapeElement -> ShapeElement -> Bool # (<=) :: ShapeElement -> ShapeElement -> Bool # (>) :: ShapeElement -> ShapeElement -> Bool # (>=) :: ShapeElement -> ShapeElement -> Bool # max :: ShapeElement -> ShapeElement -> ShapeElement # min :: ShapeElement -> ShapeElement -> ShapeElement # | |
| Show ShapeElement Source # | |
Defined in Text.AsciiDiagram.Geometry Methods showsPrec :: Int -> ShapeElement -> ShowS # show :: ShapeElement -> String # showList :: [ShapeElement] -> ShowS # | |
Define the different connection points between the segments.
Constructors
| AnchorMulti | Associated to |
| AnchorFirstDiag | Associated to |
| AnchorSecondDiag | Associated to '\' |
| AnchorPoint | Kind of "end anchor", without continuation. |
| AnchorBullet | Used as a |
| AnchorArrowUp | Associated to |
| AnchorArrowDown | Associated to |
| AnchorArrowLeft | Associated to |
| AnchorArrowRight | Associated to |
Define an horizontal or vertical segment.
Constructors
| Segment | |
Fields
| |
data SegmentKind Source #
Helper data for segment composed of only one character
Constructors
| SegmentHorizontal | |
| SegmentVertical |
Instances
| Eq SegmentKind Source # | |
Defined in Text.AsciiDiagram.Geometry | |
| Ord SegmentKind Source # | |
Defined in Text.AsciiDiagram.Geometry Methods compare :: SegmentKind -> SegmentKind -> Ordering # (<) :: SegmentKind -> SegmentKind -> Bool # (<=) :: SegmentKind -> SegmentKind -> Bool # (>) :: SegmentKind -> SegmentKind -> Bool # (>=) :: SegmentKind -> SegmentKind -> Bool # max :: SegmentKind -> SegmentKind -> SegmentKind # min :: SegmentKind -> SegmentKind -> SegmentKind # | |
| Show SegmentKind Source # | |
Defined in Text.AsciiDiagram.Geometry Methods showsPrec :: Int -> SegmentKind -> ShowS # show :: SegmentKind -> String # showList :: [SegmentKind] -> ShowS # | |
data SegmentDraw Source #
Differentiate between elements drawn with a solid line or with dashed lines.
Constructors
| SegmentSolid | |
| SegmentDashed |
Instances
| Eq SegmentDraw Source # | |
Defined in Text.AsciiDiagram.Geometry | |
| Ord SegmentDraw Source # | |
Defined in Text.AsciiDiagram.Geometry Methods compare :: SegmentDraw -> SegmentDraw -> Ordering # (<) :: SegmentDraw -> SegmentDraw -> Bool # (<=) :: SegmentDraw -> SegmentDraw -> Bool # (>) :: SegmentDraw -> SegmentDraw -> Bool # (>=) :: SegmentDraw -> SegmentDraw -> Bool # max :: SegmentDraw -> SegmentDraw -> SegmentDraw # min :: SegmentDraw -> SegmentDraw -> SegmentDraw # | |
| Show SegmentDraw Source # | |
Defined in Text.AsciiDiagram.Geometry Methods showsPrec :: Int -> SegmentDraw -> ShowS # show :: SegmentDraw -> String # showList :: [SegmentDraw] -> ShowS # | |