{"id":13828585,"url":"https://github.com/dhobsd/asciitosvg","last_synced_at":"2025-04-07T12:09:19.417Z","repository":{"id":26338857,"uuid":"29787618","full_name":"dhobsd/asciitosvg","owner":"dhobsd","description":"DANGER, WILL ROBINSON: THIS REPOSITORY IS IN MAINTENANCE MODE! I will not be continuing feature development or fixing bugs in this codebase. I will continue to review and accept pull requests that do this. Please click the following link to view the actively developed ASCIIToSVG codebase, which is written in Go.","archived":false,"fork":false,"pushed_at":"2020-07-30T16:30:24.000Z","size":505,"stargazers_count":347,"open_issues_count":1,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-31T11:02:42.227Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://github.com/asciitosvg/asciitosvg","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhobsd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-24T18:54:17.000Z","updated_at":"2024-06-25T22:38:02.000Z","dependencies_parsed_at":"2022-08-30T05:05:24.264Z","dependency_job_id":null,"html_url":"https://github.com/dhobsd/asciitosvg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhobsd%2Fasciitosvg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhobsd%2Fasciitosvg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhobsd%2Fasciitosvg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhobsd%2Fasciitosvg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhobsd","download_url":"https://codeload.github.com/dhobsd/asciitosvg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T09:02:53.645Z","updated_at":"2025-04-07T12:09:19.380Z","avatar_url":"https://github.com/dhobsd.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# ASCIIToSVG ################################################################\n\n                      .-------------------------.\n                      |                         |\n                      | .---.-. .-----. .-----. |\n                      | | .-. | +--\u003e  | |  \u003c--| |\n                      | | '-' | |  \u003c--| +--\u003e  | |\n                      | '---'-' '-----' '-----' |\n                      |  ascii     2      svg   |\n                      |                         |\n                      '-------------------------'\n                       https://9vx.org/~dho/a2s/\n\n# WARNING ###################################################################\n\nI haven't written PHP in years, and this implementation has numerous\ndrawbacks. I recommend you look into using the\n[Go implementation](https://github.com/asciitosvg/asciitosvg) instead. I will\ncontinue to accept, review, and merge PRs to this repository, and (where\nappropriate) mirror any new functionality in the Go version, but I do not\nintend to identify new bugs, fux old bugs, or self-author new functionality\nin this repository.\n\n## Introduction #############################################################\n\n### License #################################################################\n\nASCIIToSVG is copyright © 2012 Devon H. O'Dell and is distributed under an\nawesome 2-clause BSD license. All code without explicit copyright retains\nthis license. Any code not adhering to this license is explicit in its own\ncopyright.\n\n### What does it do? ########################################################\n\nASCIIToSVG is a pretty simple PHP library for parsing ASCII art diagrams and\nconverting them to a pretty SVG output format.\n\n### But... why? #############################################################\n\nThere are a few reasons, mostly to do with things I really like:\n\n * I like markdown a lot. If I could write everything in markdown, I\n   probably would. \n * I like ASCII art a lot. I've been playing around with drawing ASCII art\n   since I was both a wee lad and a BBS user.\n * I like pretty pictures. People say they're worth a thousand words.\n\nSo I thought, \"What if I could combine all these things and start writing\nmarkdown documents for my technical designs -- complete with ASCII art\ndiagrams -- that I could then prettify for presentation purposes?\"\n\n### Aren't there already things that do this? ###############################\n\nWell, yes. There is a project called [ditaa][1] that has this functionality.\nSort of. But it's written in Java and it generates PNG output. I needed\nsomething that would generate scalable output, and would be a bit easier to\nintegrate into a wiki (like the one in [mtrack][2], which we use at work).\nWe got it integrated, but I ran into a few bugs and rendering nits that I\ndidn't like. Additionally, it takes a long time to shell out the process\nand JVM to generate the PNG. If you're doing inline edits on an image, you\ncan imagine that this gets to be a heavy load on both the client and\nserver, just from a data transfer perspective alone.\n\nSo I reimplemented it in PHP. There are some things it can do better, and\nI'm aware of a few rendering bugs already, but so far it works better and\nis more extensible than ditaa, and I'm enjoying it more.\n\n## Building ASCIIToSVG ######################################################\n\nWhat?! Building?!?! Isn't this PHP?\n\nWell, yes. But some of it is tool-generated. If you check out the code, you\nwill get the latest generated code, don't worry! This information is more\nfor people who want to contribute and need to make changes to the SVG path\nparser.\n\nYou will need [JLexPHP][7] and [lemon-php][8] to build the tokenizer and\nparser for the SVG paths. (This parser was implemented [from the SVG 1.1\npaths BNF][9].) JLexPHP requires the JDK to build; lemon-php requires a C\ncompiler.\n\nYou should have the following structure one your repository:\n\n    .\n    ├── JLexPHP\n    ├── asciitosvg\n    └── lemon-php\n\nSimply running `make` on asciitosvg should be enough to get all the autogenerated \nstuff running. It will also update the logo. Please make sure to view the logo and\ntest files to make sure that you haven't broken any rendering.\n\nMake clean will remove extraneous files that aren't necessary for running;\nmake distclean removes everything autogenerated.\n\n## Using ASCIIToSVG #########################################################\n\n### Command Line ############################################################\n\nA command line utility exists to convert the ASCII file to SVG. You can put\nthis somewhere inside your `$PATH` and set its permissions to +x. You can also symlink\nto it by adding `ln -s /Users/asciitosvg/a2s a2s` in `/usr/local/bin`.\nWindows users will have to make their own batch file to run this or remove the first\nline. Usage:\n\n    Usage: a2s [-i[-|filename]] [-o[-|filename]] [-sx-scale,y-scale]\n      -h: This usage screen.\n      -i: Path to input text file. If unspecified, or set to \"-\" (hyphen),\n          stdin is used.\n      -o: Path to output SVG file. If unspecified or set to \"-\" (hyphen),\n          stdout is used.\n      -s: Grid scale in pixels. If unspecified, each grid unit on the X\n          axis is set to 9 pixels; each grid unit on the Y axis is 16 pixels.\n\nNote that this uses PHP's `getopt` which handles short options stupidly. You\nneed to put the actual argument right next to the flag; no space. For\nexample: `a2s -i- -oout.svg -s10,17` would be a valid command line\ninvocation for this utility.\n\n### Class API ###############################################################\n\nThere are plenty of comments explaining how everything works (and I'm sure\nseveral bugs negating the truth of some of those explanations) in the source\nfile. Basic flow through the API is:\n\n    :::php\n    $asciiDiagram = file_get_contents('some_pretty_art');\n    $o = new org\\dh0\\a2s\\ASCIIToSVG($asciiDiagram);\n    $o-\u003esetDimensionScale(9, 16);\n    $o-\u003eparseGrid();\n    file_put_contents('some_pretty_art.svg', $o-\u003erender());\n\nI'll put more detailed information in the [wiki][3] and this `README` as I\nhave time and inclination to do so.\n\n## How Do I Draw? ###########################################################\n\nEnough yammering about the impetus, code, and functionality. I bet you want\nto draw something. ASCIIToSVG supports a few different ways to do that. If\nyou have more questions, take a look at some of the files in the `test`\nsubdirectory. (If you have a particularly nice diagram you'd like to see\nincluded for demo, feel free to send it my way!)\n\n### Basics: Boxes and Lines #################################################\n\nBoxes can be polygons of almost any shape (don't try anything too wacky\njust yet; I haven't). Horizontal, vertical, and diagonal lines are all\nsupported, giving ASCIIToSVG basically complete support for output from\n[App::Asciio][4]. Edges of boxes and lines can be drawn by using the\nfollowing characters:\n\n * `-` or `=`: Horizontal lines (dash, equals)\n * `|` or `:`: Vertical line (pipe, colon)\n * `*`: Line of ambiguous direction (asterisk)\n * `\\` or `/`: Diagonal line (backward slash, forward slash)\n * `+`: Edge of line passing through a box or line corner (plus)\n\nThe existence of a `:` or `=` edge on a line causes that line to be\nrendered as a dashed line.\n\nTo draw a box or turn a line, you need to specify corners. The following\ncharacters are valid corner characters:\n\n * `'` and `.`: Quadratic Bézier corners (apostrophe, period)\n * `#`: Boxed, angular, 90 degree corners for boxes (hash)\n * `+`: Boxed, angular, 90 degree corners for lines (plus)\n\nThe `+` token is a control point for lines. It denotes an area where a line\nintersects another line or traverses a box boundary.\n\nA simple box with 3 rounded corners and a line pointing at it:\n\n    #----------.\n    |          | \u003c---------\n    '----------'\n\n#### A Quick Note on Diagonals ##############################################\n\nDiagonal lines cannot be made to form a closed box. If you would like to\nmake diagrams using parallelograms / diamonds (perhaps for flow charts), it\nis recommended that you annotate regular boxes and use custom objects (see\nbelow) instead. Diagonal lines also may not use `'` or `.` smoothed corners.\n\n### Basics: Markers #########################################################\n\nMarkers can be attached at the end of a line to give it a nice arrow by\nusing one of the following characters:\n\n * `\u003c`: Left marker (less than)\n * `\u003e`: Right marker (greater than)\n * `^`: Up marker (carat)\n * `v`: Down marker (letter v)\n\n### Basics: Text ############################################################\n\nText can be inserted at almost any point in the image. Text is rendered in\na monospaced font. There aren't many restrictions, but obviously anything\nyou type that looks like it's actually a line or a box is going to be a good\ncandidate for turning into some pretty SVG path. Here is a box with some\nplain black text in it:\n\n    .-------------------------------------.\n    | Hello here and there and everywhere |\n    '-------------------------------------'\n\n### Basics: Formatting #####################################################\n\nIt's possible to change the format of any boxes / polygons you create. This\nis done (true to markdown form) by providing a reference on the top left\nedge of the object, and defining that reference at the bottom of the input.\nLet me reiterate that the references *must* be defined at the *bottom* of\nthe input. An example:\n\n    .-------------.  .--------------.\n    |[Red Box]    |  |[Blue Box]    |\n    '-------------'  '--------------'\n\n    [Red Box]: {\"fill\":\"#aa4444\"}\n    [Blue Box]: {\"fill\":\"#ccccff\"}\n\nText appearing within a stylized box automatically tries to fix the color\ncontrast if the black text would be too dark on the background. The\nreference commands can take any valid SVG properties / settings for a\n[path element][5]. The commands are specified in JSON form, one per line.\nReference commands do not accept nested JSON objects -- don't try to\nplace additional curly braces inside!\n\nThe text of a reference is left in the polygon, making it useful as an\nobject title. You can have the reference removed by adding an option\n`a2s:delref` to the options JSON object. Any value will suffice to have\nthe reference fully removed from the polygon. You can also replace the\ntext in the label by specifying `a2s:label`.\n\nThis method is (in my opinion) much nicer than the one provided by ditaa:\n\n * It eats up less space.\n * It fits in smaller boxes.\n * It allows more customization.\n * It's easier to see what formatting changes happened in diffs.\n * It's easier to read any text nested in the box itself.\n\nBut that's just me. If you have thoughts on how to do this for lines,\nplease do let me know.\n\n#### Special References #####################################################\n\nIt is possible to reference an object by its starting row and column. The\nrows and columns start at (0, 0) in the top left of the diagram. Such\nreferences should only be made for stable diagrams, and only if you *really*\nneed to style text or a line in some particular way. Such references are\nmarked by starting the line with `[R,C]` where `R` is the numeric row and \n`C` is the numeric column.\n\nNote that boxes start from their top left corner. Text starts from the first\nnon-whitespace character on a line (and only traverses a single space in\nbetween text points). Lines start from the left-most point on the line that\nis not adjoined to any other objects.\n\n### Basics: Special Objects #################################################\n\nThere was some pretty nifty functionality in ditaa for special box types.\nThe ones I was most interested in were the `storage` and `document` box,\nthough I recently learned there are more than are advertised on the website.\nTo do this, one adds an `a2s:type` option to the box and specifies one of\nthe supported object types:\n\n * `storage`: The standard \"storage\" cylinder.\n * `document`: The standard document box with a wavy bottom.\n * `cloud`: A network cloud.\n * `computer`: Something that looks kind of like an iMac.\n\n### Creating Special Objects ################################################\n\nAlthough a tutorial on SVG is out of the scope of this document, it is\npossible to create your own custom objects for your own graphs! Fire up your\nfavorite vector editor that is capable of producing SVG output (if you don't\nhave one, [Inkscape][10] will work fine). Draw to your heart's content and\nsave your drawing as an SVG image (you will need to use the path tool; any\npremade shapes aren't supported). Open the image and extract all the path\ntags; put them in a file called `object.path`. Place this file in the\n`objects` directory. Any time you reference `\"a2s:type\":\"object\"`, your new\nobject will take the place of the box you created.\n\nThere are a few caveats to this approach:\n\n * You *must* specify the width and height of the original canvas in every\n   path, although there are no minimum or maximum values, nor is there any\n   required aspect ratio.\n * The path (or any group it is in) of the original SVG file must not be\n   transformed in any way. (Inkscape will do this if you change your\n   document size after you start drawing, for instance.)\n * Extraneous tags (i.e. things that aren't `\u003cpath ... /\u003e`) will probably\n   break the object parser.\n * Objects are cached in `$TMPDIR/.a2s.objcache`. If multiple users are\n   using ASCIIToSVG on the same machine, this probably isn't very safe.\n * Reference options are currently only applied to the first path;\n   additional paths are drawn with the default options of the group. This\n   means you probably want your first object to be an outline.\n\nIf you're particularly happy with an object and want to share it, feel free\nto submit it!\n\n## External Resources #######################################################\n\nThere are some interesting sites that you might be interested in; these are\nmildly related to the goals of ASCIIToSVG:\n\n * [ditaa][1] (previously mentioned) is a Java utility with a very similar\n   syntax that translates ASCII diagrams into PNG files.\n * [App::Asciio][4] (previously mentioned) allows you to programmatically\n   draw ASCII diagrams.\n * [Asciiflow][6] is a web front-end to designing ASCII flowcharts.\n   \nIf you have something really cool that is related to ASCIIToSVG, and I have\nfailed to list it here, do please let me know.\n\n## References ###############################################################\n\nIf there's nothing here, you're looking at this README post-markdown-ified.\n\n[1]: http://ditaa.sourceforge.net/ \"ditaa - DIagrams Through ASCII Art\"\n[2]: http://mtrack.wezfurlong.org/ \"mtrack project management software\"\n[3]: https://bitbucket.org/dhobsd/asciitosvg/wiki/Home \"a2s wiki page\"\n[4]: http://search.cpan.org/dist/App-Asciio/lib/App/Asciio.pm \"App::Asciio\"\n[5]: http://www.w3.org/TR/SVG/paths.html \"SVG Paths\"\n[6]: http://www.asciiflow.com/ \"Asciiflow\"\n[7]: http://bitbucket.org/wez/jlexphp \"JLexPHP\"\n[8]: https://bitbucket.org/wez/lemon-php \"lemon-php\"\n[9]: http://www.w3.org/TR/SVG/paths.html#PathDataBNF \"SVG Path Grammar\"\n[10]: http://inkscape.org/download \"Download Inkscape\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhobsd%2Fasciitosvg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhobsd%2Fasciitosvg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhobsd%2Fasciitosvg/lists"}