LSW v0.6 - Runtime interpreter for Lingo scripts
======================================================

- WORK IN PROGRESS - USE TOTALLY AT YOUR OWN RISK!


1.) INSTALLING

Unzip lsw.zip, put folder to some final destination (e.g. C:\dev\lsw\), 
then run (double-click) "lsw_install.bat" to associate LSW scripts (*.lsw) with lsw.exe.
(Notice: previous assocation for *.lsw is overwritten). 

From now on you can run LSW scripts with double-click in explorer.


2.) UNINSTALLING

Run (double-click) "lsw_uninstall.bat" to remove the LSW script association from the 
Windows Registry (and delete the lsw-folder, if you don't want/need it anymore).


3) Core API (global functions):

- include(scriptFile, *forceType)
- import(libFolder, *name)
- extend(name, scriptFile)

-- Utilities --

- @(path)
- checkXtra (aName)
- isRelativePath (tPath)
- libDir (lib)
- methods (obj)
- sanitizePath (tPath)


a) include (tScriptFile, *tForceType)

-- Embeds script in castlib (if not available yet).
-- Uses line 1 type-comment for script type (or #parent as default).
-- Returns script reference.
--
-- @param {string} scriptFile - (absolute or relative) path to script file
-- @param {symbol} [forceType] - force script type (optional)
-- @return {script|false}


b) import (libFolder, *name)

-- Embeds script in castlib (if not available yet)
-- Creates new instance (if not available yet), puts it in $.basename (or $.name)
-- Returns instance
--
-- @param {string} libFolder - (abs. or rel.) path to folder, without trailing path delimiter
-- @param {string} [name] - if specified, instance is saved in $.<name> instead $.<basename> (optional)
-- @return {instance|false}


c) extend (name, scriptFile)

-- Extends $.<name> (fails if $.<name> doesn't exist)
-- embeds script in castlib (if not available yet)
-- creates new instance with existing $.<tName> as ancestor
-- replaces $.<name> with new instance
-- returns the new instance
--
-- @param {string} name
-- @param {string} scriptFile - (absolute or relative) path to script file
-- @return {instance|false}


d) @ (path)

-- Resolves relative path (relative to the main LSW script!) and abstract path delimiter "/", 
-- returns absolute path with path delimiter for current platform.
--
-- @param {string} path - (absolute or relative) path, path delimiter "/" allowed
-- @return {string} absolute path with OS specific path delimiter 

  Example:
  
  -- called in script "C:\dev\lsw\projects\projectx\main.lsw"
  put @("images/test.jpg")
  
  -- "C:\dev\lsw\projects\projectx\images\test.jpg")
  

4. Hints

a) Namespace

  To avoid collisions with other scripts, all LSW parameters and libraries use a  
  common namespace root: _global.$
  
  
b) Script entry point: on startMovie
  
  NOTICE: on prepareMovie is used internally and therefor not called in LSW scripts. But since
  the application starts window-less, you can just put your setup code in the startMovie handler,
  before making the window visible (if your script uses the stage window at all).
  
  
c) Importing libraries with import()

  "Libraries" are parent scripts (always named "index.ls" or "index.js) loaded with the 
  import() command. Such libraries are automatically instantiated, and the instance is saved
  as $.<name> (where <name> is either specified as  optional 2. argument, or otherwise the 
  basename  of the script, i.e. the filename without ".ls"/".js").
    
  If a library was already imported before, it's NOT imported again, but the existing
  version is returned instead.
  
  Although library index scripts are parent scripts, they are NOT classes! Parent 
  scripts are only used for having separate namespaces. But of cause libraries can provide
  classes. Here an example library "midi" that provides a class "Song":
  
	  -- lib/midi/index.ls
	  property Song
	  
	  ----------------------------------------
		-- @constructor
		----------------------------------------
		on new (me, tScriptDir)
		  Song = include(tScriptDir&"song.ls")
			return me
		end
		
		-- static library functions here
		-- ...
	  
	
	Usage in LSW script:
	
		midi = import("lib/midi")
		mySong = midi.Song.new()
  
	Alternatively, the library could provide a factory function that directly returns objects:

		midi = import("lib/midi")
		mySong = midi.newSong()
	
    
  Usage examples:
  
  -- loads library "foo", which can be accessed via $.foo
  import("lib/foo") 
  
  -- loads library "foo" and stores a reference in local var fooLib, so it can be accessed 
  either using $.foo or (locally) fooLib
  fooLib = import("lib/foo") 
  
  -- loads library "foo" but saves it as "bar", so I can be accessed via $.bar
  import("lib/foo", "bar") 
  

d) Extend libraries with extend()

  Example: 
  
  extend("foo", "lib/foo-extend.ls")

  If "foo-extend.ls" is a parent script, and $.foo already exists, it's "extended", i.e. 
  an instance of foo-extend is created using the existing $.foo library as ancestor, and then
  $.foo is replaced with that new insatnce (and the new instance is returned).
  
  
e) Include other script files using include(scriptFile, *forceType)

  Examples: 
  
  include("path/to/foo.ls")
  include("path/to/foo.ls", #parent)
  
  Includes a script file, and returns the script reference. The path of the script file can be 
  either absolute or relative to the LSW exe or to the main LSW script. 
  If forceType is specified, it's set as scripttype (#parent, #movie or #score), otherwise the function tries to read the type from a "type header" comment in the first line of the script:
  a comment starting with "!" right after the "--" (Lingo) or "//" (JavaScript), immediately 
  followed by the scripttype as string. If forceType isn't specified and no type vcomment is found,
  #movie is used as default.

  NOTICE: If the script was already included before, it's NOT included again, but the existing
  version is returned instead.


f) Show a console window (hidden by default) 

  either (raw command):
  
    _player.debugplaybackenabled = 1
    
  or use Console-lib API:
    
    c = import("lib/console.ls")
    c.show() -- or: $.console.show()
    
    Console-API:
    - show ()
    - remove ()
    - log (ar1, arg2, ...)
    - dir (obj)
    - timer (<name>)
    - timeEnd (<name>)
    (more to come)
  
  
g) Show the stage window (hidden by default)

  Adjust stage properties (rect, title, bg-color, ...) as desired, then call:
  
    updateStage()
    _movie.stage.visible = 1
    
  to display it.
  
  
h) Creating standalone projectors

  When "lsw.exe" is renamed to anything else (e.g. "foo.exe"), when started it looks for 
  a file  "<basename>.lsw" (e.g. "foo.lsw")in its directory, and if it exits, loads it. 

  So to create a standalone projector:
  1. copy your core LSW script (e.g."foo.lsw") to a new folder (e.g. "foo_dist")
  2. create a sub folder "lib", and copy all libs (=either individual files or folders) 
     from the global LSW-lib folder (e.g. C:\dev\lsw\lib) to that local lib folder.
  3. copy additional scripts and assets used in your project into that folder
  4. copy "lsw.exe" into the that folder, and change its basename to the basename of your 
     core LSW script (e.g. "foo.exe")
  5. Done! You should now be able to run you project by double-clicking the exe ("foo.exe")
  
  Shell script "editor_make_standalone.bat" in the examples folder shows how you can
  automate that process, when executed it creates a new standalone version of the 
  "editor"-demo in a new folder "editor_standalone".