Skip to content

Initial commit of a PegDown Scala version. #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Hocdoc wants to merge 1 commit into
base: wip-V2
Choose a base branch
from
Open

Initial commit of a PegDown Scala version. #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 2 additions & 128 deletions CHANGELOG
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,130 +1,4 @@
Version 1.2.1 (2011-11-27)
--------------------------
- Upgraded to parboiled 1.1.4
- Added support for caption on tables (thx to Geoffrey Picron)


Version 1.2.0 (2011-10-05)
--------------------------
- Upgraded to parboiled 1.1.3
- Implemented parsing timeout, closes #42
- Fixed IndexOutOfBoundsException in ToHtmlSerializer, closes #39
- Changed parser to not swallow backslash before non-special characters, fixes #35
- Added test for fenced code blocks containing an empty line, closes #61
- Migrated all tests from TestNG to specs2
- Switched build tool from Apache Buildr to SBT


Version 1.1.0 (2011-10-05)
--------------------------
- Upgraded to parboiled 1.0.2
- Introduced LinkRenderer layer for easy customization of HTML link rendering
- Added support for [[Wiki-style]] links, thx to Brett Porter
- Fixed #27 (Missing emphasis when paragraph has multiple lines)
- Fixed #28 (Parser not fully extensible)
- Fixed #32, #33 (HTML tags with attribute names containing underscores are not recognized as tags, thx to Edward Samson)
- Fixed #34 (Pathologically slow parsing when strong and italics emphasis are applied together)


Version 1.0.2 (2011-07-05)
--------------------------
- Simplify custom extensions by making `private` fields/methods of ToHtmlSerializer and Parser `protected`
- Fixed #20 (support GFM fenced code blocks)
- Fixed #21 (simplify integration of custom code transformers)
- Fixed #22 (some characters/sequences break links when AutoLinks extensions is on)
- Fixed broken Java 1.5 compatibility (thx to Julien Nicoulaud)
- Fixed maven build: add testng and jtidy deps for tests, and configure the compiler plugin for java 5 (thx to Lukas Theussl)


Version 1.0.1 (2011-05-17)
--------------------------
- Fixed #18 (code blocks in list items split by lines)


Version 1.0.0 (2011-05-13)
--------------------------
- Closed #3 (PhpMarkdownExtra-style definition lists)
- closed #14 (superfluous paragraph breaks)
- Closed #15 (email obfuscation)
- Closed #16 (PhpMarkdownExtra-style fenced code blocks)
- Closed #17 ('nofollow' links)
- Added buffer indices to AST nodes, enabling markdown syntax highlighting
- Removed tabstop expansion (prevented proper AST node index building)
- Improved single quoting rules for Smartypants extension
- Completely refactored list parsing for code size, performance and simplicity
- Fixed small problem with AutoLink delimiters
- Upgraded to parboiled 1.0.0


Version 0.9.2 (2011-04-06)
--------------------------
- Fix: special characters not encoded correctly in plain text sections
- Fix: HTML hex entities incorrectly parsed
- Add indices into underlying buffer to AST nodes
- Upgraded to parboiled 0.11.1


Version 0.9.1 (2011-03-21)
--------------------------
- Upgraded to parboiled 0.11.0


Version 0.9.0 (2011-02-11)
--------------------------
- Completely overhauled and cleaned up general architecture, split out HTML serialization into AST visitor (thanks to Ravindar Reddy)
- Fixed bug causing the disappearance of text elements in certain list constructs
- Fixed excessive backtracking bug on parsing larger blocks of 'opening-tags-only' HTML
- Fixed file name casing problem causing certain tests to fail on case-sensitive file systems
- Implemented various smaller performance improvements resulting in a general speed-up by 10-30%
- Opened up PegDownProcessor and Parser to custom extensions
- Switched from Ant to Buildr, changed to maven-style project layout
- Changed to 3 part version numbering in preparation of the coming semantic versioning compatibility (http://semver.org)
- Upgraded to parboiled 0.10.1


Version 0.8.5.4 (2010-10-04)
Version 0.1.0.1 (2013-02-06)
----------------------------
- Switched off superfluous parse tree building resulting in nearly doubled parsing performance
- Upgraded to parboiled 0.9.9.0


Version 0.8.5.3 (2010-08-13)
----------------------------
- Added HTML suppression options
- Upgraded to parboiled 0.9.8.2 (another ~ 5% performance increase by using a few @MemoMismatches annotations)


Version 0.8.5.2 (2010-08-12)
----------------------------
- Upgraded to parboiled 0.9.8.1 (~ 10% performance increase, slightly simplified parser)


Version 0.8.5.1 (2010-06-19)
----------------------------
- Fixed several problems, especially with regard to image links (thanks to Nick Ewing for the report)
- Added support for double angle quotes to the QUOTES extension
- Further increased test coverage


Version 0.8.5.0 (2010-06-14)
----------------------------
- Completely rewrote AST implementation improving maintainability and simplifying further extensions
- Fixed different problems, mainly related to the ABBREVIATIONS extension
- Added TABLES extension
- Added simple benchmarking "test"


Version 0.8.1.0 (2010-06-08)
----------------------------
- Fixed problem with SetextHeading2
- Fixed performance problem in inputs with complex emphasis constructs
- Added ABBREVIATIONS extension
- Added HARDWRAPS extension
- Added AUTOLINKS extension
- Added support for parens in link urls (must be escaped in explicit links)
- Expanded test coverage


Version 0.8.0.1 (2010-04-30)
----------------------------
first public release
* first public release
5 changes: 0 additions & 5 deletions NOTICE
View file
Open in desktop

This file was deleted.

91 changes: 30 additions & 61 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
Introduction
------------

_pegdown_ is a pure Java library for clean and lightweight [Markdown] processing based on a [parboiled] PEG parser.
_pegdownScala_ is a pure Scala library for clean and lightweight [Markdown] processing based on a [parboiled] PEG parser.

_pegdown_ is nearly 100% compatible with the original Markdown specification and fully passes the original Markdown test suite.
On top of the standard Markdown feature set _pegdown_ implements a number of extensions similar to what other popular Markdown processors offer.
Currently _pegdown_ supports the following extensions over standard Markdown:
_pegdownScala_ is nearly 100% compatible with the original Markdown specification and fully passes the original Markdown test suite.
On top of the standard Markdown feature set _pegdownScala_ implements a number of extensions similar to what other popular Markdown processors offer.
Currently _pegdownScala_ supports the following extensions over standard Markdown:

* SMARTS: Beautifies apostrophes, ellipses ("..." and ". . .") and dashes ("--" and "---")
* QUOTES: Beautifies single quotes, double quotes and double angle quotes (« and »)
Expand All @@ -20,100 +20,69 @@ Currently _pegdown_ supports the following extensions over standard Markdown:
* INLINE HTML SUPPRESSION: Suppresses the output of inline HTML elements.
* WIKILINKS: Support `[[Wiki-style links]]` with a customizable URL rendering logic.

Note: _pegdown_ differs from the original Markdown in that it ignores in-word emphasis as in
Note: _pegdownScala_ differs from the original Markdown in that it ignores in-word emphasis as in

> my_cool_file.txt
> 2*3*4=5

Currently this "extension" cannot be switched off.

Differences to pegdown
----------------------

Installation
------------
_pegdownScala_ is a port of the great [PegDown] Java library from Mathias Doenitz.
There are some differences to the Java Version.

Pros:

You have two options:
* The parser is implemented as immutable class and thread safe.
* Should run on the Google AppEngine.
* More compact Scala code (30% of the Java code lines).
* No time expensive parser extension step.

* Download the JAR for the latest version from the [download page].
_pegdown_ 1.2.0 has only one dependency: [parboiled for Java][parboiled], version 1.1.3.

* The pegdown artifact is also available from maven central with group id **org.pegdown** and artifact-id **pegdown**.
Cons:

* pegdownScala is a beta version: interlaced HTML tags doesn't work correct,
PegDown is much better tested.
* No implementation for timeouts in pegdownScala. You may want to use Akka to handle long tasks.
* pegdownScala isn't optimized for performance.

Usage
-----

Using _pegdown_ is very simple: Just create a new instance of a [PegDownProcessor] and call one of its
`markdownToHtml` methods to convert the given Markdown source to an HTML string. If you'd like to customize the
rendering of HTML links (Auto-Links, Explicit-Links, Mail-Links, Reference-Links and/or Wiki-Links), e.g. for adding
`rel="nofollow"` attributes based on some logic you can supply your own instance of a [LinkRenderer] with the call
to `markdownToHtml`.

You can also use pegdown only for the actual parsing of the Markdown source and do the serialization to the
target format (e.g. XML) yourself. To do this just call the `parseMarkdown` method of the [PegDownProcessor] to obtain
the root node of the Astract Syntax Tree for the document.
With a custom [Visitor] implementation you can do whatever serialization you want. As an example you might want to
take a look at the [sources of the ToHtmlSerializer][ToHtmlSerializer].

Note that the first time you create a [PegDownProcessor] it can take up to a few hundred milliseconds to prepare the
underlying parboiled parser instance. However, once the first processor has been built all further instantiations will
be fast. Also, you can reuse an existing [PegDownProcessor] instance as often as you want, as long as you prevent
concurrent accesses, since neither the [PegDownProcessor] nor the underlying parser is thread-safe.

See <http://sirthias.github.com/pegdown/api> for the pegdown API documentation.


Parsing Timeouts
----------------

Since Markdown has no official grammar and contains a number of ambiguities the parsing of Markdown source, especially
with enabled language extensions, can be "hard" and result, in certain corner cases, in exponential parsing time.
In order to provide a somewhat predictable behavior *pegdown* therefore supports the specification of a parsing timeout,
which you can supply to the [PegDownProcessor] constructor.
Using _pegdownScala_ is very simple: Just call `ToHtmlSeralizer(markdownSource)`.

If the parser happens to run longer than the specified timeout period it terminates itself with an exception, which
causes the `markdownToHtml` method to return `null`. Your application should then deal with this case accordingly and,
for example, inform the user.
TODO: Add more documentation.

The default timeout, if not explicitly specified, is 2 seconds.


IDE Support
-----------

The excellent [idea-markdown plugin] for IntelliJ IDEA, RubyMine, PhpStorm, WebStorm, PyCharm and appCode uses _pegdown_
as its underlying parsing engine. The plugin gives you proper syntax-highlighting for markdown source and shows you
exactly, how _pegdown_ will parse your texts.
You can also use _pegdownScala_ from the command line to convert a Markdown file to HTML:

`pegdownScala <MarkdownFilename.md>`

Credits
-------

All the code is based on [PegDown] from Mathias Doenitz. I would never be able to build this
Scala port without your great work.

A large part of the underlying PEG grammar was developed by John MacFarlane and made available with his
tool [peg-markdown](http://github.com/jgm/peg-markdown).


License
-------

_pegdown_ is licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).


Patch Policy
------------
_pegdownScala_ is licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).

Feedback and contributions to the project, no matter what kind, are always very welcome.
However, patches can only be accepted from their original author.
Along with any patches, please state that the patch is your original work and that you license the work to the pegdown project under the project’s open source license.

[Markdown]: http://daringfireball.net/projects/markdown/ "Main Markdown site"
[parboiled]: http://www.parboiled.org
[Github-flavoured-Markdown]: http://github.github.com/github-flavored-markdown/
[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/users_guide/multimarkdown_syntax_guide/
[Download Page]: http://github.com/sirthias/pegdown/downloads
[PegDown]: https://github.com/sirthias/pegdown
[PegDownProcessor]: http://www.decodified.com/pegdown/api/org/pegdown/PegDownProcessor.html
[LinkRenderer]: http://www.decodified.com/pegdown/api/org/pegdown/LinkRenderer.html
[Visitor]: http://www.decodified.com/pegdown/api/org/pegdown/ast/Visitor.html
[ToHtmlSerializer]: https://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/ToHtmlSerializer.java
[idea-markdown plugin]: https://github.com/nicoulaj/idea-markdown
[SBT]: http://www.scala-sbt.org/
[Node]: http://www.decodified.com/pegdown/api/org/pegdown/ast/Node.html
[Node]: http://www.decodified.com/pegdown/api/org/pegdown/ast/Node.html
70 changes: 10 additions & 60 deletions build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,25 @@
name := "pegdown"
name := "pegdownScala"

version := "1.2.1"
version := "0.1"

scalaVersion := "2.10.0"

homepage := Some(new URL("http://pegdown.org"))

organization := "org.pegdown"

organizationHomepage := Some(new URL("http://pegdown.org"))

description := "A Java 1.5+ library providing a clean and lightweight markdown processor"
description := "A Scala library providing a clean and lightweight markdown processor"

startYear := Some(2009)
startYear := Some(2013)

licenses := Seq("Apache 2" -> new URL("http://www.apache.org/licenses/LICENSE-2.0.txt"))

javacOptions ++= Seq(
"-g", // required for byte-code rewriting in parboiled-java!
"-deprecation",
"-target", "1.5",
"-source", "1.5",
"-encoding", "utf8",
"-Xlint:unchecked"
)

javacOptions in doc := Seq(
"-source", "1.5",
"-encoding", "utf8"
)

scalaVersion := "2.9.2"

scalacOptions := Seq("-unchecked", "-deprecation", "-encoding", "utf8")

libraryDependencies ++= Seq(
"org.parboiled" % "parboiled-java" % "1.1.4",
libraryDependencies ++= Seq(
"org.parboiled" % "parboiled-scala_2.10" % "1.1.4",
"net.sf.jtidy" % "jtidy" % "r938" % "test",
"org.specs2" %% "specs2" % "1.12.2" % "test"
"org.specs2" %% "specs2" % "1.13" % "test",
"com.novocode" % "junit-interface" % "0.10-M2" % "test"
)

resolvers += Opts.resolver.sonatypeReleases

// publishing

crossPaths := false

autoScalaLibrary := false

publishMavenStyle := true

publishArtifact in Test := false

pomIncludeRepository := { _ => false }

useGpg := true

pgpSigningKey := Some(-2321133875171851978L)

publishTo <<= version { v: String =>
val nexus = "https://oss.sonatype.org/"
if (v.trim.endsWith("SNAPSHOT")) Some("snapshots" at nexus + "content/repositories/snapshots")
else Some("releases" at nexus + "service/local/staging/deploy/maven2")
}

pomExtra :=
<scm>
<url>git@github.com:sirthias/pegdown.git</url>
<connection>scm:git:git@github.com:sirthias/pegdown.git</connection>
</scm>
<developers>
<developer>
<id>sirthias</id>
<name>Mathias Doenitz</name>
</developer>
</developers>
Loading