asciidocgo

package module
v0.0.0-...-e150718 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2014 License: MIT Imports: 23 Imported by: 0

README 

asciidocgo
==========

[quote]
An Asciidoctor clone in Go. Very early stages.

image:http://img.shields.io/travis/ciarand/asciidocgo.svg?style=flat[
    "Build status", link=https://travis-ci.org/ciarand/asciidocgo]

Goals
-----
- Asciidoctor compatability

- Blackfriday-like API (drop-in replacement ideally)

- 100% test coverage

Contributing
------------
- We mostly need documentation right now

- Let's move everything to the root level

- A CLI tool is almost literally the last thing we need to work on right now

Code style
----------
- Don't break the tests

- Format with gofmt

- Use Ginkgo for tests

- Comment every new function or struct you add

- Never use `panic` in reachable code

- Use `snake_case` for filenames, camel case for symbols

- Run the tests before (and after) you commit

Documentation

Overview

Asciidocgo implements an AsciiDoc renderer in Go.

Methods for parsing Asciidoc input files and rendering documents using eRuby templates.

Asciidoc documents comprise a header followed by zero or more sections. Sections are composed of blocks of content. For example: 

= Doc Title

== Section 1

This is a paragraph block in the first section.

== Section 2

This section has a paragraph block and an olist block.

. Item 1
. Item 2

Examples:

Use built-in templates: 

lines = File.readlines("your_file.asc")
doc = Asciidoctor::Document.new(lines)
html = doc.render
File.open("your_file.html", "w+") do |file|
  file.puts html
end

Use custom (Tilt-supported) templates: 

lines = File.readlines("your_file.asc")
doc = Asciidoctor::Document.new(lines, :template_dir => 'templates')
html = doc.render
File.open("your_file.html", "w+") do |file|
  file.puts html
end

Index

Constants

This section is empty.

Variables

View Source 
var EncodeUriCharsRx, _ = regexp.Compile(`[\^\-!~*';:@=+$,()\[\]]`)

REGEXP_ENCODE_URI_CHARS = /[^\w\-.!~*';:@=+$,()\[\]]/ BUG? doesn't work with the ^\w...

View Source 
var PASS_MATCHRx, _ = regexp.Compile("\u0096" + `(\d+)` + "\u0097")

Functions

func ExpandPath 

func ExpandPath(path string) string
Expand the path by resolving any parent references (..)

and cleaning self references (.). The result will be relative if the path is relative and absolute if the path is absolute. The file separator used in the expanded path is the one specified when the class was constructed. path - the String path to expand returns a String path with any parent or self references resolved.

func IsRoot 

func IsRoot(apath string) bool

Check if the specified path is an absolute root path his operation correctly handles both posix and windows paths. returns a Boolean indicating whether the path is an absolute root path

func IsWebRoot 

func IsWebRoot(apath string) bool

Determine if the path is an absolute (root) web path. Returns a Boolean indicating whether the path is an absolute (root) web path

func JoinPath 

func JoinPath(segments []string, root string) string
Join the segments using the posix file separator.

Use the root, if specified, to construct an absolute path. Otherwise join the segments as a relative path. segments - a String Array of path segments root - a String path root (optional, default: nil) returns a String path formed by joining the segments using the posix file separator and prepending the root, if specified.

func PartitionPath 

func PartitionPath(path string, webPath bool) (pathSegments []string, root string, posixPath string)

Partition the path into path segments and remove any empty segments or segments that are self references (.). The path is split on either posix or windows file separators. returns a 3-item Array containing the Array of String path segments, the path root, if the path is absolute, and the posix version of the path.

func Posixfy 

func Posixfy(path string) string

Normalize path by converting any backslashes to forward slashes Returns a String path with any backslashes replaced with forward slashes

func ReadAsset 

func ReadAsset(path string, warnOnFailure bool) string
Read the contents of the file at the specified path.

This method assumes that the path is safe to read. It checks that the file is readable before attempting to read it. path - the String path from which to read the contents warn_on_failure - a Boolean that controls whether a warning is issued if 

the file cannot be read

returns the contents of the file at the specified path, or nil if the file does not exist.

func TestPathResolver 

func TestPathResolver(t *testing.T)

func WebPath 

func WebPath(target, start string) string
Resolve a web path from the target and start paths.

The main function of this operation is to resolve any parent references and remove any self references. start - the String start (i.e., parent) path returns a String path that joins the target path with the start path with any parent references resolved and self references removed

Types

type AbstractNodable 

type AbstractNodable interface {
	IsAbstractNodable()
}

type ApplyNormalSubsable 

type ApplyNormalSubsable interface {
	ApplyNormalSubs(lines string) string
}

type AttributeListMaker 

type AttributeListMaker interface {
	NewAttributeList(attrline string, block ApplyNormalSubsable, delimiter string) AttributeListable
}

type AttributeListable 

type AttributeListable interface {
	ParseInto(into map[string]interface{}, posAttrs []string) map[string]interface{}
	Parse(posAttrs []string) map[string]interface{}
}

type Convertable 

type Convertable interface {
	Convert() string
}

type Document 

type Document struct {
	// contains filtered or unexported fields
}

Asciidoc Document, onced loaded from an IO, string or array

func Load 

func Load(input io.Reader) *Document

Accepts input as an IO. If the input is a File, information about the file is stored in attributes on the Document object.

func LoadString 

func LoadString(input string) *Document

Accepts input as a string

func LoadStrings 

func LoadStrings(inputs ...string) *Document

Accepts input as an array of strings

func NewDocument 

func NewDocument(data []string, options map[string]string) *Document

Initialize an Asciidoc object. - data: The Array of Strings holding the Asciidoc source document. (default: []) - options - A Hash of options to control processing, such as setting the safe mode (:safe), suppressing the header/footer (:header_footer) and attribute overrides (:attributes) (default: {})

Examples 

data = File.readlines(filename)
doc  = Asciidoctor::Document.new(data)
puts doc.render

func (*Document) IsMonitored 

func (d *Document) IsMonitored() bool

Check if a Document is supposed to be monitored

func (*Document) LoadRenderTime 

func (d *Document) LoadRenderTime() (loadRenderTime int, err error)

LoadRender means Load plus Render times Error if document didn't activated the monitoring

func (*Document) LoadTime 

func (d *Document) LoadTime() (loadTime int, err error)

Load means Read plus Parse times Error if document didn't activated the monitoring

func (*Document) Monitor 

func (d *Document) Monitor() *Document

Setup a monitor for the document (or does nothing if the monitor already exists). Returns self, for easy composition

func (*Document) ParseTime 

func (d *Document) ParseTime() (parseTime int, err error)

Time to parse the document once read from IO source Error if document didn't activated the monitoring

func (*Document) ReadTime 

func (d *Document) ReadTime() (readTime int, err error)

Time to read the document from IO source Error if document didn't activated the monitoring

func (*Document) RenderTime 

func (d *Document) RenderTime() (renderTime int, err error)

Time to render the document once loaded Error if document didn't activated the monitoring

func (*Document) TotalTime 

func (d *Document) TotalTime() (totalTime int, err error)

Total means LoadRender plus Write times Error if document didn't activated the monitoring

func (*Document) WriteTime 

func (d *Document) WriteTime() (writeTime int, err error)

Time to write the document once rendered Error if document didn't activated the monitoring

type Documentable 

type Documentable interface {
	Document() Documentable
	Attributes() map[string]interface{}
	Attr(name string, defaultValue interface{}, inherit bool) interface{}
	HasAttr(name string, expect interface{}, inherit bool) bool

	HasReftext() bool

	Safe() safemode.SafeMode
	BaseDir() string

	PlaybackAttributes(map[string]interface{})
	Renderer() *Renderer
	CounterIncrement(counterName string, block *abstractNode) string
	Counter(name, seed string) int
	DocType() string
	// contains filtered or unexported methods
}

type Extensionables 

type Extensionables interface {
	HasInlineMacros() bool
	InlineMacros() []InlineMacroable
}

type Footnotable 

type Footnotable interface {
	Index() int
	Id() int
	Text() string
	String() string
}

type GlobalParsable 

type GlobalParsable interface {
	// contains filtered or unexported methods
}

type InlineMacroable 

type InlineMacroable interface {
	IsShortFormat() bool
	IsContentModelAttributes() bool
	Regexp() *regexp.Regexp
	ProcessMethod(self interface{}, target string, attributes map[string]interface{}) string
	PosAttrs() []string
}

type InlineMaker 

type InlineMaker interface {
	NewInline(parent AbstractNodable, c context.Context, text string, opts *OptionsInline) Convertable
}

type NotMonitoredError 

type NotMonitoredError struct {
	// contains filtered or unexported fields
}

Error returned when accessing times on a Document not monitored

func (*NotMonitoredError) Error 

func (e *NotMonitoredError) Error() string

Print description of a non-monitored error

type OptionsInline 

type OptionsInline struct {
	// contains filtered or unexported fields
}

func (*OptionsInline) Attributes 

func (oi *OptionsInline) Attributes() map[string]interface{}

func (*OptionsInline) Target 

func (oi *OptionsInline) Target() string

func (*OptionsInline) TypeInline 

func (oi *OptionsInline) TypeInline() string

func (oi *OptionsInline) Id() string { return oi.id }

type OptionsParseAttributes 

type OptionsParseAttributes struct {
	// contains filtered or unexported fields
}

func (*OptionsParseAttributes) AttributeMissing 

func (opa *OptionsParseAttributes) AttributeMissing() string

func (*OptionsParseAttributes) Into 

func (opa *OptionsParseAttributes) Into() map[string]interface{}

func (*OptionsParseAttributes) SetSubResult 

func (opa *OptionsParseAttributes) SetSubResult(aSubResult bool)

func (*OptionsParseAttributes) SubInput 

func (opa *OptionsParseAttributes) SubInput() bool

func (*OptionsParseAttributes) SubResult 

func (opa *OptionsParseAttributes) SubResult() bool

func (*OptionsParseAttributes) UnescapeInput 

func (opa *OptionsParseAttributes) UnescapeInput() bool

type PathResolver 

type PathResolver struct {
	// contains filtered or unexported fields
}

Handles all operations for resolving, cleaning and joining paths. This class includes operations for handling both web paths (request URIs) and system paths.

The main emphasis of the class is on creating clean and secure paths. Clean paths are void of duplicate parent and current directory references in the path name. Secure paths are paths which are restricted from accessing directories outside of a jail root, if specified.

Since joining two paths can result in an insecure path, this class also handles the task of joining a parent (start) and child (target) path.

This class makes no use of path utilities from the Ruby libraries. Instead, it handles all aspects of path manipulation. The main benefit of internalizing these operations is that the class is able to handle both posix and windows paths independent of the operating system on which it runs. This makes the class both deterministic and easier to test.

Examples: 

resolver = PathResolver.new

Web Paths

resolver.web_path('images')
=> 'images'

resolver.web_path('./images')
=> './images'

resolver.web_path('/images')
=> '/images'

resolver.web_path('./images/../assets/images')
=> './assets/images'

resolver.web_path('/../images')
=> '/images'

resolver.web_path('images', 'assets')
=> 'assets/images'

resolver.web_path('tiger.png', '../assets/images')
=> '../assets/images/tiger.png'

System Paths

resolver.working_dir
=> '/path/to/docs'

resolver.system_path('images')
=> '/path/to/docs/images'

resolver.system_path('../images')
=> '/path/to/images'

resolver.system_path('/etc/images')
=> '/etc/images'

resolver.system_path('images', '/etc')
=> '/etc/images'

resolver.system_path('', '/etc/images')
=> '/etc/images'

resolver.system_path(nil, nil, '/path/to/docs')
=> '/path/to/docs'

resolver.system_path('..', nil, '/path/to/docs')
=> '/path/to/docs'

resolver.system_path('../../../css', nil, '/path/to/docs')
=> '/path/to/docs/css'

resolver.system_path('../../../css', '../../..', '/path/to/docs')
=> '/path/to/docs/css'

resolver.system_path('..', 'C:\\data\\docs\\assets', 'C:\\data\\docs')
=> 'C:/data/docs'

resolver.system_path('..\\..\\css', 'C:\\data\\docs\\assets', 'C:\\data\\docs')
=> 'C:/data/docs/css'

begin
  resolver.system_path('../../../css', '../../..', '/path/to/docs', :recover => false)
rescue SecurityError => e
  puts e.message
end
=> 'path ../../../../../../css refers to location outside jail: /path/to/docs (disallowed in safe mode)'

resolver.system_path('/path/to/docs/images', nil, '/path/to/docs')
=> '/path/to/docs/images'

begin
  resolver.system_path('images', '/etc', '/path/to/docs')
rescue SecurityError => e
  puts e.message
end
=> Start path /etc is outside of jail: /path/to/docs'

func NewPathResolver 

func NewPathResolver(fileSeparator byte, workingDir string) *PathResolver
Construct a new instance of PathResolver, optionally specifying

the file separator (to override the system default) and the working directory (to override the present working directory). The working directory will be expanded to an absolute path inside the constructor. file_separator - the String file separator to use for path operations (optional, default: File::FILE_SEPARATOR) working_dir - the String working directory (optional, default: Dir.pwd)

func (*PathResolver) FileSeparator 

func (pr *PathResolver) FileSeparator() byte

func (*PathResolver) RelativePath 

func (pr *PathResolver) RelativePath(filename, baseDirectory string) string

Calculate the relative path to this absolute filename from the specified base directory. If either the filename or the base_directory are not absolute paths, no work is done. filename - An absolute file name as a String base_directory - An absolute base directory as a String Return the relative path String of the filename calculated from the base directory

func (*PathResolver) SystemPath 

func (pr *PathResolver) SystemPath(target, start, jail string, canrecover bool, targetName string) string

Resolve a system path from the target and start paths. If a jail path is specified, enforce that the resolved directory is contained within the jail path. If a jail path is not provided, the resolved path may be any location on the system. If the resolved path is absolute, use it as is. If the resolved path is relative, resolve it relative to the working_dir specified in the constructor. target - the String target path start - the String start (i.e., parent) path jail - the String jail path to confine the resolved path opts - an optional Hash of options to control processing (default: {}):

  • :recover is used to control whether the processor should auto-recover when an illegal path is encountered
  • :target_name is used in messages to refer to the path being resolved

returns a String path that joins the target path with the start path with any parent references resolved and self references removed and enforces that the resolved path be contained within the jail, if provided

func (*PathResolver) WorkingDir 

func (pr *PathResolver) WorkingDir() string

type Referencable 

type Referencable interface {
	HasId(id string) bool
	Get(id string) string
}

type Renderer 

type Renderer struct{}
Methods for rendering Asciidoc Documents, Sections, and Blocks

using <del>eRuby</del> Go templates

func (*Renderer) Render 

func (r *Renderer) Render(view string, object interface{}, locals []interface{}) string
Render an Asciidoc object with a specified view template.

view - the String view template name. object - the Object to be used as an evaluation scope. locals - the optional Hash of locals to be passed to Tilt (default {}) (also ignored, really)

type SubstDocumentable 

type SubstDocumentable interface {
	Attr(name string, defaultValue interface{}, inherit bool) interface{}
	Basebackend(base interface{}) bool
	SubAttributes(data string, opts *OptionsParseAttributes) string
	Counter(name string, seed int) string
	HasAttr(name string, expect interface{}, inherit bool) bool
	Extensions() Extensionables
	Register(typeDoc string, value []string)
	References() Referencable
	NewFootnote(index int, id int, text string) Footnotable
	RegisterFootnote(f Footnotable)
	FindFootnote(id int) Footnotable
}

Source Files

View all Source files

Directories

Path Synopsis
consts
compliance
contentModel
context
regexps
regexps/quotes
safemode
to check: https://gist.github.com/alphazero/2718939 For now: - http://play.golang.org/p/8o0WywyaDT - http://play.golang.org/p/QFheQeChIn - http://play.golang.org/p/p5Z8X3nxXL <=== All from https://groups.google.com/forum/#!topic/golang-nuts/ct99dtK2Jo4/discussion
 to check: https://gist.github.com/alphazero/2718939 For now: - http://play.golang.org/p/8o0WywyaDT - http://play.golang.org/p/QFheQeChIn - http://play.golang.org/p/p5Z8X3nxXL <=== All from https://groups.google.com/forum/#!topic/golang-nuts/ct99dtK2Jo4/discussion

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.