Documentation update and minor refactoring.

Author: sambitdash

docs/src/index.md

@@ -67,6 +67,19 @@ pdPageIsEmpty
 pdPageGetCosObject
 pdPageGetContentObjects
 ```
+## PDF Page objects
+```@docs
+PDPageObject
+PDPageElement
+PDPageObjectGroup
+PDPageTextObject
+PDPageTextRun
+PDPageMarkedContent
+PDPageInlineImage
+PDPage_BeginGroup
+PDPage_EndGroup
+```
+
 # Cos
 ```@docs
 CosDoc

src/CDObject.jl

@@ -10,7 +10,7 @@ string types without having any encoding associated for semantic representation.
 Determination of encoding is carried out mostly by associated fonts and character maps in
 the content stream. There are also strings used in descriptions and other attributes of a
 PDF file where no font or mapping information is provided. This represents the string type
-in such situations. Typically, strings in PDFs are 3 types.
+in such situations. Typically, strings in PDFs are of 3 types.
 
 1. Text string
     a. PDDocEncoded string - Similar to ISO_8859-1

src/CosDoc.jl

@@ -19,7 +19,7 @@ physical file structure of the PDF document. To be used for accessing PDF intern
 from document structure when no direct API is available.
 
 One can access any aspect of PDF using the COS level APIs alone. However, they may require
-you to know the PDF specification in details and not the most intuititive.
+you to know the PDF specification in details and they are not the most intuititive.
 """
 abstract type CosDoc end
 
@@ -50,7 +50,8 @@ end
 ```
     show(io::IO, doc::CosDoc)
 ```
-Prints the CosDoc. The intent is to print lesser information from the structure.
+Prints the CosDoc. The intent is to print lesser information from the structure as default
+can be overwhelming flooding the REPL.
 """
 function show(io::IO, doc::CosDoc)
     print(io, "\nCosDoc ==>\n")
@@ -71,7 +72,7 @@ end
 ```
 Reclaims all system resources consumed by the `CosDoc`. The `CosDoc` should not be used
 after this method is called. `cosDocClose` only needs to be explicitly called if you have
-opened the document by'cosDocOpen'. Documents opened with `pdDocOpen` do not need to use
+opened the document by 'cosDocOpen'. Documents opened with `pdDocOpen` do not need to use
 this method.
 """
 function cosDocClose(doc::CosDocImpl)
@@ -105,8 +106,8 @@ end
     cosDocGetRoot(doc::CosDoc) -> CosDoc
 ```
 The structural starting point of a PDF document. Also known as document root dictionary.
-This provides details object locations and document access methodology. This should not be
-confused with the `catalog` object of the PDF document.
+This provides details of object locations and document access methodology. This should not
+be confused with the `catalog` object of the PDF document.
 """
 cosDocGetRoot(doc::CosDoc) = CosNull
 
@@ -121,7 +122,7 @@ access to the direct object after searching for the object in the document struc
 indirect object reference is passed as an `obj` parameter the complete `indirect object`
 (reference as well as all content of the object) are returned. A `direct object` passed to
 the method is returned as is without any translation. This ensures the user does not have
-to go through type check of the objects before accessing the contents.
+to go through checking the type of the objects before accessing the contents.
 """
 cosDocGetObject(doc::CosDoc, obj::CosObject) = CosNull
 
@@ -451,7 +452,7 @@ cosDocGetPageNumbers(doc::CosDoc, catalog::CosObject, label::AbstractString) ->
 ```
 PDF utilizes two pagination schemes. An internal global page number that is maintained
 serially as an integer and `PageLabel` that is shown by the viewers. Given a `label` this
-method returns a `range` of valid page numbers for the given label.
+method returns a `range` of valid page numbers.
 """
 function cosDocGetPageNumbers(doc::CosDoc, catalog::CosObject, label::AbstractString)
     ref = get(catalog, cn"PageLabels")

src/CosObject.jl

@@ -41,6 +41,8 @@ abstract type CosObject end
 ```
     CosString
 ```
+Abstract type that represents a PDF string. In PDF objects are mere byte representations.
+They translate to actual text strings by application of fonts and associated encodings.
 """
 abstract type CosString <: CosObject end
 
@@ -49,13 +51,16 @@ abstract type CosString <: CosObject end
 ```
     CosNumeric
 ```
+Abstract type for numeric objects. The objects can be an integer [`CosInt`](@ref) or float
+[`CosFloat`](@ref).
 """
 abstract type CosNumeric <: CosObject end
 
 """
 ```
     CosBoolean
 ```
+A boolean object in PDF which is either a `CosTrue` or `CosFalse`
 """
 struct CosBoolean <: CosObject
     val::Bool
@@ -70,22 +75,25 @@ struct CosNullType <: CosObject end
 ```
     CosNull
 ```
+PDF representation of a `null` object. Can be applied to [`CosObject`](@ref) of any type.
 """
 const CosNull=CosNullType()
 
 """
 ```
     CosFloat
 ```
+A numeric float data type.
 """
 struct CosFloat <: CosNumeric
     val::Float64
 end
 
 """
 ```
-    CosFloat
+    CosInt
 ```
+An integer in PDF document.
 """
 struct CosInt <: CosNumeric
     val::Int
@@ -116,6 +124,7 @@ get(o::CosIndirectObject) = get(o.obj)
 ```
     CosName
 ```
+Name objects are symbols used in PDF documents.
 """
 struct CosName <: CosObject
     val::Symbol
@@ -124,8 +133,9 @@ end
 
 """
 ```
-    @cn_str
+    @cn_str(str) -> CosName
 ```
+A string decorator for easier instantiation of a [`CosName`](@ref)
 """
 macro cn_str(str)
     return CosName(str)
@@ -135,6 +145,8 @@ end
 ```
     CosXString
 ```
+Concrete representation of a [`CosString`](@ref) object. The underlying data is represented
+as hexadecimal characters in ASCII.
 """
 struct CosXString <: CosString
   val::Vector{UInt8}
@@ -145,6 +157,8 @@ end
 ```
     CosLiteralString
 ```
+Concrete representation of a [`CosString`](@ref) object. The underlying data is represented
+by byte representations without any encoding.
 """
 struct CosLiteralString <: CosString
     val::Vector{UInt8}
@@ -157,55 +171,84 @@ CosLiteralString(str::AbstractString)=CosLiteralString(transcode(UInt8,str))
 ```
     CosArray
 ```
+An array in a PDF file. The objects can be any combination of [`CosObject`](@ref).
 """
 mutable struct CosArray <: CosObject
-    val::Array{CosObject,1}
-    function CosArray(arr::Array{T,1} where {T<:CosObject})
-      val = Array{CosObject,1}()
+    val::Vector{CosObject}
+    function CosArray(arr::Vector{T} where {T<:CosObject})
+      val = Vector{CosObject}()
       for v in arr
         push!(val,v)
       end
       new(val)
     end
-    CosArray()=new(Array{CosObject,1}())
+    CosArray()=new(Vector{CosObject}())
 end
 
-get(o::CosArray, isNative=false)=isNative ? map((x)->get(x),o.val) : o.val
+"""
+```
+    get(o::CosArray, isNative=false) -> Vector{CosObject}
+```
+An array in a PDF file. The objects can be any combination of [`CosObject`](@ref).
+
+`isNative = true` will return the underlying native object inside the `CosArray` by
+invoking get method on it.
+"""
+get(o::CosArray, isNative=false) = isNative ? map((x)->get(x),o.val) : o.val
+"""
+```
+    length(o::CosArray) -> Int
+```
+Length of the `CosArray`
+"""
 length(o::CosArray)=length(o.val)
 
 """
 ```
     CosDict
 ```
+Name value pair of a PDF objects. The object is very similar to the `Dict` object. The `key`
+has to be of a [`CosName`](@ref) type.
 """
 mutable struct CosDict <: CosObject
     val::Dict{CosName,CosObject}
     CosDict()=new(Dict{CosName,CosObject}())
 end
 
-get(dict::CosDict, name::CosName)=get(dict.val,name,CosNull)
+"""
+```
+    get(dict::CosDict, name::CosName) -> CosObject
+```
+Returns the value as a [`CosObject`](@ref) for the key `name`
+"""
+get(dict::CosDict, name::CosName) = get(dict.val,name,CosNull)
 
 get(o::CosIndirectObject{CosDict}, name::CosName) = get(o.obj, name)
 
 """
-Set the value to object. If the object is CosNull the key is deleted.
+```
+    set!(dict::CosDict, name::CosName, obj::CosObject) -> CosObject
+```
+Sets the value on a dictionary object. Setting a `CosNull` object deletes the object from
+the dictionary. 
 """
 function set!(dict::CosDict, name::CosName, obj::CosObject)
-  if (obj === CosNull)
-    return delete!(dict.val,name)
-  else
-    dict.val[name] = obj
+    if (obj === CosNull)
+        delete!(dict.val,name)
+    else
+        dict.val[name] = obj
+    end
     return dict
-  end
 end
 
-set!(o::CosIndirectObject{CosDict}, name::CosName, obj::CosObject) =
-            set!(o.obj, name, obj)
+set!(o::CosIndirectObject{CosDict}, name::CosName, obj::CosObject) = set!(o.obj, name, obj)
 
 """
 ```
     CosStream
 ```
+A stream object in a PDF. Stream objects have an `extends` disctionary, followed by binary
+data.
 """
 mutable struct CosStream <: CosObject
     extent::CosDict

src/CosObjectHelpers.jl

@@ -9,7 +9,7 @@ function convert(::Type{CDTextString}, xstr::CosXString)
     const FEFF = [LATIN_UPPER_F, LATIN_UPPER_E, LATIN_UPPER_F, LATIN_UPPER_F]
     prefix = xstr.val[1:4]
     hasPrefix = (prefix == feff || prefix == FEFF)
-    isUTF16   = hasPrefix || prefix[1:2] == UInt8[0x00, 0x00]
+    isUTF16   = hasPrefix || prefix[1:2] == UInt8[0x30, 0x30]
     data = xstr.val
     buffer = data |> String |> hex2bytes
     if isUTF16

src/PDDoc.jl

@@ -15,7 +15,7 @@ using ..Common
 ```
     PDDoc
 ```
-A in memory representation of a PDF document. Once created this type has to be used to
+An in memory representation of a PDF document. Once created this type has to be used to
 access a PDF document.
 """
 abstract type PDDoc end
@@ -61,7 +61,7 @@ end
     pdDocGetCatalog(doc::PDDoc) -> CosObject
 ```
 `Catalog` is considered the topmost level object in  PDF document that is subsequently
-used to traverse and extract information on a PDF document. To be used for accessing PDF
+used to traverse and extract information from a PDF document. To be used for accessing PDF
 internal objects from document structure when no direct API is available.
 """
 function pdDocGetCatalog(doc::PDDoc)
@@ -78,15 +78,15 @@ physical file structure of the PDF document. To be used for accessing PDF intern
 from document structure when no direct API is available.
 
 One can access any aspect of PDF using the COS level APIs alone. However, they may require
-you to know the PDF specification in details and not the most intuititive.
+you to know the PDF specification in details and it is not the most intuititive.
 """
 pdDocGetCosDoc(doc::PDDoc)= doc.cosDoc
 
 """
 ```
     pdDocGetPage(doc::PDDoc, num::Int) -> PDPage
 ```
-Given a document absolute page number provides the associated page.
+Given a document absolute page number, provides the associated page object.
 """
 function pdDocGetPage(doc::PDDoc, num::Int)
   cosobj = find_page_from_treenode(doc.pages, num)
@@ -118,9 +118,11 @@ end
     pdDocGetInfo(doc::PDDoc) -> Dict
 ```
 Given a PDF document provides the document information available in the `DocumentInfo`
-disctionary. The information typically includes _creation date, modification date, author,
-creator_ used etc. However, information content are not all mandatory and all information
-may not be available in a document. Please refer to the PDF specification for details.
+dictionary. The information typically includes *creation date, modification date, author,
+creator* used etc. However, all information content are not mandatory. Hence, all
+information needed may not be available in a document.
+
+Please refer to the PDF specification for further details.
 """
 function pdDocGetInfo(doc::PDDoc)
     ref = get(doc.cosDoc.trailer[1], CosName("Info"))
@@ -140,8 +142,10 @@ end
 ```
 Some information in PDF is stored as name and value pairs not essentially a dictionary.
 They are all aggregated and can be accessed from one `names` dictionary object in the
-document catalog. This method provides access to such dictionary in a PDF file. Not all PDF
+document catalog. This method provides access to such values in a PDF file. Not all PDF
 document may have a names dictionary. In such cases, a `CosNull` object may be returned.
+
+Please refer to the PDF specification for further details.
 """
 function pdDocGetNamesDict(doc::PDDoc)
     catalog = pdDocGetCatalog(doc)

src/PDFIO.jl

@@ -30,7 +30,15 @@ export  PDDoc,
             pdPageIsEmpty,
             pdPageGetCosObject,
             pdPageGetContentObjects,
-            pdPageExtractText
+            pdPageExtractText,
+        PDPageObject,
+            PDPageObjectGroup,
+                PDPage_BeginGroup, PDPage_EndGroup,
+            PDPageTextObject,
+            PDPageMarkedContent,
+            PDPageElement,
+                PDPageTextRun,
+            PDPageInlineImage
 
 using .Cos
 export  CosDoc,

src/PDPage.jl

@@ -23,6 +23,8 @@ pdPageGetCosObject(page::PDPage) = page.cospage
 ```
 Page rendering objects are normally stored in a `CosStream` object in a PDF file. This
 method provides access to the stream object.
+
+Please refer to the PDF specification for further details.
 """
 function pdPageGetContents(page::PDPage)
     if (page.contents === CosNull)
@@ -46,9 +48,8 @@ end
 ```
     pdPageGetContentObjects(page::PDPage) -> CosObject
 ```
-A page object can have multiple associated content objects. This method will return a
-`CosArray` if there are multiple of content objects associated. Otherwise an indirect
-object of `CosStream` type will be returned.
+Page rendering objects are normally stored in a `CosStream` object in a PDF file. This
+method provides access to the stream object.
 """
 function pdPageGetContentObjects(page::PDPage)
     if (isnull(page.content_objects))