#
# Copyright (C) 2012 The Android Open Source Project
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
A set of helpers for rendering Mako templates with a Metadata model.
"""
import metadata_model
import re
import markdown
import textwrap
import sys
import bs4
# Monkey-patch BS4. WBR element must not have an end tag.
bs4.builder.HTMLTreeBuilder.empty_element_tags.add("wbr")
from collections import OrderedDict
# Relative path from HTML file to the base directory used by <img> tags
IMAGE_SRC_METADATA="images/camera2/metadata/"
# Prepend this path to each <img src="foo"> in javadocs
JAVADOC_IMAGE_SRC_METADATA="../../../../" + IMAGE_SRC_METADATA
NDKDOC_IMAGE_SRC_METADATA="../" + IMAGE_SRC_METADATA
_context_buf = None
def _is_sec_or_ins(x):
return isinstance(x, metadata_model.Section) or \
isinstance(x, metadata_model.InnerNamespace)
##
## Metadata Helpers
##
def find_all_sections(root):
"""
Find all descendants that are Section or InnerNamespace instances.
Args:
root: a Metadata instance
Returns:
A list of Section/InnerNamespace instances
Remarks:
These are known as "sections" in the generated C code.
"""
return root.find_all(_is_sec_or_ins)
def find_parent_section(entry):
"""
Find the closest ancestor that is either a Section or InnerNamespace.
Args:
entry: an Entry or Clone node
Returns:
An instance of Section or InnerNamespace
"""
return entry.find_parent_first(_is_sec_or_ins)
# find uniquely named entries (w/o recursing through inner namespaces)
def find_unique_entries(node):
"""
Find all uniquely named entries, without recursing through inner namespaces.
Args:
node: a Section or InnerNamespace instance
Yields:
A sequence of MergedEntry nodes representing an entry
Remarks:
This collapses multiple entries with the same fully qualified name into
one entry (e.g. if there are multiple entries in different kinds).
"""
if not isinstance(node, metadata_model.Section) and \
not isinstance(node, metadata_model.InnerNamespace):
raise TypeError("expected node to be a Section or InnerNamespace")
d = OrderedDict()
# remove the 'kinds' from the path between sec and the closest entries
# then search the immediate children of the search path
search_path = isinstance(node, metadata_model.Section) and node.kinds \
or [node]
for i in search_path:
for entry in i.entries:
d[entry.name] = entry
for k,v in d.iteritems():
yield v.merge()
def path_name(node):
"""
Calculate a period-separated string path from the root to this element,
by joining the names of each node and excluding the Metadata/Kind nodes
from the path.
Args:
node: a Node instance
Returns:
A string path
"""
isa = lambda x,y: isinstance(x, y)
fltr = lambda x: not isa(x, metadata_model.Metadata) and \
not isa(x, metadata_model.Kind)
path = node.find_parents(fltr)
path = list(path)
path.reverse()
path.append(node)
return ".".join((i.name for i in path))
def ndk(name):
"""
Return the NDK version of given name, which replace
the leading "android" to "acamera"
Args:
name: name string of an entry
Returns:
A NDK version name string of the input name
"""
name_list = name.split(".")
if name_list[0] == "android":
name_list[0] = "acamera"
return ".".join(name_list)
def protobuf_type(entry):
"""
Return the protocol buffer message type for input metadata entry.
Only support types used by static metadata right now
Returns:
A string of protocol buffer type. Ex: "optional int32" or "repeated RangeInt"
"""
typeName = None
if entry.typedef is None:
typeName = entry.type
else:
typeName = entry.typedef.name
typename_to_protobuftype = {
"rational" : "Rational",
"size" : "Size",
"sizeF" : "SizeF",
"rectangle" : "Rect",
"streamConfigurationMap" : "StreamConfigurations",
"rangeInt" : "RangeInt",
"rangeLong" : "RangeLong",
"colorSpaceTransform" : "ColorSpaceTransform",
"blackLevelPattern" : "BlackLevelPattern",
"byte" : "int32", # protocol buffer don't support byte
"boolean" : "bool",
"float" : "float",
"double" : "double",
"int32" : "int32",
"int64" : "int64",
"enumList" : "int32"
}
if typeName not in typename_to_protobuftype:
print >> sys.stderr,\
" ERROR: Could not find protocol buffer type for {%s} type {%s} typedef {%s}" % \
(entry.name, entry.type, entry.typedef)
proto_type = typename_to_protobuftype[typeName]
prefix = "optional"
if entry.container == 'array':
has_variable_size = False
for size in entry.container_sizes:
try:
size_int = int(size)
except ValueError:
has_variable_size = True
if has_variable_size:
prefix = "repeated"
return "%s %s" %(prefix, proto_type)
def protobuf_name(entry):
"""
Return the protocol buffer field name for input metadata entry
Returns:
A string. Ex: "android_colorCorrection_availableAberrationModes"
"""
return entry.name.replace(".", "_")
def has_descendants_with_enums(node):
"""
Determine whether or not the current node is or has any descendants with an
Enum node.
Args:
node: a Node instance
Returns:
True if it finds an Enum node in the subtree, False otherwise
"""
return bool(node.find_first(lambda x: isinstance(x, metadata_model.Enum)))
def get_children_by_throwing_away_kind(node, member='entries'):
"""
Get the children of this node by compressing the subtree together by removing
the kind and then combining any children nodes with the same name together.
Args:
node: An instance of Section, InnerNamespace, or Kind
Returns:
An iterable over the combined children of the subtree of node,
as if the Kinds never existed.
Remarks:
Not recursive. Call this function repeatedly on each child.
"""
if isinstance(node, metadata_model.Section):
# Note that this makes jump from Section to Kind,
# skipping the Kind entirely in the tree.
node_to_combine = node.combine_kinds_into_single_node()
else:
node_to_combine = node
combined_kind = node_to_combine.combine_children_by_name()
return (i for i in getattr(combined_kind, member))
def get_children_by_filtering_kind(section, kind_name, member='entries'):
"""
Takes a section and yields the children of the merged kind under this section.
Args:
section: An instance of Section
kind_name: A name of the kind, i.e. 'dynamic' or 'static' or 'controls'
Returns:
An iterable over the children of the specified merged kind.
"""
matched_kind = next((i for i in section.merged_kinds if i.name == kind_name), None)
if matched_kind:
return getattr(matched_kind, member)
else:
return ()
##
## Filters
##
# abcDef.xyz -> ABC_DEF_XYZ
def csym(name):
"""
Convert an entry name string into an uppercase C symbol.
Returns:
A string
Example:
csym('abcDef.xyz') == 'ABC_DEF_XYZ'
"""
newstr = name
newstr = "".join([i.isupper() and ("_" + i) or i for i in newstr]).upper()
newstr = newstr.replace(".", "_")
return newstr
# abcDef.xyz -> abc_def_xyz
def csyml(name):
"""
Convert an entry name string into a lowercase C symbol.
Returns:
A string
Example:
csyml('abcDef.xyz') == 'abc_def_xyz'
"""
return csym(name).lower()
# pad with spaces to make string len == size. add new line if too big
def ljust(size, indent=4):
"""
Creates a function that given a string will pad it with spaces to make
the string length == size. Adds a new line if the string was too big.
Args:
size: an integer representing how much spacing should be added
indent: an integer representing the initial indendation level
Returns:
A function that takes a string and returns a string.
Example:
ljust(8)("hello") == 'hello '
Remarks:
Deprecated. Use pad instead since it works for non-first items in a
Mako template.
"""
def inner(what):
newstr = what.ljust(size)
if len(newstr) > size:
return what + "\n" + "".ljust(indent + size)
else:
return newstr
return inner
def _find_new_line():
if _context_buf is None:
raise ValueError("Context buffer was not set")
buf = _context_buf
x = -1 # since the first read is always ''
cur_pos = buf.tell()
while buf.tell() > 0 and buf.read(1) != '\n':
buf.seek(cur_pos - x)
x = x + 1
buf.seek(cur_pos)
return int(x)
# Pad the string until the buffer reaches the desired column.
# If string is too long, insert a new line with 'col' spaces instead
def pad(col):
"""
Create a function that given a string will pad it to the specified column col.
If the string overflows the column, put the string on a new line and pad it.
Args:
col: an integer specifying the column number
Returns:
A function that given a string will produce a padded string.
Example:
pad(8)("hello") == 'hello '
Remarks:
This keeps track of the line written by Mako so far, so it will always
align to the column number correctly.
"""
def inner(what):
wut = int(col)
current_col = _find_new_line()
if len(what) > wut - current_col:
return what + "\n".ljust(col)
else:
return what.ljust(wut - current_col)
return inner
# int32 -> TYPE_INT32, byte -> TYPE_BYTE, etc. note that enum -> TYPE_INT32
def ctype_enum(what):
"""
Generate a camera_metadata_type_t symbol from a type string.
Args:
what: a type string
Returns:
A string representing the camera_metadata_type_t
Example:
ctype_enum('int32') == 'TYPE_INT32'
ctype_enum('int64') == 'TYPE_INT64'
ctype_enum('float') == 'TYPE_FLOAT'
Remarks:
An enum is coerced to a byte since the rest of the camera_metadata
code doesn't support enums directly yet.
"""
return 'TYPE_%s' %(what.upper())
# Calculate a java type name from an entry with a Typedef node
def _jtypedef_type(entry):
typedef = entry.typedef
additional = ''
# Hacky way to deal with arrays. Assume that if we have
# size 'Constant x N' the Constant is part of the Typedef size.
# So something sized just 'Constant', 'Constant1 x Constant2', etc
# is not treated as a real java array.
if entry.container == 'array':
has_variable_size = False
for size in entry.container_sizes:
try:
size_int = int(size)
except ValueError:
has_variable_size = True
if has_variable_size:
additional = '[]'
try:
name = typedef.languages['java']
return "%s%s" %(name, additional)
except KeyError:
return None
# Box if primitive. Otherwise leave unboxed.
def _jtype_box(type_name):
mapping = {
'boolean': 'Boolean',
'byte': 'Byte',
'int': 'Integer',
'float': 'Float',
'double': 'Double',
'long': 'Long'
}
return mapping.get(type_name, type_name)
def jtype_unboxed(entry):
"""
Calculate the Java type from an entry type string, to be used whenever we
need the regular type in Java. It's not boxed, so it can't be used as a
generic type argument when the entry type happens to resolve to a primitive.
Remarks:
Since Java generics cannot be instantiated with primitives, this version
is not applicable in that case. Use jtype_boxed instead for that.
Returns:
The string representing the Java type.
"""
if not isinstance(entry, metadata_model.Entry):
raise ValueError("Expected entry to be an instance of Entry")
metadata_type = entry.type
java_type = None
if entry.typedef:
typedef_name = _jtypedef_type(entry)
if typedef_name:
java_type = typedef_name # already takes into account arrays
if not java_type:
if not java_type and entry.enum and metadata_type == 'byte':
# Always map byte enums to Java ints, unless there's a typedef override
base_type = 'int'
else:
mapping = {
'int32': 'int',
'int64': 'long',
'float': 'float',
'double': 'double',
'byte': 'byte',
'rational': 'Rational'
}
base_type = mapping[metadata_type]
# Convert to array (enums, basic types)
if entry.container == 'array':
additional = '[]'
else:
additional = ''
java_type = '%s%s' %(base_type, additional)
# Now box this sucker.
return java_type
def jtype_boxed(entry):
"""
Calculate the Java type from an entry type string, to be used as a generic
type argument in Java. The type is guaranteed to inherit from Object.
It will only box when absolutely necessary, i.e. int -> Integer[], but
int[] -> int[].
Remarks:
Since Java generics cannot be instantiated with primitives, this version
will use boxed types when absolutely required.
Returns:
The string representing the boxed Java type.
"""
unboxed_type = jtype_unboxed(entry)
return _jtype_box(unboxed_type)
def _is_jtype_generic(entry):
"""
Determine whether or not the Java type represented by the entry type
string and/or typedef is a Java generic.
For example, "Range<Integer>" would be considered a generic, whereas
a "MeteringRectangle" or a plain "Integer" would not be considered a generic.
Args:
entry: An instance of an Entry node
Returns:
True if it's a java generic, False otherwise.
"""
if entry.typedef:
local_typedef = _jtypedef_type(entry)
if local_typedef:
match = re.search(r'<.*>', local_typedef)
return bool(match)
return False
def _jtype_primitive(what):
"""
Calculate the Java type from an entry type string.
Remarks:
Makes a special exception for Rational, since it's a primitive in terms of
the C-library camera_metadata type system.
Returns:
The string representing the primitive type
"""
mapping = {
'int32': 'int',
'int64': 'long',
'float': 'float',
'double': 'double',
'byte': 'byte',
'rational': 'Rational'
}
try:
return mapping[what]
except KeyError as e:
raise ValueError("Can't map '%s' to a primitive, not supported" %what)
def jclass(entry):
"""
Calculate the java Class reference string for an entry.
Args:
entry: an Entry node
Example:
<entry name="some_int" type="int32"/>
<entry name="some_int_array" type="int32" container='array'/>
jclass(some_int) == 'int.class'
jclass(some_int_array) == 'int[].class'
Returns:
The ClassName.class string
"""
return "%s.class" %jtype_unboxed(entry)
def jkey_type_token(entry):
"""
Calculate the java type token compatible with a Key constructor.
This will be the Java Class<T> for non-generic classes, and a
TypeReference<T> for generic classes.
Args:
entry: An entry node
Returns:
The ClassName.class string, or 'new TypeReference<ClassName>() {{ }}' string
"""
if _is_jtype_generic(entry):
return "new TypeReference<%s>() {{ }}" %(jtype_boxed(entry))
else:
return jclass(entry)
def jidentifier(what):
"""
Convert the input string into a valid Java identifier.
Args:
what: any identifier string
Returns:
String with added underscores if necessary.
"""
if re.match("\d", what):
return "_%s" %what
else:
return what
def enum_calculate_value_string(enum_value):
"""
Calculate the value of the enum, even if it does not have one explicitly
defined.
This looks back for the first enum value that has a predefined value and then
applies addition until we get the right value, using C-enum semantics.
Args:
enum_value: an EnumValue node with a valid Enum parent
Example:
<enum>
<value>X</value>
<value id="5">Y</value>
<value>Z</value>
</enum>
enum_calculate_value_string(X) == '0'
enum_calculate_Value_string(Y) == '5'
enum_calculate_value_string(Z) == '6'
Returns:
String that represents the enum value as an integer literal.
"""
enum_value_siblings = list(enum_value.parent.values)
this_index = enum_value_siblings.index(enum_value)
def is_hex_string(instr):
return bool(re.match('0x[a-f0-9]+$', instr, re.IGNORECASE))
base_value = 0
base_offset = 0
emit_as_hex = False
this_id = enum_value_siblings[this_index].id
while this_index != 0 and not this_id:
this_index -= 1
base_offset += 1
this_id = enum_value_siblings[this_index].id
if this_id:
base_value = int(this_id, 0) # guess base
emit_as_hex = is_hex_string(this_id)
if emit_as_hex:
return "0x%X" %(base_value + base_offset)
else:
return "%d" %(base_value + base_offset)
def enumerate_with_last(iterable):
"""
Enumerate a sequence of iterable, while knowing if this element is the last in
the sequence or not.
Args:
iterable: an Iterable of some sequence
Yields:
(element, bool) where the bool is True iff the element is last in the seq.
"""
it = (i for i in iterable)
first = next(it) # OK: raises exception if it is empty
second = first # for when we have only 1 element in iterable
try:
while True:
second = next(it)
# more elements remaining.
yield (first, False)
first = second
except StopIteration:
# last element. no more elements left
yield (second, True)
def pascal_case(what):
"""
Convert the first letter of a string to uppercase, to make the identifier
conform to PascalCase.
If there are dots, remove the dots, and capitalize the letter following
where the dot was. Letters that weren't following dots are left unchanged,
except for the first letter of the string (which is made upper-case).
Args:
what: a string representing some identifier
Returns:
String with first letter capitalized
Example:
pascal_case("helloWorld") == "HelloWorld"
pascal_case("foo") == "Foo"
pascal_case("hello.world") = "HelloWorld"
pascal_case("fooBar.fooBar") = "FooBarFooBar"
"""
return "".join([s[0:1].upper() + s[1:] for s in what.split('.')])
def jkey_identifier(what):
"""
Return a Java identifier from a property name.
Args:
what: a string representing a property name.
Returns:
Java identifier corresponding to the property name. May need to be
prepended with the appropriate Java class name by the caller of this
function. Note that the outer namespace is stripped from the property
name.
Example:
jkey_identifier("android.lens.facing") == "LENS_FACING"
"""
return csym(what[what.find('.') + 1:])
def jenum_value(enum_entry, enum_value):
"""
Calculate the Java name for an integer enum value
Args:
enum: An enum-typed Entry node
value: An EnumValue node for the enum
Returns:
String representing the Java symbol
"""
cname = csym(enum_entry.name)
return cname[cname.find('_') + 1:] + '_' + enum_value.name
def generate_extra_javadoc_detail(entry):
"""
Returns a function to add extra details for an entry into a string for inclusion into
javadoc. Adds information about units, the list of enum values for this key, and the valid
range.
"""
def inner(text):
if entry.units:
text += '\n\n<b>Units</b>: %s\n' % (dedent(entry.units))
if entry.enum and not (entry.typedef and entry.typedef.languages.get('java')):
text += '\n\n<b>Possible values:</b>\n<ul>\n'
for value in entry.enum.values:
if not value.hidden:
text += ' <li>{@link #%s %s}</li>\n' % ( jenum_value(entry, value ), value.name )
text += '</ul>\n'
if entry.range:
if entry.enum and not (entry.typedef and entry.typedef.languages.get('java')):
text += '\n\n<b>Available values for this device:</b><br>\n'
else:
text += '\n\n<b>Range of valid values:</b><br>\n'
text += '%s\n' % (dedent(entry.range))
if entry.hwlevel != 'legacy': # covers any of (None, 'limited', 'full')
text += '\n\n<b>Optional</b> - This value may be {@code null} on some devices.\n'
if entry.hwlevel == 'full':
text += \
'\n<b>Full capability</b> - \n' + \
'Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the\n' + \
'android.info.supportedHardwareLevel key\n'
if entry.hwlevel == 'limited':
text += \
'\n<b>Limited capability</b> - \n' + \
'Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the\n' + \
'android.info.supportedHardwareLevel key\n'
if entry.hwlevel == 'legacy':
text += "\nThis key is available on all devices."
return text
return inner
def javadoc(metadata, indent = 4):
"""
Returns a function to format a markdown syntax text block as a
javadoc comment section, given a set of metadata
Args:
metadata: A Metadata instance, representing the the top-level root
of the metadata for cross-referencing
indent: baseline level of indentation for javadoc block
Returns:
A function that transforms a String text block as follows:
- Indent and * for insertion into a Javadoc comment block
- Trailing whitespace removed
- Entire body rendered via markdown to generate HTML
- All tag names converted to appropriate Javadoc {@link} with @see
for each tag
Example:
"This is a comment for Javadoc\n" +
" with multiple lines, that should be \n" +
" formatted better\n" +
"\n" +
" That covers multiple lines as well\n"
" And references android.control.mode\n"
transforms to
" * <p>This is a comment for Javadoc\n" +
" * with multiple lines, that should be\n" +
" * formatted better</p>\n" +
" * <p>That covers multiple lines as well</p>\n" +
" * and references {@link CaptureRequest#CONTROL_MODE android.control.mode}\n" +
" *\n" +
" * @see CaptureRequest#CONTROL_MODE\n"
"""
def javadoc_formatter(text):
comment_prefix = " " * indent + " * ";
# render with markdown => HTML
javatext = md(text, JAVADOC_IMAGE_SRC_METADATA)
# Identity transform for javadoc links
def javadoc_link_filter(target, shortname):
return '{@link %s %s}' % (target, shortname)
javatext = filter_links(javatext, javadoc_link_filter)
# Crossref tag names
kind_mapping = {
'static': 'CameraCharacteristics',
'dynamic': 'CaptureResult',
'controls': 'CaptureRequest' }
# Convert metadata entry "android.x.y.z" to form
# "{@link CaptureRequest#X_Y_Z android.x.y.z}"
def javadoc_crossref_filter(node):
if node.applied_visibility in ('public', 'java_public'):
return '{@link %s#%s %s}' % (kind_mapping[node.kind],
jkey_identifier(node.name),
node.name)
else:
return node.name
# For each public tag "android.x.y.z" referenced, add a
# "@see CaptureRequest#X_Y_Z"
def javadoc_crossref_see_filter(node_set):
node_set = (x for x in node_set if x.applied_visibility in ('public', 'java_public'))
text = '\n'
for node in node_set:
text = text + '\n@see %s#%s' % (kind_mapping[node.kind],
jkey_identifier(node.name))
return text if text != '\n' else ''
javatext = filter_tags(javatext, metadata, javadoc_crossref_filter, javadoc_crossref_see_filter)
def line_filter(line):
# Indent each line
# Add ' * ' to it for stylistic reasons
# Strip right side of trailing whitespace
return (comment_prefix + line).rstrip()
# Process each line with above filter
javatext = "\n".join(line_filter(i) for i in javatext.split("\n")) + "\n"
return javatext
return javadoc_formatter
def ndkdoc(metadata, indent = 4):
"""
Returns a function to format a markdown syntax text block as a
NDK camera API C/C++ comment section, given a set of metadata
Args:
metadata: A Metadata instance, representing the the top-level root
of the metadata for cross-referencing
indent: baseline level of indentation for comment block
Returns:
A function that transforms a String text block as follows:
- Indent and * for insertion into a comment block
- Trailing whitespace removed
- Entire body rendered via markdown
- All tag names converted to appropriate NDK tag name for each tag
Example:
"This is a comment for NDK\n" +
" with multiple lines, that should be \n" +
" formatted better\n" +
"\n" +
" That covers multiple lines as well\n"
" And references android.control.mode\n"
transforms to
" * This is a comment for NDK\n" +
" * with multiple lines, that should be\n" +
" * formatted better\n" +
" * That covers multiple lines as well\n" +
" * and references ACAMERA_CONTROL_MODE\n" +
" *\n" +
" * @see ACAMERA_CONTROL_MODE\n"
"""
def ndkdoc_formatter(text):
# render with markdown => HTML
ndktext = md(text, NDKDOC_IMAGE_SRC_METADATA, False)
# Convert metadata entry "android.x.y.z" to form
# NDK tag format of "ACAMERA_X_Y_Z"
def ndkdoc_crossref_filter(node):
if node.applied_ndk_visible == 'true':
return csym(ndk(node.name))
else:
return node.name
# For each public tag "android.x.y.z" referenced, add a
# "@see ACAMERA_X_Y_Z"
def ndkdoc_crossref_see_filter(node_set):
node_set = (x for x in node_set if x.applied_ndk_visible == 'true')
text = '\n'
for node in node_set:
text = text + '\n@see %s' % (csym(ndk(node.name)))
return text if text != '\n' else ''
ndktext = filter_tags(ndktext, metadata, ndkdoc_crossref_filter, ndkdoc_crossref_see_filter)
ndktext = ndk_replace_tag_wildcards(ndktext, metadata)
comment_prefix = " " * indent + " * ";
def line_filter(line):
# Indent each line
# Add ' * ' to it for stylistic reasons
# Strip right side of trailing whitespace
return (comment_prefix + line).rstrip()
# Process each line with above filter
ndktext = "\n".join(line_filter(i) for i in ndktext.split("\n")) + "\n"
return ndktext
return ndkdoc_formatter
def dedent(text):
"""
Remove all common indentation from every line but the 0th.
This will avoid getting <code> blocks when rendering text via markdown.
Ignoring the 0th line will also allow the 0th line not to be aligned.
Args:
text: A string of text to dedent.
Returns:
String dedented by above rules.
For example:
assertEquals("bar\nline1\nline2", dedent("bar\n line1\n line2"))
assertEquals("bar\nline1\nline2", dedent(" bar\n line1\n line2"))
assertEquals("bar\n line1\nline2", dedent(" bar\n line1\n line2"))
"""
text = textwrap.dedent(text)
text_lines = text.split('\n')
text_not_first = "\n".join(text_lines[1:])
text_not_first = textwrap.dedent(text_not_first)
text = text_lines[0] + "\n" + text_not_first
return text
def md(text, img_src_prefix="", table_ext=True):
"""
Run text through markdown to produce HTML.
This also removes all common indentation from every line but the 0th.
This will avoid getting <code> blocks in markdown.
Ignoring the 0th line will also allow the 0th line not to be aligned.
Args:
text: A markdown-syntax using block of text to format.
img_src_prefix: An optional string to prepend to each <img src="target"/>
Returns:
String rendered by markdown and other rules applied (see above).
For example, this avoids the following situation:
<!-- Input -->
<!--- can't use dedent directly since 'foo' has no indent -->
<notes>foo
bar
bar
</notes>
<!-- Bad Output -- >
<!-- if no dedent is done generated code looks like -->
<p>foo
<code><pre>
bar
bar</pre></code>
</p>
Instead we get the more natural expected result:
<!-- Good Output -->
<p>foo
bar
bar</p>
"""
text = dedent(text)
# full list of extensions at http://pythonhosted.org/Markdown/extensions/
md_extensions = ['tables'] if table_ext else []# make <table> with ASCII |_| tables
# render with markdown
text = markdown.markdown(text, md_extensions)
# prepend a prefix to each <img src="foo"> -> <img src="${prefix}foo">
text = re.sub(r'src="([^"]*)"', 'src="' + img_src_prefix + r'\1"', text)
return text
def filter_tags(text, metadata, filter_function, summary_function = None):
"""
Find all references to tags in the form outer_namespace.xxx.yyy[.zzz] in
the provided text, and pass them through filter_function and summary_function.
Used to linkify entry names in HMTL, javadoc output.
Args:
text: A string representing a block of text destined for output
metadata: A Metadata instance, the root of the metadata properties tree
filter_function: A Node->string function to apply to each node
when found in text; the string returned replaces the tag name in text.
summary_function: A Node list->string function that is provided the list of
unique tag nodes found in text, and which must return a string that is
then appended to the end of the text. The list is sorted alphabetically
by node name.
"""
tag_set = set()
def name_match(name):
return lambda node: node.name == name
# Match outer_namespace.x.y or outer_namespace.x.y.z, making sure
# to grab .z and not just outer_namespace.x.y. (sloppy, but since we
# check for validity, a few false positives don't hurt).
# Try to ignore items of the form {@link <outer_namespace>...
for outer_namespace in metadata.outer_namespaces:
tag_match = r"(?<!\{@link\s)" + outer_namespace.name + \
r"\.([a-zA-Z0-9\n]+)\.([a-zA-Z0-9\n]+)(\.[a-zA-Z0-9\n]+)?([/]?)"
def filter_sub(match):
whole_match = match.group(0)
section1 = match.group(1)
section2 = match.group(2)
section3 = match.group(3)
end_slash = match.group(4)
# Don't linkify things ending in slash (urls, for example)
if end_slash:
return whole_match
candidate = ""
# First try a two-level match
candidate2 = "%s.%s.%s" % (outer_namespace.name, section1, section2)
got_two_level = False
node = metadata.find_first(name_match(candidate2.replace('\n','')))
if not node and '\n' in section2:
# Linefeeds are ambiguous - was the intent to add a space,
# or continue a lengthy name? Try the former now.
candidate2b = "%s.%s.%s" % (outer_namespace.name, section1, section2[:section2.find('\n')])
node = metadata.find_first(name_match(candidate2b))
if node:
candidate2 = candidate2b
if node:
# Have two-level match
got_two_level = True
candidate = candidate2
elif section3:
# Try three-level match
candidate3 = "%s%s" % (candidate2, section3)
node = metadata.find_first(name_match(candidate3.replace('\n','')))
if not node and '\n' in section3:
# Linefeeds are ambiguous - was the intent to add a space,
# or continue a lengthy name? Try the former now.
candidate3b = "%s%s" % (candidate2, section3[:section3.find('\n')])
node = metadata.find_first(name_match(candidate3b))
if node:
candidate3 = candidate3b
if node:
# Have 3-level match
candidate = candidate3
# Replace match with crossref or complain if a likely match couldn't be matched
if node:
tag_set.add(node)
return whole_match.replace(candidate,filter_function(node))
else:
print >> sys.stderr,\
" WARNING: Could not crossref likely reference {%s}" % (match.group(0))
return whole_match
text = re.sub(tag_match, filter_sub, text)
if summary_function is not None:
return text + summary_function(sorted(tag_set, key=lambda x: x.name))
else:
return text
def ndk_replace_tag_wildcards(text, metadata):
"""
Find all references to tags in the form android.xxx.* or android.xxx.yyy.*
in the provided text, and replace them by NDK format of "ACAMERA_XXX_*" or
"ACAMERA_XXX_YYY_*"
Args:
text: A string representing a block of text destined for output
metadata: A Metadata instance, the root of the metadata properties tree
"""
tag_match = r"android\.([a-zA-Z0-9\n]+)\.\*"
tag_match_2 = r"android\.([a-zA-Z0-9\n]+)\.([a-zA-Z0-9\n]+)\*"
def filter_sub(match):
return "ACAMERA_" + match.group(1).upper() + "_*"
def filter_sub_2(match):
return "ACAMERA_" + match.group(1).upper() + match.group(2).upper() + "_*"
text = re.sub(tag_match, filter_sub, text)
text = re.sub(tag_match_2, filter_sub_2, text)
return text
def filter_links(text, filter_function, summary_function = None):
"""
Find all references to tags in the form {@link xxx#yyy [zzz]} in the
provided text, and pass them through filter_function and
summary_function.
Used to linkify documentation cross-references in HMTL, javadoc output.
Args:
text: A string representing a block of text destined for output
metadata: A Metadata instance, the root of the metadata properties tree
filter_function: A (string, string)->string function to apply to each 'xxx#yyy',
zzz pair when found in text; the string returned replaces the tag name in text.
summary_function: A string list->string function that is provided the list of
unique targets found in text, and which must return a string that is
then appended to the end of the text. The list is sorted alphabetically
by node name.
"""
target_set = set()
def name_match(name):
return lambda node: node.name == name
tag_match = r"\{@link\s+([^\s\}]+)([^\}]*)\}"
def filter_sub(match):
whole_match = match.group(0)
target = match.group(1)
shortname = match.group(2).strip()
#print "Found link '%s' as '%s' -> '%s'" % (target, shortname, filter_function(target, shortname))
# Replace match with crossref
target_set.add(target)
return filter_function(target, shortname)
text = re.sub(tag_match, filter_sub, text)
if summary_function is not None:
return text + summary_function(sorted(target_set))
else:
return text
def any_visible(section, kind_name, visibilities):
"""
Determine if entries in this section have an applied visibility that's in
the list of given visibilities.
Args:
section: A section of metadata
kind_name: A name of the kind, i.e. 'dynamic' or 'static' or 'controls'
visibilities: An iterable of visibilities to match against
Returns:
True if the section has any entries with any of the given visibilities. False otherwise.
"""
for inner_namespace in get_children_by_filtering_kind(section, kind_name,
'namespaces'):
if any(filter_visibility(inner_namespace.merged_entries, visibilities)):
return True
return any(filter_visibility(get_children_by_filtering_kind(section, kind_name,
'merged_entries'),
visibilities))
def filter_visibility(entries, visibilities):
"""
Remove entries whose applied visibility is not in the supplied visibilities.
Args:
entries: An iterable of Entry nodes
visibilities: An iterable of visibilities to filter against
Yields:
An iterable of Entry nodes
"""
return (e for e in entries if e.applied_visibility in visibilities)
def remove_synthetic(entries):
"""
Filter the given entries by removing those that are synthetic.
Args:
entries: An iterable of Entry nodes
Yields:
An iterable of Entry nodes
"""
return (e for e in entries if not e.synthetic)
def filter_ndk_visible(entries):
"""
Filter the given entries by removing those that are not NDK visible.
Args:
entries: An iterable of Entry nodes
Yields:
An iterable of Entry nodes
"""
return (e for e in entries if e.applied_ndk_visible == 'true')
def wbr(text):
"""
Insert word break hints for the browser in the form of <wbr> HTML tags.
Word breaks are inserted inside an HTML node only, so the nodes themselves
will not be changed. Attributes are also left unchanged.
The following rules apply to insert word breaks:
- For characters in [ '.', '/', '_' ]
- For uppercase letters inside a multi-word X.Y.Z (at least 3 parts)
Args:
text: A string of text containing HTML content.
Returns:
A string with <wbr> inserted by the above rules.
"""
SPLIT_CHARS_LIST = ['.', '_', '/']
SPLIT_CHARS = r'([.|/|_/,]+)' # split by these characters
CAP_LETTER_MIN = 3 # at least 3 components split by above chars, i.e. x.y.z
def wbr_filter(text):
new_txt = text
# for johnyOrange.appleCider.redGuardian also insert wbr before the caps
# => johny<wbr>Orange.apple<wbr>Cider.red<wbr>Guardian
for words in text.split(" "):
for char in SPLIT_CHARS_LIST:
# match at least x.y.z, don't match x or x.y
if len(words.split(char)) >= CAP_LETTER_MIN:
new_word = re.sub(r"([a-z])([A-Z])", r"\1<wbr>\2", words)
new_txt = new_txt.replace(words, new_word)
# e.g. X/Y/Z -> X/<wbr>Y/<wbr>/Z. also for X.Y.Z, X_Y_Z.
new_txt = re.sub(SPLIT_CHARS, r"\1<wbr>", new_txt)
return new_txt
# Do not mangle HTML when doing the replace by using BeatifulSoup
# - Use the 'html.parser' to avoid inserting <html><body> when decoding
soup = bs4.BeautifulSoup(text, features='html.parser')
wbr_tag = lambda: soup.new_tag('wbr') # must generate new tag every time
for navigable_string in soup.findAll(text=True):
parent = navigable_string.parent
# Insert each '$text<wbr>$foo' before the old '$text$foo'
split_by_wbr_list = wbr_filter(navigable_string).split("<wbr>")
for (split_string, last) in enumerate_with_last(split_by_wbr_list):
navigable_string.insert_before(split_string)
if not last:
# Note that 'insert' will move existing tags to this spot
# so make a new tag instead
navigable_string.insert_before(wbr_tag())
# Remove the old unmodified text
navigable_string.extract()
return soup.decode()