HomerJax beta 0.5
This is a global shared object for reading and writing data from the
Internet, now available at Script Central. To help you initially
understand its capabilities, I am pasting the current documentation below.
Use the Help button in Script Manager to read the documentation in your
web browser, or to run a demo.
Jamal
HomerJax
Beta 0.5
August 1, 2009
Copyright 2009 by Jamal Mazrui
GNU Lesser General Public License (LGPL)
Contents
Introduction
COM Exchange Format
Dialog Methods
File Methods
Folder Methods
HTML Methods
JScript Data Methods
Path Methods
Regular Expression Methods
Registry Methods
Shell Methods
String Methods
Variant Data Methods
Web Request Methods
XML Methods
Development Notes
----------
Introduction
HomerJax is a library of convenience functions for accessing Internet
resources. It is written in JScript, the Microsoft version of JavaScript,
and is dependent on several COM servers distributed with Windows. The
word "Homer" is a brand name I sometimes use for developer tools I create.
The word "Jax" derives from Ajax, which originally meant "Asynchronous
JavaScript and XML." Ajax technologies focus on building dynamic user
interfaces in web browsers. HomerJax functions use some of these core
technologies, but focus on reading, interpreting, and writing data from
the Internet.
Since the Internet is a great source of accessible information for people
with visual disabilities who cannot readily read the printed word, my hope
is that this library makes it easier for developers, including blind ones
like myself, to build applications that take advantage of new social
networking sites such as Twitter, FaceBook, and many others. I intend for
HomerJax to be accessible via various programming environments, including
the Windows Script Host, screen reader scripting languages, and other
programming languages via a COM server interface.
The functionality and documentation of HomerJax will improve over time in
response to comments, questions, and suggestions. Code contributions are
also welcome.
----------
COM Exchange Format
The Component Object Model (COM) is a set of Windows standards by which
different programming languages and applications can communicate. COM
uses a flexible data type called a variant, which can be an individual
value, array of values, or complex object with methods, properties, and
events. In general, any COM client can use string, numeric, and COM
objects as the data types of parameters or return values. Some, however,
cannot use arrays. COM exchange format is intended to support
collections, as well as primitive data types, for use by any COM client.
Rather than an array, a list COM object is used from the .NET Framework
(any version). A COM object dictionary is also used from the Windows
Script Host.
By convention, HomerJax variable names use lower case prefixes to indicate
the data type: s for string, i for integer, n for floating point number,
l for list, d for dictionary, and o for other COM object. HomerJax
includes various methods for converting between JavaScript Object Notation
(JSON), variant data types, and COM exchange format. This provides much
flexibility for accessing data on the Internet.
----------
Dialog Methods
These are simple, modal dialogs. Parameters supply values that are needed
in reading order of the dialog window, from top to bottom and left to
right. Thus, the window title is the first parameter. DialogShow
displays information; DialogConfirm prompts for confirmation; and
DialogInput prompts for input.
DialogConfirm(sTitle, sMessage, sDefault)
Get choice from a standard Yes, No, or Cancel message box
DialogInput(sTitle, sField, sValue)
Get input from a single edit box
DialogShow(oTitle, oMessage)
Show string version of two parameters in the title and prompt of a message
box
----------
File Methods
These copy, move, delete, or test for existence of files.
FileCopy(sSource, sTarget)
Copy source to destination file, replacing if it exists
FileDelete(sFile)
Delete a file if it exists, && test whether it is subsequently absent
FileExists(sFile)
Test whether File exists
FileGetDate(sFile)
Get date of a file
FileGetSize(sFile)
Get size of a file
FileGetType(sFile)
Get file type
FileMove(sSource, sTarget)
Move source to destination file, replacing if it exists
FileToString(sFile)
Get content of text file
----------
Folder Methods
These copy, move, delete, or test for existence of folders.
FolderCopy(sSource, sTarget)
Copy source to destination Folder, replacing if it exists
FolderCreate(sFolder)
Create folder
FolderDelete(sFolder)
Delete a Folder if it exists, && test whether it is subsequently absent
FolderExists(sFolder)
Test whether folder exists
FolderGetDate(sFolder)
Get date of a Folder
FolderGetSize(sFolder)
Get size of folder, summing the sizes of files && subfolders it contains
FolderMove(sSource, sTarget)
Move source to destination Folder, replacing if it exists
----------
HTML Methods
These get page text, table text, or URLs of HTML.
HtmlEncodeString(sText)
Encode a string for HTML or XML
HtmlGetLinks(sUrl)
Get a list of two-item lists containing the URL and text of a link
HtmlGetUrls(sUrl)
Get a list of URLs linked to a web page
HtmlGetText(sUrl)
Get the text of an HTML page
HtmlGetTableText(sUrl, iTable)
Get the text of an HTML table specified by number, or null for all of them
----------
JScript Data Methods
These convert between JScript and variant data types.
JsDictionaryToEncodedString(d)
Convert dictionary to string with http encoding
JsDictionaryToVt(d)
Convert JScript dictionary to variant
JsInspectObject(sName, oValue)
Report on type of object and its subobjects
JsIsBlank(sText)
Test if string is empty or white space
JsIsMute(o)
test for empty string
JsIsNull(o)
Test for null
JsIsObject(o)
Test for object
JSNumber(o)
Convert to JScript number
JsObjectToVt(oValue)
Convert JScript object to variant
JsPrint(o)
Print to screen using console mode of Windows Script Host
JsPrintObject(sName, oValue)
Print type of object and its subobjects
JsString(o)
Convert to a JScript string
JsToVt(sJs)
Convert string in JavaScript Object Notation to COM exchange format
----------
Path Methods
These parse file or folder paths into their components; get paths of
Windows special folders; or create temporary files.
PathCombine(sFolder, sName)
Combine folder && name to form a valid path
PathCreateTempFolder()
Create temporary folder && return its full path
PathExists(sPath)
Test whether path exists
PathGetBase(sPath)
Get base/root name of a file or folder
PathGetCurrentDirectory()
Get current directory of active process
PathGetExtension(sPath)
Get extention of file || folder
PathGetFolder(sPath)
Get the parent folder of a file or folder
PathGetInternetCacheFolder()
Get Windows folder for temporary Internet files
PathGetLong(sPath)
Get long name of file or folder
PathGetName(sPath)
Get the file or folder name at the end of a path
PathGetShort(sPath)
Get short path (8.3 style) of a file or folder
PathGetSpec(sDir, sWildcards, sFlags)
Get a list of paths, specifying folder, wild card pattern, && sort order
PathGetTempFile()
Get full path of a temporary file
PathGetTempFolder()
Get Windows folder for temporary files
PathGetTempName()
Get Name for temporary file || folder
PathSetCurrentDirectory(sDir)
Set current directory of active process, and return previously current
directory
----------
Regular Expression Methods
These search or extract strings based on regular expressions.
RegExpContains(sText, sMatch, bIgnoreCase)
Get Array containing the starting index and text of the first match of a
regular expression
RegExpContainsLast(sText, sMatch, bIgnoreCase)
Get list containing the starting index and text of the last match of a
regular expression
RegExpCount(sText, sMatch, bIgnoreCase)
Count matches of a regular expression
RegExpExtract(sText, sMatch, bIgnoreCase)
Get list containing matches of a regular expression
RegExpReplace(sText, sMatch, sReplace, bIgnoreCase)
Replace text matching a regular expression
----------
Registry Methods
These read or write strings with the Windows registry (not yet debugged).
RegistryGetString(iRootKey, sSubKey, sValueName)
Get a string from registry
RegistryRead(sKey)
Get a string from the registry
RegistrySetString(iRootKey, sSubKey, sValueName, sValueData)
Set a registry string
RegistryWrite(sKey, sValue)
Write a string to the registry
----------
Shell Methods
These execute programs or open files.
ShellCreateShortcut(sFile, sTargetPath, sWorkingDirectory, iWindowStyle,
sHotkey)
Create a .lnk or .url file
ShellExec(sCommand)
Run a console mode command && return its standard output
ShellExecute(sFile, sParams, sFolder, sVerb, iWindowStyle)
Execute a command with a verb like RunAs
ShellExpandEnvironmentVariables(sText)
Replace environment variables with their values
ShellGetEnvironmentVariable(sVariable)
Get the value of an environment variable
ShellGetShortcutTargetPath(sFile)
Get the target path of a shortcut file
ShellGetSpecialFolder(vFolder)
Get a special Windows folder
ShellInvokeVerb(sPath, sVerb)
Invoke a verb on a file or folder
ShellOpen(sPath)
Open a file or folder with the default program associated with its type
ShellOpenWith(sExe, sParam)
Open a program with a file
ShellRun(sFile, iStyle, bWait)
Launch a program or file, indicating its window style && whether to wait
before returning
ShellRunCommandPrompt(sDir)
Open a command prompt in the directory specified
ShellRunExplorerWindow(sDir)
Open Windows Explorer in the directory specified
ShellWait(sPath)
Run a program and wait for it to return
----------
String Methods
These parse strings or save them to files.
StringAppendToFile(sText, sFile, sDivider)
Append string to File, omitting divider if the first one
StringChopLeft(sText, iCount)
Remove iCount characters from left of sText
StringChopRight(sText, iCount)
Remove iCount characters from Right of sText
StringContains(sText, sMatch, bIgnoreCase)
Test if a string is contained in another
StringConvertToMacLineBreak(sText)
Convert to Macintosh line break, \r
StringConvertToUnixLineBreak(sText)
Convert to Unix line break, \n
StringConvertToWinLineBreak(sText)
Convert to standard Windows line break, \r\n
StringCount(sText, sMatch)
Count occurrences of a string within another string
StringEndsWith(sText, sSuffix, bIgnoreCase)
Test whether first string ends with second one
StringEqual(s1, s2)
Test if two strings are exactly equal
StringEquiv(s1, s2)
Test whether two strings are the same except for capitalization
StringGetASCII(sText)
Get space delimited ASCII codes for characters in string
StringLeft(sText, iCount)
Return leftmost characters of a string
StringLength(s)
Return length of a string
StringPlural(sItem, iCount)
Return singular || plural form of a string, depending on whether count
equals one
StringQuote(sText)
Quote a string
StringReplaceAll(sText, sMatch, sReplace)
Replace all occurences of a string within another
StringRight(sText, iCount)
Return rightmost characters of a string
StringStartsWith(sText, sPrefix, bIgnoreCase)
Test whether first string starts with second one
StringToFile(sText, sFile)
Saves string to text file, replacing if it exists
StringTrim(sText)
Trim white space from both ends of a string
StringUnquote(sText)
Unquote a string
StringWrap(sText, iMaxLine)
var aLines, aWords
var i, j
var sReturn, sLines, sLine, sWords, sWord
aLines = sText.split(vbCrLf)
sReturn = xMute
var iCount = aLines.length
for (var i = 0; i < iCount; i++)
sLine = aLines[i]
if (sLine.length > iMaxLine)
aWords = sLine.split(' ')
sLine = xMute
for (var j = 0; j < aWords.length; j++)
sWord = aWords(j)
if (sLine.length + sWord.length > iMaxLine)
sReturn += StringTrim(sLine) + vbCrLf
sLine = sWord + ' '
}
else
sLine = sLine + sWord + ' '
}
}
}
else
sReturn += RTrim(sLine) + vbCrLf
}
}
return sReturn
} // StringWrap method
----------
Variant Data Methods
These convert between variant and JScript data types.
VtArrayToJs(a)
Convert variant array to JScript
VtArrayToList(a)
Convert variant array to list
VtCreateDictionary()
Return a variant dictionary
VtCreateFileSystemObject()
Return a file system object
VtCreateHtmlFile()
Create a variant HTMLFile object
VtCreateInternetExplorerApplication()
Return an Internet Explorer object
VtCreateList()
Create a variant list object
VtCreateRegExp()
Return a scripting RegExp object
VtCreateShellApplication()
Return a Shell.Application object
VtCreateStream()
Return an ADODB.Stream object
VtCreateVBScriptControl()
Return MSScriptControl.ScriptControl object
VtCreateWebRequest()
Create web request object
VtCreateWScriptShell()
Return WScript.Shell object
VtCreateXmlDocument()
Return an XML document
VtDateToJs(dt)
Convert a variant date to JScript
VtDictionaryToJs(d)
Convert a variant dictionary to JScript
VtDictionaryKeysToJs(d)
Convert variant array of dictionary keys to JScript array
VtDictionaryKeysToList(d)
Convert variant array of dictionary keys to list
VtEvalVBScript(sCode, dParams)
Evaluate VBScript code and return the result
VtEvalVBScriptParam(sCode, vParam)
Evaluate VBScript code and return result, passing single argument
VtGetWMIObject()
Get WMI object
VtInitDictionary(vValue)
Create a variant dictionary and initialize it with a single key/value pair
VtListToJs(l)
Convert variant list to JScript array
VtStreamToFile(aBytes, sFile)
Save a variant byte array to a binary file
VtTypeName(vVariant)
Get variant subtype
----------
Web Request Methods
These send GET or POST requests to web servers, retrieving strings or
saving to files.
WebRequest(sType, sUrl, dData, dHeaders, sUser, sPassword)
Send a web request and return the response
WebRequestGet(sUrl, dData, dHeaders, sUser, sPassword)
Send a get request
WebRequestGetToFile(sUrl, dData, dHeaders, sUser, sPassword, sFile)
Send a get request and save response to file
WebRequestGetToString(sUrl, dData, dHeaders, sUser, sPassword)
Send a get request and return response as string
WebRequestHead(sUrl, dData, dHeaders, sUser, sPassword)
Send a head request
WebRequestHeader(sUrl, sHeader)
Get response header
WebRequestPost(sUrl, dData, dHeaders, sUser, sPassword)
Send a post request
WebRequestPostToFile(sUrl, dData, dHeaders, sUser, sPassword, sFile)
Send a post request and save response to file
WebRequestPostToString(sUrl, dData, dHeaders, sUser, sPassword)
Send a post request and return response as string
WebRequestToFile(sType, sUrl, dData, dHeaders, sUser, sPassword, sFile)
Save web resource to file
WebRequestToString(sType, sUrl, dData, dHeaders, sUser, sPassword)
Return web resource as string
WebUrlContentType(sUrl)
Get content type of a web resource
WebUrlFileName(sUrl)
Get suggested file name of a web resource
WebUrlIsHtml()
Test whether content type is text/html
WebUrlToFile(sUrl, sFile)
Save web resource to file
WebUrlToString(sUrl)
Return web resource as string
----------
XML Methods
These read or write XML data, from memory or files.
XmlAppendElement(oParent, sName, sValue)
Append element to a node
XmlCreateElement(oNode, sName, sValue)
Create an XML element
XmlCreateFile(sFile)
Create a root XML file
XmlEnsureGetNode(oDoc, sPath)
Return a node, creating preceding elements if necessary
XmlEnsureOpenFile(sFile)
Open an XML file, creating it if necessary
XmlGetAttribute(sFile, sPath, sAttribute, sDefault)
Get an attribute of a node
XmlGetNode(sFile, sPath)
Get a node
XmlGetNodeNames(sFile, sPath)
Get node names
XmlGetNodes(sFile, sPath)
Get a node collection
XmlGetValue(sFile, sPath, sDefault)
Get a value of a node
XmlOpenFile(sFile)
Open an XML file
XmlRemoveAttribute(sFile, sPath)
Remove an attribute
XmlRemoveNode(sFile, sPath)
Remove a node
XmlRemoveNodes(sFile, sPath)
Remove a node collection
XmlSetAttribute(sFile, sPath, sAttribute, sText)
Set an attribute
XmlSetValue(sFile, sPath, sValue)
Set a value
----------
Development Notes
Thanks go to Bryan Garaventa for information on the MSXml2.XMLHTTP object,
and to Martin Slack for information on the System.Collections.ArrayList
object.
