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 ¶
- Variables
- func ExpandPath(path string) string
- func IsRoot(apath string) bool
- func IsWebRoot(apath string) bool
- func JoinPath(segments []string, root string) string
- func PartitionPath(path string, webPath bool) (pathSegments []string, root string, posixPath string)
- func Posixfy(path string) string
- func ReadAsset(path string, warnOnFailure bool) string
- func TestPathResolver(t *testing.T)
- func WebPath(target, start string) string
- type AbstractNodable
- type ApplyNormalSubsable
- type AttributeListMaker
- type AttributeListable
- type Convertable
- type Document
- func (d *Document) IsMonitored() bool
- func (d *Document) LoadRenderTime() (loadRenderTime int, err error)
- func (d *Document) LoadTime() (loadTime int, err error)
- func (d *Document) Monitor() *Document
- func (d *Document) ParseTime() (parseTime int, err error)
- func (d *Document) ReadTime() (readTime int, err error)
- func (d *Document) RenderTime() (renderTime int, err error)
- func (d *Document) TotalTime() (totalTime int, err error)
- func (d *Document) WriteTime() (writeTime int, err error)
- type Documentable
- type Extensionables
- type Footnotable
- type GlobalParsable
- type InlineMacroable
- type InlineMaker
- type NotMonitoredError
- type OptionsInline
- type OptionsParseAttributes
- func (opa *OptionsParseAttributes) AttributeMissing() string
- func (opa *OptionsParseAttributes) Into() map[string]interface{}
- func (opa *OptionsParseAttributes) SetSubResult(aSubResult bool)
- func (opa *OptionsParseAttributes) SubInput() bool
- func (opa *OptionsParseAttributes) SubResult() bool
- func (opa *OptionsParseAttributes) UnescapeInput() bool
- type PathResolver
- type Referencable
- type Renderer
- type SubstDocumentable
Constants ¶
This section is empty.
Variables ¶
var EncodeUriCharsRx, _ = regexp.Compile(`[\^\-!~*';:@=+$,()\[\]]`)
REGEXP_ENCODE_URI_CHARS = /[^\w\-.!~*';:@=+$,()\[\]]/ BUG? doesn't work with the ^\w...
var PASS_MATCHRx, _ = regexp.Compile("\u0096" + `(\d+)` + "\u0097")
Functions ¶
func ExpandPath ¶
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 ¶
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 ¶
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 ¶
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 ¶
Normalize path by converting any backslashes to forward slashes Returns a String path with any backslashes replaced with forward slashes
func ReadAsset ¶
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 WebPath ¶
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 AttributeListMaker ¶
type AttributeListMaker interface {
NewAttributeList(attrline string, block ApplyNormalSubsable, delimiter string) AttributeListable
}
type AttributeListable ¶
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 ¶
Accepts input as an IO. If the input is a File, information about the file is stored in attributes on the Document object.
func LoadStrings ¶
Accepts input as an array of strings
func NewDocument ¶
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 ¶
Check if a Document is supposed to be monitored
func (*Document) LoadRenderTime ¶
LoadRender means Load plus Render times Error if document didn't activated the monitoring
func (*Document) LoadTime ¶
Load means Read plus Parse times Error if document didn't activated the monitoring
func (*Document) Monitor ¶
Setup a monitor for the document (or does nothing if the monitor already exists). Returns self, for easy composition
func (*Document) ParseTime ¶
Time to parse the document once read from IO source Error if document didn't activated the monitoring
func (*Document) ReadTime ¶
Time to read the document from IO source Error if document didn't activated the monitoring
func (*Document) RenderTime ¶
Time to render the document once loaded 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 GlobalParsable ¶
type GlobalParsable interface {
// contains filtered or unexported methods
}
type InlineMacroable ¶
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 Renderer ¶
type Renderer struct{}
Methods for rendering Asciidoc Documents, Sections, and Blocks
using <del>eRuby</del> Go templates
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 ¶
Directories ¶
Path | Synopsis |
---|---|
consts
|
|
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 |