Provide an API for registering custom APIs

ILuaAPI has been moved to dan200.computercraft.api.lua. One creates
a new API by registering an instance of ILuaAPIFactory. This takes an
instance of IComputerSystem and returns such an API.

IComputerSystem is an extension of IComputerAccess, with methods to
access additional information about the the computer, such as its label
and filesystem.

src/main/java/dan200/computercraft/ComputerCraft.java

@@ -9,6 +9,7 @@
import com.google.common.base.CaseFormat;
import dan200.computercraft.api.filesystem.IMount;
import dan200.computercraft.api.filesystem.IWritableMount;
import dan200.computercraft.api.lua.ILuaAPIFactory;
import dan200.computercraft.api.media.IMedia;
import dan200.computercraft.api.media.IMediaProvider;
import dan200.computercraft.api.network.IPacketNetwork;
@@ -81,10 +82,7 @@
import java.net.MalformedURLException;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.*;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;

@@ -244,6 +242,7 @@
    private static List<IMediaProvider> mediaProviders = new ArrayList<>();
    private static List<ITurtlePermissionProvider> permissionProviders = new ArrayList<>();
    private static final Map<String, IPocketUpgrade> pocketUpgrades = new HashMap<>();
    private static final Set<ILuaAPIFactory> apiFactories = new LinkedHashSet<>();

    // Implementation
    @Mod.Instance( value = ComputerCraft.MOD_ID )
@@ -644,6 +643,14 @@ public static void registerMediaProvider( IMediaProvider provider )
        }
    }

    public static void registerAPIFactory( ILuaAPIFactory provider )
    {
        if( provider != null )
        {
            apiFactories.add( provider );
        }
    }

    public static IPeripheral getPeripheralAt( World world, BlockPos pos, EnumFacing side )
    {
        // Try the handlers in order:
@@ -771,6 +778,11 @@ public IPacketNetwork getWirelessNetwork()
        return WirelessNetwork.getUniversal();
    }

    public static Iterable<ILuaAPIFactory> getAPIFactories()
    {
        return apiFactories;
    }

    public static int createUniqueNumberedSaveDir( World world, String parentSubPath )
    {
        return IDAssigner.getNextIDFromDirectory(new File(getWorldDir(world), parentSubPath));

src/main/java/dan200/computercraft/api/ComputerCraftAPI.java

@@ -8,6 +8,7 @@

import dan200.computercraft.api.filesystem.IMount;
import dan200.computercraft.api.filesystem.IWritableMount;
import dan200.computercraft.api.lua.ILuaAPIFactory;
import dan200.computercraft.api.media.IMedia;
import dan200.computercraft.api.media.IMediaProvider;
import dan200.computercraft.api.network.IPacketNetwork;
@@ -311,6 +312,22 @@ public static IPacketNetwork getWirelessNetwork()
        return null;
    }

    public static void registerAPIFactory( @Nonnull ILuaAPIFactory upgrade )
    {
        findCC();
        if( computerCraft_registerAPIFactory != null )
        {
            try
            {
                computerCraft_registerAPIFactory.invoke( null, upgrade );
            }
            catch( Exception e )
            {
                // It failed
            }
        }
    }

    // The functions below here are private, and are used to interface with the non-API ComputerCraft classes.
    // Reflection is used here so you can develop your mod without decompiling ComputerCraft and including
    // it in your solution, and so your mod won't crash if ComputerCraft is installed.
@@ -354,6 +371,9 @@ private static void findCC()
                } );
                computerCraft_getWirelessNetwork = findCCMethod( "getWirelessNetwork", new Class<?>[] {
                } );
                computerCraft_registerAPIFactory = findCCMethod( "registerAPIFactory", new Class<?>[] {
                    ILuaAPIFactory.class
                } );
            } catch( Exception e ) {
                System.out.println( "ComputerCraftAPI: ComputerCraft not found." );
            } finally {
@@ -390,4 +410,5 @@ private static Method findCCMethod( String name, Class<?>[] args )
    private static Method computerCraft_registerPermissionProvider = null;
    private static Method computerCraft_registerPocketUpgrade = null;
    private static Method computerCraft_getWirelessNetwork = null;
    private static Method computerCraft_registerAPIFactory = null;
}

src/main/java/dan200/computercraft/api/filesystem/IFileSystem.java

@@ -0,0 +1,38 @@
package dan200.computercraft.api.filesystem;

import java.io.IOException;

/**
 * Provides a mount of the entire computer's file system.
 *
 * This exists for use by various APIs - one should not attempt to mount it.
 */
public interface IFileSystem extends IWritableMount
{
    /**
     * Combine two paths together, reducing them into a normalised form.
     *
     * @param path  The main path.
     * @param child The path to append.
     * @return The combined, normalised path.
     */
    String combine( String path, String child );

    /**
     * Copy files from one location to another.
     *
     * @param from The location to copy from.
     * @param to   The location to copy to. This should not exist.
     * @throws IOException If the copy failed.
     */
    void copy( String from, String to ) throws IOException;

    /**
     * Move files from one location to another.
     *
     * @param from The location to move from.
     * @param to   The location to move to. This should not exist.
     * @throws IOException If the move failed.
     */
    void move( String from, String to ) throws IOException;
}

src/main/java/dan200/computercraft/api/lua/IComputerSystem.java

@@ -0,0 +1,29 @@
package dan200.computercraft.api.lua;

import dan200.computercraft.api.filesystem.IFileSystem;
import dan200.computercraft.api.peripheral.IComputerAccess;

import javax.annotation.Nullable;

/**
 * An interface passed to {@link ILuaAPIFactory} in order to provide additional information
 * about a computer.
 */
public interface IComputerSystem extends IComputerAccess
{
    /**
     * Get the file system for this computer.
     *
     * @return The computer's file system, or {@code null} if it is not initialised.
     */
    @Nullable
    IFileSystem getFileSystem();

    /**
     * Get the label for this computer
     *
     * @return This computer's label, or {@code null} if it is not set.
     */
    @Nullable
    String getLabel();
}

src/main/java/dan200/computercraft/api/lua/ILuaAPI.java

@@ -0,0 +1,47 @@
/*
 * This file is part of ComputerCraft - http://www.computercraft.info
 * Copyright Daniel Ratcliffe, 2011-2016. Do not distribute without permission.
 * Send enquiries to dratcliffe@gmail.com
 */

package dan200.computercraft.api.lua;

import dan200.computercraft.api.ComputerCraftAPI;

/**
 * Represents a {@link ILuaObject} which is stored as a global variable on computer startup.
 *
 * Before implementing this interface, consider alternative methods of providing methods. It is generally preferred
 * to use peripherals to provide functionality to users.
 *
 * @see ILuaAPIFactory
 * @see ComputerCraftAPI#registerAPIFactory(ILuaAPIFactory)
 */
public interface ILuaAPI extends ILuaObject
{
    /**
     * Get the globals this API will be assigned to. This will override any other global, so you should
     *
     * @return A list of globals this API will be assigned to.
     */
    String[] getNames();

    /**
     * Called when the computer is turned on.
     *
     * One should only interact with the file system.
     */
    default void startup() { }

    /**
     * Called every time the computer is ticked. This can be used to process various.
     */
    default void update() { }

    /**
     * Called when the computer is turned off or unloaded.
     *
     * This should reset the state of the object, disposing any remaining file handles, or other resources.
     */
    default void shutdown() { }
}

src/main/java/dan200/computercraft/api/lua/ILuaAPIFactory.java

@@ -0,0 +1,24 @@
package dan200.computercraft.api.lua;

import dan200.computercraft.api.ComputerCraftAPI;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Construct an {@link ILuaAPI} for a specific computer.
 *
 * @see ILuaAPI
 * @see ComputerCraftAPI#registerAPIFactory(ILuaAPIFactory)
 */
public interface ILuaAPIFactory
{
    /**
     * Create a new API instance for a given computer.
     *
     * @param computer The computer this API is for.
     * @return The created API, or {@code null} if one should not be injected.
     */
    @Nullable
    ILuaAPI create( @Nonnull IComputerSystem computer );
}

src/main/java/dan200/computercraft/core/apis/BitAPI.java

@@ -6,6 +6,7 @@

package dan200.computercraft.core.apis;

import dan200.computercraft.api.lua.ILuaAPI;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;

@@ -37,21 +38,6 @@ public BitAPI( IAPIEnvironment _environment )
            "bit"
        };
    }

    @Override
    public void startup( )
    {
    }

    @Override
    public void advance( double _dt )
    {
    }
    
    @Override
    public void shutdown( )
    {
    }
    
    @Nonnull
    @Override

src/main/java/dan200/computercraft/core/apis/BufferAPI.java

@@ -6,6 +6,7 @@

package dan200.computercraft.core.apis;

import dan200.computercraft.api.lua.ILuaAPI;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.ILuaObject;
import dan200.computercraft.api.lua.LuaException;
@@ -100,21 +101,6 @@ public BufferAPI( IAPIEnvironment _env )
        };
    }

    @Override
    public void startup()
    {
    }

    @Override
    public void advance( double _dt )
    {
    }

    @Override
    public void shutdown()
    {
    }

    @Nonnull
    @Override
    public String[] getMethodNames()