diff --git a/README.md b/README.md new file mode 100644 index 0000000..1fb555c --- /dev/null +++ b/README.md @@ -0,0 +1,163 @@ + + + + +jscreole - Parse Creole into DOM +================================ +```js +var creole = new creole({ + interwiki: { + MeatballWiki: 'http://www.usemod.com/cgi-bin/mb.pl?', + TiddlyWiki: 'http://www.tiddlywiki.com/#', + WikiCreole: 'http://www.wikicreole.org/wiki/', + Palindrome: function(link) { + return 'http://www.example.com/wiki/' + link.split('').reverse().join(''); + } + }, + linkFormat: '#' +}); + +var div = document.createElement('div'); +creole.parse(div, "* This is [[Wikipedia:Wikitext|wikitext]]"); +``` + +This module implements Creole 1.0 parser, as defined by +http://www.wikicreole.org/wiki/Creole1.0 . + + + +Options +------- + +* `defaultImageText`: Alternative text for an image with no alternative text + ```text + {{image.png}} + ``` + + as opposed to empty alternative text + ```text + {{image.png|}} + ``` + + Note that strict Creole 1.0 doesn't allow images with no alternative text. + +* `interwiki`: Interwiki map. Object properties' values are strings, arrays of one or two + strings, or functions. The first string is a leading part + of the URL. If the second string is given as well, it is a + trailing part. If the value is a function, which takes a link identifier as an + argument, its return value is the whole URL. + +* `linkFormat`: Internal links' format. Same format as in ["interwiki"](#interwiki)'s properties. + +* `strict`: Whether the parser is strict Creole 1.0. For constructor only, i. e. + non-overridable in `parse` method. A non-strict parser allows images in tables + and images with no alternative text. + + +creole._base - Parse text into DOM +================================== +```js +// Define grammar +var g = { + para: { _tag: 'p', + _regex: /([ \t]*\S.+((\r?\n|\r)[ \t]*\S.*)*)/, _capture: 0 } +}; +g._root = { _children: [ g.para ] }; + +// Create parser +var parser = new creole._base(g); + +// Parse +var div = document.createElement('div'); +parser.parse(div, 'para\n' + + ' continues\n\n' + + 'another para\n \n' + + 'yet another para'); +``` + +This module implements a simple recursive descent parser using regular +expressions for lexical analysis. The result is stored into a DOM object, +that can be then put in a document or traversed using standard DOM API. + + + +Parser +------ + +* `new creole._base(grammar, options)`: + + The constructor creates a new parser object given a grammar and options. + The grammar is an object of any type, which must contain a root property, + that also must be an object of any type. The root is cast to a + type specified by `this._ruleConstructor`, being `creole._rule` + by default. See ["Rules"](#rules) for more info on defining rule objects. + + Options are optional but if passed it must be an object. The only option + available in `creole._base` is `forIE`, which should be set `true` for + Microsoft Internet Explorer compatibility. Derived objects and subinterfaces + may extend the `options` object with their own options. + +* `parse(node, data, options)`: + + This method parses flat text data and creates a DOM tree inside a given node, + which should be a Node object. If options are passed, they override those + passed to the constructor. Options merge at the first depth, merging + nested options is not supported. + + +Rules +----- + +* `_regex`: A regular expression to match the input. + +* `_capture`: What should be captured for the output data: 0 for the whole matched substring, + 1 and so on for corresponding capturing brackets. If not listed, data will be + empty. + +* `_replaceRegex`, `_replaceString`: If set, captured data will be processed before output. + +* `_tag`: If set, captured data will be enclosed inside a new child element, otherwise + they will be put in the current node. + +* `_attrs`: If set to an object, a new child element will have the given attributes. + +* `_children`: An array of grammar rules, which define possible child nodes. + +* `_fallback`: If there are chunks which don't match any child rule, they are being + processed with this one. + + +Author +====== + +Ivan Fomichev <[ifomichev@gmail.com](mailto:ifomichev@gmail.com)> + + + +Copyright +========= +```text +Copyright (c) 2008 Ivan Fomichev + +Portions Copyright (c) 2007 Chris Purcell + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +``` diff --git a/util/npm-pkg/.gitignore b/util/npm-pkg/.gitignore new file mode 100644 index 0000000..81ef5a8 --- /dev/null +++ b/util/npm-pkg/.gitignore @@ -0,0 +1,2 @@ + +/Pod/Markdown.pm diff --git a/util/npm-pkg/perl-podmd-optim.sed b/util/npm-pkg/perl-podmd-optim.sed new file mode 100755 index 0000000..535643b --- /dev/null +++ b/util/npm-pkg/perl-podmd-optim.sed @@ -0,0 +1,52 @@ +#!/bin/sed -nrf +# -*- coding: UTF-8, tab-width: 2 -*- + +: read_all + $!{N;b read_all} +: normalize_input + s~[ \t]+(\n|$)~\1~g + s~^\s*~\n\n\n~ + +: identify_blocks + s~\n# NAME\n+([^\f\n]+\n)~\n\n\1\f=\1~g + s~\n# (DESCRIPTION|SYNOPSIS)\n+~\n~g + # s~\n((\n+ {4}[^\f\n]+)+)~\f\1\f~g + +: simple_transforms + s~\f([A-Z])([A-Z]+)~\1\L\2\E~g + +: code_block_init + s~(\f)(\n*)~\2```\n\1~g + s~(```)(\n\f[^\f]*\n *var [a-z]+ = )~\1js\2~g + s~(```)(\n\f)~\1text\2~g + s~(\n*)(\f)~\n\2```\1~g +: code_block_again + s~(\f)(\n+)~\2\1~g + s~(\f) {4}([^\f\n]+)~\2\1~g + s~(\f)(\f)~~g +t code_block_again + +: underline + #s~(^|\n)([^\n]+\n) *(\f)~\n\f\2\2\3~g + #s~\f([A-Za-z-]+)\b[^\n]*~~g + s~(\f)(\S)[^\f\n]~\2\1\2~g + s~(\f)(\S)(\n|$)~\3~g +t underline + +: list_optim + s~(\n *\- )((new |[A-Za-z]+\.)*([a-z\\_]+[A-Z]?)+(|\ + | *\([^\n]*\)))\n~\1`\2`\n~g + + + +: normalize_output + s~^\s+~~ + s~\s*$~\n~ + s~\n+=cut\n+$~~ + p +b eof + + + + +: eof diff --git a/util/npm-pkg/pod2md.sed b/util/npm-pkg/pod2md.sed new file mode 100755 index 0000000..77e7688 --- /dev/null +++ b/util/npm-pkg/pod2md.sed @@ -0,0 +1,79 @@ +#!/bin/sed -rf +# -*- coding: UTF-8, tab-width: 2 -*- + +: read_all + $!{N;b read_all} +: normalize_input + s~[ \t]+(\n|$)~\1~g + +: identify_blocks + s~(^|\n)=head1 NAME\n+([^\f\n]+\n)~\n\n\1\2\f=\2~g + s~\n=head[1-9] (DESCRIPTION|SYNOPSIS)\n+~\n~g + s~\n=head1 (AUTHOR|COPYRIGHT)\n~\n\n\f\1\ + \f=\1\n~g + s~\n=head2 ([A-Z][a-z]+)\n+~\n\n\1\n\f-\1\n\n~g + s~\n((\n+ [^\f\n]+)+)~\f\1\f~g + +: simple_transforms + s~\f([A-Z])([A-Z]+)~\1\L\2\E~g + s~\bC<([^<>]+)>~`\1`~g + +: code_block_init + s~(\f)(\n*)~\2```\n\1~g + s~(```)(\n\f[^\f]*\n *var [a-z]+ = )~\1js\2~g + s~(```)(\n\f)~\1text\2~g + s~(\n*)(\f)~\n\2```\1~g +: code_block_again + s~(\f)(\n+)~\2\1~g + s~(\f) {2}([^\f\n]+)~\2\1~g + s~(\f)(\f)~~g +t code_block_again + +: underline + s~(^|\n)([^\n]+\n) *(\f)~\n\f\2\2\3~g + s~\f([A-Za-z-]+)\b[^\n]*~~g + s~(\f)(\S)[^\f\n]~\2\1\2~g + s~(\f)(\S)(\n|$)~\3~g +t underline + +: list_init + s~\n=over\n~\n\f
    ~g + s~\n=item ([^\f\n]+)\n~\f\n* \1:\n\f
  • ~g + s~\n=item(\n+)~\n* \f
  • ~g + s~\n=back\n~\n\f
~g +: list_indent + s~(\f
  • )([^\f\n]*)(\n+)~ \2\3\1~g +t list_indent +: list_clean_indent + s~ +\n~\n~g + s~\n+\f<(li|ul)>\f\n+~\n\n~g +: list_mark_identifiers + s~(\n *\* )((new |[A-Za-z]+\.)*([a-z_]+[A-Z]?)+(|\ + | *\([^\n]*\))):\n~\1`\2`:\n~g +: list_merge_word_defs + s~(\n *\* [`A-Za-z_-, ]+):\n+ *\* ([`A-Za-z_-]+:\n)~\1, \2~g + s~(\n *\* [`A-Za-z_-, ]+:)\n+ {2}([A-Z])~\1 \2~g +t list_merge_word_defs + +: links + s~(\n *\* )(`([A-Za-z-]+)`)(\n|:)~\1\2\4~g + s~(\b|<)F<([^\f\n <>]+@[^\f\n <>]+)>(>|)~\1[\2](mailto:\2)\3~g + s~\bL<("?([A-Za-z-]+)"?)>~[\1](#\L\2\E)~g + s~\bL<([a-z]{2,8}://[^\f\n <>]+)>~\f \1 \f~g + s~(^|\n|<| )\f ~\1~g + s~ \f( |>|\n|$)~\1~g + s~\f~~g + + +: normalize_output + s~^\s+~~ + s~\s*$~\n~ + s~\n+=cut\n+$~~ + s~^~\n\n\n~ + p +b eof + + + + +: eof diff --git a/util/npm-pkg/upd-meta.sh b/util/npm-pkg/upd-meta.sh new file mode 100755 index 0000000..36c7fb5 --- /dev/null +++ b/util/npm-pkg/upd-meta.sh @@ -0,0 +1,81 @@ +#!/bin/bash +# -*- coding: utf-8, tab-width: 2 -*- +SELFPATH="$(readlink -m "$0"/..)" + + +function upd_npm_pkg_meta () { + cd "$SELFPATH" || return $? + + local PODMD_MOD= + # PODMD_MOD='Pod::Markdown' + # ^-- tested 2015-06-21: yielded quite some ugly Markdown, and no easy + # way to tell code block indentation apart from list indentation. + [ -z "$PODMD_MOD" ] || perl_podmd_test 2>/dev/null \ + || perl_podmd_download || return $? + + local SRC_FN= + for SRC_FN in ../../*.pod; do + pod2markdown "$SRC_FN" || return $? + done + + return 0 +} + + +function perl_podmd_test () { + perl -M"$PODMD_MOD" -e ''; return $? +} + + +function perl_podmd_download () { + echo "W: Perl module $PODMD_MOD seems to not be installed." \ + "Will try to download it:" >&2 + local CPAN_DL_BASE='https://api.metacpan.org/source/' + local PODMD_CPAN_DL='RWSTAUNER/Pod-Markdown-2.002/lib/Pod/Markdown.pm' + local SAVE_FN="${PODMD_MOD//:://}".pm + mkdir -p "${SAVE_FN%/*.pm}" || return $? + wget -O "$SAVE_FN" -c "${CPAN_DL_BASE}${PODMD_CPAN_DL}" || return $?$( + echo "E: Unable to download perl module $PODMD_MOD" >&2) + perl_podmd_test; return $? +} + + +function perl_podmd_convert () { + perl -M"$PODMD_MOD" -e "$PODMD_MOD"'->new->filter(@ARGV)' "$@"; return $? +} + + +function pod2markdown () { + local SRC_FN="$1"; shift + local DEST_FN="$1"; shift + [ -n "$DEST_FN" ] || DEST_FN="${SRC_FN%.pod}.md" + + if [ -z "$PODMD_MOD" ]; then + sed -nrf "$SELFPATH/pod2md.sed" "$SRC_FN" >"$DEST_FN" || return $? + return 0 + fi + + perl_podmd_convert "$SRC_FN" >"$DEST_FN" || return $? + sed -nrf perl-podmd-optim.sed -i "$DEST_FN" || return $? + return 0 +} + + + + + + + + + + + + + + + + + + + +upd_npm_pkg_meta "$@"; exit $?